vitepress-plugin-cloudflare-ai-search

Replace the VitePress default-theme search with Cloudflare AI Search. Read Bringing Cloudflare AI Search to Docus and VitePress for the story behind the package family.

• Replaces the default navbar search without changing your theme.
• Uses Cloudflare’s official search-modal-snippet component.
• Supports Cloudflare’s built-in keyboard shortcut, favorites, and analytics.
• Follows VitePress light and dark mode unless you choose a theme.

Installation

pnpm add vitepress-plugin-cloudflare-ai-search

Usage

Add the plugin to the VitePress vite.plugins array:

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { cloudflareAISearch } from 'vitepress-plugin-cloudflare-ai-search'

export default defineConfig({
  vite: {
    plugins: [
      cloudflareAISearch({
        endpoint: 'https://search.example.com',
      }),
    ],
  },
})

[!NOTE]
Do not configure themeConfig.search. This plugin replaces VitePress’s local or Algolia search UI.

Options

cloudflareAISearch({
  endpoint: 'https://search.example.com',
  placeholder: 'Search the docs',
  theme: 'auto',
  maxResults: 10,
  disableAnalytics: true,
  cssVariables: {
    '--search-snippet-primary-color': '#646cff',
  },
})

Option	Description
endpoint	Required. Public AI Search endpoint root.
placeholder, maxResults, maxRenderResults, debounceMs	Search input and result-list behavior.
theme	light, dark, or auto. Omit it to synchronize with VitePress.
hideBranding, showUrl, showDate, hideThumbnails, groupBy, seeMore	Cloudflare search result presentation.
shortcut, useMetaKey	Keyboard shortcut customization. Defaults to k and true.
requestOptions	Additional public request fields, headers, and query parameters.
disableAnalytics	Disables Cloudflare analytics. Analytics are enabled by default.
translations	Cloudflare modal translations. searchButtonLabel also controls the navbar label.
cssVariables	--search-snippet-* properties forwarded to the component host for Shadow DOM styling.

The navbar label uses translations.searchButtonLabel, then placeholder, then Search.

[!WARNING]
The endpoint and every option are sent to the browser. Never add API tokens, Authorization values, Cloudflare Access service-token secrets, or other credentials to requestOptions.

Cloudflare setup

Create an AI Search instance, enable its public /search endpoint, and add your development and production origins to its authorized hosts. Index only content that is safe to expose publicly.

Use cloudflare-ai-search-sync to index VitePress pages during builds.

Related packages

• cloudflare-ai-search-sync synchronizes VitePress, Nuxt Content, and Markdown with Cloudflare AI Search.
• docus-cloudflare-ai-search provides the equivalent search UI for Docus.

Sponsors

License

MIT License © 2026-PRESENT Estéban Soubiran