294 lines
8.5 KiB
Text
294 lines
8.5 KiB
Text
---
|
|
title: Migrate from DocSearch v4
|
|
description: Move a DocSearch v4 integration to the v5 and Agent Studio APIs.
|
|
---
|
|
|
|
import TabItem from '@theme/TabItem';
|
|
import Tabs from '@theme/Tabs';
|
|
|
|
DocSearch v5 separates keyword search from the AI experience and uses Agent Studio for Ask AI. Plan the migration around the experience your site provides.
|
|
|
|
Review the complete [v5 breaking changes](./v5-breaking-changes) before releasing.
|
|
|
|
## 1. Upgrade packages
|
|
|
|
Upgrade every DocSearch package in the integration together with the `^5` range.
|
|
|
|
<Tabs groupId="language" aria-label="Programming language">
|
|
<TabItem value="react" label="React">
|
|
|
|
<Tabs groupId="package-manager" aria-label="Package manager">
|
|
<TabItem value="npm" label="npm">
|
|
|
|
```bash
|
|
npm install @docsearch/react@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="yarn" label="Yarn">
|
|
|
|
```bash
|
|
yarn add @docsearch/react@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="pnpm" label="pnpm">
|
|
|
|
```bash
|
|
pnpm add @docsearch/react@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="bun" label="Bun">
|
|
|
|
```bash
|
|
bun add @docsearch/react@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
</TabItem>
|
|
<TabItem value="js" label="JavaScript">
|
|
|
|
<Tabs groupId="package-manager" aria-label="Package manager">
|
|
<TabItem value="npm" label="npm">
|
|
|
|
```bash
|
|
npm install @docsearch/js@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="yarn" label="Yarn">
|
|
|
|
```bash
|
|
yarn add @docsearch/js@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="pnpm" label="pnpm">
|
|
|
|
```bash
|
|
pnpm add @docsearch/js@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="bun" label="Bun">
|
|
|
|
```bash
|
|
bun add @docsearch/js@^5 @docsearch/css@^5
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
If you use the Composable API or Sidepanel, also upgrade `@docsearch/core@^5`, `@docsearch/modal@^5`, `@docsearch/sidepanel@^5`, or `@docsearch/sidepanel-js@^5`.
|
|
|
|
## 2. Choose keyword-only or AI-capable search
|
|
|
|
### JavaScript without Ask AI
|
|
|
|
The v4 root export rendered the combined component. In v5, the root export is AI-capable and the `/docsearch` subpath is keyword-only.
|
|
|
|
Change the import:
|
|
|
|
```diff title="app.js"
|
|
-import docsearch from '@docsearch/js';
|
|
+import docsearch from '@docsearch/js/docsearch';
|
|
```
|
|
|
|
Your keyword options can remain unchanged while you migrate deprecated options in a later step.
|
|
|
|
For a CDN integration, replace the root bundle with the keyword-only UMD file:
|
|
|
|
```diff title="index.html"
|
|
-<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
|
|
+<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@^5/dist/umd/docsearch.js"></script>
|
|
```
|
|
|
|
### JavaScript with Ask AI
|
|
|
|
Keep the root import. It now renders the AI-capable `DocSearchAI` component:
|
|
|
|
```js title="app.js"
|
|
import docsearch from '@docsearch/js';
|
|
|
|
docsearch({
|
|
container: '#docsearch',
|
|
appId: 'YOUR_APP_ID',
|
|
apiKey: 'YOUR_SEARCH_API_KEY',
|
|
indices: ['YOUR_INDEX_NAME'],
|
|
askAi: {
|
|
agentId: 'YOUR_AGENT_ID',
|
|
},
|
|
});
|
|
```
|
|
|
|
For a CDN integration, use `dist/umd/index.js`. It exposes `window.docsearch`, as v4 did.
|
|
|
|
### React without Ask AI
|
|
|
|
Keep `DocSearch`, but remove any AI props. In v5 it renders keyword search only:
|
|
|
|
```jsx title="Search.jsx"
|
|
import { DocSearch } from '@docsearch/react';
|
|
|
|
<DocSearch
|
|
appId="YOUR_APP_ID"
|
|
apiKey="YOUR_SEARCH_API_KEY"
|
|
indices={['YOUR_INDEX_NAME']}
|
|
/>;
|
|
```
|
|
|
|
### React with Ask AI
|
|
|
|
Replace `DocSearch` with `DocSearchAI`:
|
|
|
|
```diff title="Search.jsx"
|
|
-import { DocSearch } from '@docsearch/react';
|
|
+import { DocSearchAI } from '@docsearch/react';
|
|
|
|
-<DocSearch
|
|
+<DocSearchAI
|
|
appId="YOUR_APP_ID"
|
|
apiKey="YOUR_SEARCH_API_KEY"
|
|
indices={['YOUR_INDEX_NAME']}
|
|
askAi={{ agentId: 'YOUR_AGENT_ID' }}
|
|
/>
|
|
```
|
|
|
|
`DocSearchAI` requires `askAi`. The string shorthand remains supported:
|
|
|
|
```jsx title="Search.jsx"
|
|
<DocSearchAI askAi="YOUR_AGENT_ID" {...searchProps} />
|
|
```
|
|
|
|
## 3. Move Ask AI to Agent Studio
|
|
|
|
V5 removes the legacy Ask AI token and chat transport. Create the agent in [Agent Studio](/docs/agent-studio/getting-started) before switching production traffic. If you already have an Ask AI assistant, follow [Migrate Ask AI to Agent Studio](/docs/agent-studio/migrate-to-agent-studio).
|
|
|
|
Rename `assistantId` to `agentId`. Remove `agentStudio` from `askAi`. Agent Studio is the only Ask AI backend in v5.
|
|
|
|
```diff title="app.js"
|
|
askAi: {
|
|
- assistantId: 'YOUR_ASSISTANT_ID',
|
|
+ agentId: 'YOUR_AGENT_ID',
|
|
- agentStudio: true,
|
|
}
|
|
```
|
|
|
|
The v4 Agent Studio form keyed search parameters by index name. V5 keeps that shape and removes the legacy flat form:
|
|
|
|
```diff title="app.js"
|
|
askAi: {
|
|
- assistantId: 'YOUR_ASSISTANT_ID',
|
|
+ agentId: 'YOUR_AGENT_ID',
|
|
searchParameters: {
|
|
- filters: 'language:en',
|
|
- attributesToRetrieve: ['title', 'content', 'url'],
|
|
+ docs: {
|
|
+ filters: 'language:en',
|
|
+ attributesToRetrieve: ['title', 'content', 'url'],
|
|
+ },
|
|
},
|
|
}
|
|
```
|
|
|
|
Agent Studio search parameters support `filters`, `attributesToRetrieve`, `restrictSearchableAttributes`, and `distinct`. They don't support `facetFilters` in this object. Put fixed facet conditions in `filters`, or configure dynamic Agent Studio indices.
|
|
|
|
V5 adds `askAi.indices`, `askAi.tools`, `askAi.memory`, and `askAi.promptSuggestions`. Keep all Agent Studio configuration inside `askAi`. Keep `interceptAskAiEvent` at the component or `docsearch()` root because it controls view routing.
|
|
|
|
## 4. Move keyword configuration to `indices`
|
|
|
|
`indexName` and root `searchParameters` both have been removed in `v5`.
|
|
|
|
```diff title="app.js"
|
|
docsearch({
|
|
appId: 'YOUR_APP_ID',
|
|
apiKey: 'YOUR_SEARCH_API_KEY',
|
|
- indexName: 'docs',
|
|
- searchParameters: {
|
|
- facetFilters: ['language:en'],
|
|
- },
|
|
+ indices: [
|
|
+ {
|
|
+ name: 'docs',
|
|
+ searchParameters: {
|
|
+ facetFilters: ['language:en'],
|
|
+ },
|
|
+ },
|
|
+ ],
|
|
});
|
|
```
|
|
|
|
Use one item per index. DocSearch queries them in array order.
|
|
|
|
## 5. Update result customization
|
|
|
|
Existing `transformItems`, `hitComponent`, `resultsFooterComponent`, `transformSearchClient`, navigation, Insights, and translation props remain available.
|
|
|
|
V5 changes the result markup and adds breadcrumbs, source sections, facets, and badges. Review custom CSS, DOM selectors, screenshots, and tests that depend on v4 markup.
|
|
|
|
To show a badge from a custom record property, add the property to the per-index `attributesToRetrieve`, then set `resultBadgeKey`:
|
|
|
|
```jsx title="Search.jsx"
|
|
<DocSearch
|
|
appId="YOUR_APP_ID"
|
|
apiKey="YOUR_SEARCH_API_KEY"
|
|
indices={[
|
|
{
|
|
name: 'docs',
|
|
searchParameters: {
|
|
attributesToRetrieve: [
|
|
'hierarchy.lvl0',
|
|
'hierarchy.lvl1',
|
|
'hierarchy.lvl2',
|
|
'hierarchy.lvl3',
|
|
'hierarchy.lvl4',
|
|
'hierarchy.lvl5',
|
|
'hierarchy.lvl6',
|
|
'content',
|
|
'type',
|
|
'url',
|
|
'version',
|
|
],
|
|
},
|
|
},
|
|
]}
|
|
resultBadgeKey="version"
|
|
/>
|
|
```
|
|
|
|
## 6. Verify styles and package exports
|
|
|
|
The full stylesheet remains available from `@docsearch/css` and the CDN `dist/style.css` file:
|
|
|
|
```js title="app.js"
|
|
import '@docsearch/css';
|
|
```
|
|
|
|
The React package adds split style entries for variables, button, modal, Ask AI, and Sidepanel. See [Styling](/docs/packages/css/styling).
|
|
|
|
`@docsearch/js` now defines an exports map. Replace unsupported deep imports with `@docsearch/js` or `@docsearch/js/docsearch`. Continue to use documented React subpaths such as `@docsearch/react/button`, `/modal`, `/sidepanel`, and `/version`; their generated file names changed, but the package subpaths remain the public API.
|
|
|
|
## 7. Verify programmatic controls
|
|
|
|
The JavaScript function returns a `DocSearchInstance` with `open`, `close`, `openAskAi`, `destroy`, `isReady`, and `isOpen`. Use `openAskAi` only with the default AI-capable entry.
|
|
|
|
React forwards `DocSearchRef`. It also exposes `openSidepanel`, `isSidepanelOpen`, and `isSidepanelSupported` for [hybrid mode](/docs/hybrid-mode).
|
|
|
|
Test these cases before release:
|
|
|
|
- Open and close by button, `Ctrl/Cmd+K`, `/`, and Escape.
|
|
- Search every configured index and apply every facet.
|
|
- Open Ask AI, send follow-up questions, submit feedback, and restore a conversation.
|
|
- Exercise any custom tools and memory authentication.
|
|
- Verify custom hit links, result footers, translations, badges, and Insights events.
|
|
- Verify mobile behavior. Hybrid mode uses the modal instead of the Sidepanel on mobile.
|
|
|
|
## 8. Update framework integrations
|
|
|
|
If Docusaurus manages DocSearch configuration, follow the [Docusaurus adapter guide](/docs/packages/docusaurus-adapter/getting-started). For custom provider, button, and modal layouts, review the [Composable API](/docs/composable-api).
|