v1.0.0

Introduction

This page records the v1 release and its migration path. For a new installation, use the current guide.

Nuxt AI Ready v1 renamed configuration and hooks, changed endpoint authentication, and adopted mdream v1.

The migration to mdream v1 changed HTML-to-Markdown options. The release also unified heading types and fixed cron locking.

Most breaking changes have a backward compatibility layer that emits deprecation warnings, for the deprecated patterns listed below. See the full migration steps and compat shims below, or paste the agent migration prompt into your AI coding tool to prepare the migration. Review its changes before deploying.

🧠 Mdream v1

The HTML to Markdown engine has been rewritten. mdream v1 ships a native Rust engine, WebAssembly for edge runtimes, and a simpler declarative API while keeping the JS engine available as @mdream/js for users who need imperative hook based plugins. The preset option is replaced by top-level flags, and extraction plugins are now declarative objects instead of function wrappers.

export default defineNuxtConfig({
  aiReady: {
    mdreamOptions: {
      minimal: true,
      clean: true
    }
  }
})

📊 Enhanced CLI Status

The nuxt-ai-ready status command now shows richer diagnostics: activity stats (1h/24h), recent pages, IndexNow backoff status, cron run history, and sitemap health.

🔐 Shared Auth Utility

Endpoint authentication is consolidated into a single requireAuth() utility, replacing duplicated auth logic across 6 route handlers.

⚠️ Breaking Changes

Dependency Version Bumps

The following internal dependencies have new minimum versions. Check their release notes for changes that affect your configuration.

• nuxt-site-config v4: breaking changes
• @nuxtjs/robots v6: breaking changes
• @nuxtjs/sitemap v8: breaking changes

mdream Options Shape

mdreamOptions changed from HTMLToMarkdownOptions & { preset?: 'minimal' } to the new MdreamOptions type from mdream v1. The preset key no longer exists.

 aiReady: {
-  mdreamOptions: { preset: 'minimal' },
+  mdreamOptions: { minimal: true },
 }

Config Rename

cacheMaxAgeSeconds is now llmsTxtCacheSeconds to clarify it only controls the llms.txt cache, not markdown route caching.

 aiReady: {
-  cacheMaxAgeSeconds: 600,
+  llmsTxtCacheSeconds: 600,
 }

Type Rename

BulkDocument is now PageDocument.

-import type { BulkDocument } from 'nuxt-ai-ready'
+import type { PageDocument } from 'nuxt-ai-ready'

Hook Rename

The Nitro runtime hook ai-ready:markdown is now ai-ready:page:markdown, matching the build-time hook name.

-nitroApp.hooks.hook('ai-ready:markdown', (ctx) => {
+nitroApp.hooks.hook('ai-ready:page:markdown', (ctx) => {
   ctx.markdown += '\n\nCustom footer'
 })

Headings Type Unified

PageEntry.headings and PageIndexedContext.headings changed from string (JSON) to Array<Record<string, string>> (already parsed). Remove any JSON.parse() calls on .headings.

 const page = await queryPages(event, { route: '/about' })
-const headings = JSON.parse(page.headings)
+const headings = page.headings // already parsed

Endpoint Auth: Header Instead of Query String

Protected /__ai-ready/* endpoints now require an Authorization: Bearer <token> header instead of ?secret=<token> in the query string. This prevents secrets from leaking into server logs and referrer headers.

-fetch('/__ai-ready/poll?secret=TOKEN', { method: 'POST' })
+fetch('/__ai-ready/poll', {
+  method: 'POST',
+  headers: { Authorization: 'Bearer TOKEN' },
+})

-curl -X POST "https://site.com/__ai-ready/poll?secret=TOKEN"
+curl -H "Authorization: Bearer TOKEN" -X POST "https://site.com/__ai-ready/poll"

Update CI scripts, external cron jobs, or monitoring tools that call protected endpoints. Prune dry runs did not require authentication.

🛟 Migration Assistance

v1 includes a backward compatibility layer to ease migration. The following deprecated patterns still work but emit warnings:

• cacheMaxAgeSeconds in nuxt.config.ts is auto-mapped to llmsTxtCacheSeconds with a build warning
• mdreamOptions.preset triggers a build warning explaining the new shape
• ?secret=<token> query auth still works on protected /__ai-ready/* endpoints but logs a deprecation warning per request

The v1 release planned to remove these shims in v2. This is a historical migration note, not a statement of current shim support. Use the renamed configuration and Bearer header in new code.

🐛 Bug Fixes

• Cron lock race condition fixed with atomic INSERT ... ON CONFLICT DO UPDATE ... WHERE instead of check-then-set (854551f)
• Unsafe JSON.parse calls replaced with safeJsonParse() across query layer (854551f)
• Input validation added to poll, prune, and indexnow endpoints (limit, timeout, ttl clamping) (854551f)
• console.warn replaced with logger.warn in cron runner (854551f)
• Markdown cache now varies by Accept headers (f513c08)

Agent Migration Prompt

Copy this prompt into your AI coding agent (Claude Code, Cursor, Copilot, etc.) to prepare the v1 migration:

I'm upgrading nuxt-ai-ready to v1. Apply these breaking changes to my codebase:

1. mdream options: `mdreamOptions` in nuxt.config.ts changed shape. Replace `{ preset: 'minimal' }` with `{ minimal: true }`. The type changed from `HTMLToMarkdownOptions` to `MdreamOptions`.

2. Config rename: `cacheMaxAgeSeconds` is now `llmsTxtCacheSeconds` in nuxt.config.ts under the `aiReady` key.

3. Type rename: `BulkDocument` is now `PageDocument`. Update all imports from 'nuxt-ai-ready'.

4. Hook rename: The Nitro runtime hook `ai-ready:markdown` is now `ai-ready:page:markdown`. Update all hooks.hook() and hooks.callHook() calls.

5. Headings type change: `PageEntry.headings` and `PageIndexedContext.headings` changed from `string` (JSON) to `Array<Record<string, string>>` (parsed). Remove any JSON.parse() calls on .headings since it's now already parsed.

6. Auth mechanism change: Protected `/__ai-ready/*` endpoints now use `Authorization: Bearer <token>` header instead of `?secret=<token>` query parameter. Update any fetch calls, curl commands, CI scripts, or external cron jobs that hit these endpoints.

Note: v1 includes backward compatibility shims for `cacheMaxAgeSeconds`, `mdreamOptions.preset`, and `?secret=` query auth. These emit deprecation warnings. The v1 release planned their removal in v2; verify support against the target version. After applying changes, verify no deprecation warnings remain in your build output or server logs.

Search my entire codebase for these patterns and apply all necessary changes.