🚀 Using DocSearch v4 beta with Docusaurus & VitePress

[dylantientcheu]

Important

Heads-up: v4 is still in beta. Expect sharp edges and please report anything odd! We’ll iterate quickly based on your feedback. ❤️

---

✨ What’s new in v4?

• Chat-style “Ask AI” answers (optional, powered by your own LLM key)

• Updated default theme & a11y improvements

---

1. Docusaurus (v4 beta)

1-a Create or open your site

npx create-docusaurus@latest my-docs classic
cd my-docs

1-b Swap in the v4 beta tarballs

Edit package.json and replace the usual deps:

- "@docusaurus/core": "3.x.x",
- "@docusaurus/preset-classic": "3.x.x",
+ "@docusaurus/core": "https://github.com/algolia/docsearch/releases/download/v4.0.0-beta.4/docusaurus-core-3.8.1.tgz",
+ "@docusaurus/preset-classic": "https://github.com/algolia/docsearch/releases/download/v4.0.0-beta.4/docusaurus-preset-classic-3.8.1.tgz"

Because those tarballs pull other Docusaurus internals, add a resolutions block (Yarn/PNPM) or the npm-equivalent overrides:

"resolutions": {
  "@docusaurus/utils": "https://github.com/algolia/docsearch/releases/download/v4.0.0-beta.4/docusaurus-utils-3.8.1.tgz",
  "@docusaurus/theme-search-algolia": "https://github.com/algolia/docsearch/releases/download/v4.0.0-beta.4/docusaurus-theme-search-algolia-3.8.1.tgz",
  "@docusaurus/theme-translations": "https://github.com/algolia/docsearch/releases/download/v4.0.0-beta.4/docusaurus-theme-translations-3.8.1.tgz"
}

Then install:

npm i      # or yarn / pnpm

1-c Configure DocSearch (and optional Ask AI)

In docusaurus.config.js:

themeConfig: {
  algolia: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    // --- v4 Ask AI (optional) ---
    askAi: 'YOUR_ASSISTANT_ID' // ← remove if you don’t need Ask AI
  },
},

💡 Full options: https://docusaurus.io/docs/search#connecting-algolia

See it live

Fork / play with this Codesandbox: https://codesandbox.io/p/devbox/7vmqn4

---

2. VitePress (v4 beta)

Use the latest VitePress alpha

---

🤔 FAQ / Trouble-shooting

Problem	Quick fix
Peer-dep version errors	Make sure you copied every URL in the resolutions block.
Yarn gives “Cannot find package”	Yarn v1 needs yarn add after adding resolutions.
More deps issues	If you are using any other docusaurus package. Create its own tarball by pulling this PR facebook/docusaurus#11327. yarn build. Then cd packages/<your_package>. and run npm pack, copy the tarball in your project and use it in your package json @docusaurus/your-plugin: "file:./your-plugin-3.8.1.tgz.
Ask AI isn’t answering	Check that assistantId matches an enabled assistant in your Algolia dashboard and that you’ve supplied your own LLM API key.

---

🙏 We need your feedback!

• Does the tarball approach work smoothly on your infra (CI, lockfile, etc.)?

• Any missing peer-deps or TypeScript errors?

• Are the Ask AI defaults sensible? What would you tweak?

Please drop comments below or open issues with the v4-beta label.
Happy hacking! 🔍✨

Note

This is only temporary patch, we are working with Docusaurus/VitePress to get these through their next release cycle if possible.

[dylantientcheu]

🚀 Update: VitePress' PR is now merged, use the latest VitePress alpha to enjoy DocSearch v4 native integration.

[trad-alrowais]

@terad_alrowais

[trad-alrowais]

@trad-alrowais