Migration guide

A note on version numbers: the published npm history for this package goes 0.3.0 → 0.3.3 → 0.4.0 — 0.3.1 and 0.3.2 exist in CHANGELOG.mdand are real, documented changes, but aren't independently installable from the registry today. If you're upgrading from 0.3.0 directly to 0.4.0, you're picking up everything below from 0.3.1 through 0.4.0 in one jump — read all of it, not just the 0.4.0 section.

0.3.x → 0.4.0

Crawler tokens changed — check for Claude-Web

The entire crawler registry was re-verified against vendor documentation instead of third-party SEO-blog lists. Claude-Web, Anthropic's pre-2024 token, was removed and replaced by the current Claude-User. If you match on crawler User-Agent strings anywhere in your own code — not just through this package's detector — search for Claude-Web and replace it:

// Before
if (userAgent.includes("Claude-Web")) { /* ... */ }

// After
if (userAgent.includes("Claude-User")) { /* ... */ }

Six crawlers were added: OAI-SearchBot, Claude-SearchBot, Perplexity-User, Amazonbot, Amzn-SearchBot, Amzn-User — see the crawler registry reference for the full, current list of 21.

detectAndOptimize() moved (0.3.1)

If you're on 0.3.0 and importing detectAndOptimize from anywhere other than a Next.js project, the import itself was crashing — see the troubleshooting entry for the fix (import from ai-visibility/detector instead of /next). Existing ai-visibility/next imports keep working unchanged — this is additive, not a breaking rename.

onDetect is now safely async (0.4.0)

createNextMiddleware()'s onDetect may now return a Promise<void> and gets registered with event.waitUntil() automatically. No code change required — this only matters if you had an async onDetectthat seemed to work in testing but silently dropped writes in production; it's reliable now.

Subpath type exports completed (0.4.0)

ai-visibility/schema, /generators, and /express now re-export their parameter types (ProductSchemaData, RobotsConfig, AIMiddlewareConfig, etc.), not just their classes/functions. If you were importing a type from the root barrel purely to pair with a subpath import, you can now import both from the same subpath — not required, but simplifies the import list.

0.2.x → 0.3.x

robots.txt default disallow list is now empty

The change most likely to affect you. RobotsGenerator's default disallow list used to include /_next, /admin, /api, /private, and /static — meaning every site using the defaults, Next.js apps especially, was shipping a robots.txtthat told AI crawlers not to fetch the site's own JS/CSS chunks. The default is now []. If you relied on the old default, pass your own disallow list explicitly:

new RobotsGenerator({
  allowAI: ["GPTBot", "ClaudeBot", "PerplexityBot"],
  disallow: ["/admin", "/api"], // now explicit, not implied
})

SchemaBuilder.fromHTML() is now async

fromHTML() lazily import()s cheerio on first call instead of requiring it statically, so it now returns Promise<SchemaObject> instead of SchemaObject directly. Add awaitif you weren't already using it:

// Before (0.2.x)
const schema = SchemaBuilder.fromHTML(html);

// After (0.3.0+)
const schema = await SchemaBuilder.fromHTML(html);

Subpath exports added (non-breaking)

ai-visibility/detector, /schema, /generators, /express, and /next were added alongside the root barrel, which is unchanged — every 0.2.x import path still works with no code changes. Switching to subpath imports is worth doing for edge runtimes (Cloudflare Workers, Next.js Edge Middleware) since /detector, /schema, and /generatorshave zero runtime dependencies; it's optional everywhere else.

Full entry-by-entry detail for every release is in the package's CHANGELOG.md. See recipes for current working examples and troubleshooting for gotchas specific to individual frameworks.