0.2.0 • Published 10h ago

cloudflare-ai-search-sync

Licence

MIT

Version

0.2.0

Deps

Size

28 kB

Vulns

Weekly

Summary Dependency Versions

cloudflare-ai-search-sync

Synchronize Markdown and Nuxt Content with Cloudflare AI Search. Read Bringing Cloudflare AI Search to Docus and VitePress for the story behind the package family.

Index Markdown from Vite, VitePress 2, or Nuxt Content.
Resolve public URLs from each framework's routing configuration.
Keep Cloudflare's built-in source in sync with the completed local snapshot.
Configure the metadata used by the Cloudflare AI Search snippet.

Installation

pnpm add cloudflare-ai-search-sync

Usage

The adapters are disabled by default. Enable synchronization with enabled: true or CLOUDFLARE_AI_SEARCH_SYNC_ENABLED=true. An explicit option takes precedence over the environment variable.

VitePress

Use the native VitePress 2 buildEnd hook:

// .vitepress/config.ts
import { cloudflareAISearchSync } from 'cloudflare-ai-search-sync/vitepress'
import { defineConfig } from 'vitepress'

export default defineConfig({
  buildEnd: cloudflareAISearchSync({ enabled: true }),
})

The adapter resolves base, rewrites, and cleanUrls before uploading each page.

Nuxt Content

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
    'cloudflare-ai-search-sync/nuxt',
  ],
  cloudflareAISearchSync: { enabled: true },
})

The module runs during nuxt build and nuxt generate, never during nuxt dev. It indexes published Markdown documents from Nuxt Content page collections and excludes documents with draft: true, including drafts stored in meta.

Vite filesystem

Synchronize a folder of Markdown files after successful Vite builds:

// vite.config.ts
import { cloudflareAISearchSync } from 'cloudflare-ai-search-sync/fs'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    cloudflareAISearchSync({
      enabled: true,
      folder: './docs',
    }),
  ],
})

Relative folders resolve from the Vite project root. Set cleanUrls: true to omit .html from non-index routes.

Custom integrations

The root export provides synchronizeItems, syncItems, ensureItemMetadata, toPublicUrl, siteRoot, isSyncEnabled, and getCloudflareClient for custom content sources.

Cloudflare setup

Provide the following build-only environment variables:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_AI_SEARCH_INSTANCE_ID=
CLOUDFLARE_AI_SEARCH_NAMESPACE=
CLOUDFLARE_AI_SEARCH_SYNC_ENABLED=true

The API token needs Account / AI Search:Edit and Account / AI Search:Run permissions. Never expose these credentials through Vite client configuration, Nuxt public runtime configuration, or a browser bundle.

Vite loads variables from its resolved mode and environment directory. VitePress loads production variables from the site root. Nuxt reads the build process environment. Explicit adapter options take precedence in every integration.

The adapters upload the complete local snapshot before deleting stale items from the AI Search builtin source. This includes manually uploaded built-in items. An empty snapshot therefore deletes all built-in items.

vitepress-plugin-cloudflare-ai-search replaces VitePress 2 search with the Cloudflare AI Search UI.
docus-cloudflare-ai-search replaces Docus search with Cloudflare AI Search.