@vercel/geistdocs 1.25.2 → 1.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/cli.js +8 -0
  2. package/dist/cli/index.js +6 -2
  3. package/dist/config.d.ts +5 -0
  4. package/dist/config.d.ts.map +1 -1
  5. package/dist/internal/chat-retrieval.d.ts +32 -0
  6. package/dist/internal/chat-retrieval.d.ts.map +1 -0
  7. package/dist/internal/chat-retrieval.js +91 -0
  8. package/dist/internal/mixedbread.d.ts +93 -0
  9. package/dist/internal/mixedbread.d.ts.map +1 -0
  10. package/dist/internal/mixedbread.js +286 -0
  11. package/dist/internal/page-actions-client.d.ts.map +1 -1
  12. package/dist/internal/page-actions-client.js +1 -19
  13. package/dist/internal/search-export.d.ts +18 -0
  14. package/dist/internal/search-export.d.ts.map +1 -0
  15. package/dist/internal/search-export.js +1 -0
  16. package/dist/internal/search-sync.d.ts +25 -0
  17. package/dist/internal/search-sync.d.ts.map +1 -0
  18. package/dist/internal/search-sync.js +312 -0
  19. package/dist/routes/chat.d.ts +8 -2
  20. package/dist/routes/chat.d.ts.map +1 -1
  21. package/dist/routes/chat.js +53 -15
  22. package/dist/routes/search-export.d.ts +12 -0
  23. package/dist/routes/search-export.d.ts.map +1 -0
  24. package/dist/routes/search-export.js +44 -0
  25. package/docs/agents.md +4 -3
  26. package/docs/llms.txt +384 -33
  27. package/docs/manifest.json +12 -3
  28. package/docs/pages/ask-ai.md +3 -0
  29. package/docs/pages/configuration.md +5 -2
  30. package/docs/pages/deployment.md +30 -5
  31. package/docs/pages/env.md +13 -3
  32. package/docs/pages/getting-started.md +29 -9
  33. package/docs/pages/index.md +3 -2
  34. package/docs/pages/md.md +1 -1
  35. package/docs/pages/migration.md +148 -8
  36. package/docs/pages/mixedbread-retrieval.md +144 -0
  37. package/docs/sitemap.md +3 -2
  38. package/package.json +10 -4
  39. package/template/.env.example +19 -0
  40. package/template/AGENTS.md +17 -3
  41. package/template/app/api/search/export/route.ts +8 -0
  42. package/template/content/docs/ask-ai.mdx +3 -0
  43. package/template/content/docs/configuration.mdx +5 -2
  44. package/template/content/docs/deployment.mdx +31 -6
  45. package/template/content/docs/env.mdx +14 -4
  46. package/template/content/docs/getting-started.mdx +30 -10
  47. package/template/content/docs/index.mdx +3 -2
  48. package/template/content/docs/md.mdx +1 -1
  49. package/template/content/docs/meta.json +1 -0
  50. package/template/content/docs/migration.mdx +150 -9
  51. package/template/content/docs/mixedbread-retrieval.mdx +142 -0
  52. package/template/geistdocs.tsx +12 -1
  53. package/template/lib/geistdocs/config.tsx +2 -5
  54. package/template/package.json +2 -2
@@ -30,7 +30,7 @@
30
30
  "description": "Learn about the environment variables used in Geistdocs",
31
31
  "path": "pages/env.md",
32
32
  "source": "apps/template/content/docs/env.mdx",
33
- "summary": "Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.",
33
+ "summary": "Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.",
34
34
  "title": "Environment Variables",
35
35
  "type": "reference",
36
36
  "url": "/docs/env"
@@ -39,7 +39,7 @@
39
39
  "description": "Learn how to deploy your Geistdocs site to Vercel",
40
40
  "path": "pages/deployment.md",
41
41
  "source": "apps/template/content/docs/deployment.mdx",
42
- "summary": "Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.",
42
+ "summary": "Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.",
43
43
  "title": "Deploy to Vercel",
44
44
  "type": "guide",
45
45
  "url": "/docs/deployment"
@@ -152,6 +152,15 @@
152
152
  "type": "integration",
153
153
  "url": "/docs/feedback"
154
154
  },
155
+ {
156
+ "description": "Configure Mixedbread retrieval for a Geistdocs Ask AI chat and sync documentation to a site-specific Store",
157
+ "path": "pages/mixedbread-retrieval.md",
158
+ "source": "apps/template/content/docs/mixedbread-retrieval.mdx",
159
+ "summary": "Provision a Mixedbread Store for one Geistdocs consumer site, enable semantic retrieval, and sync documentation during production builds.",
160
+ "title": "Improve Ask AI answers with Mixedbread",
161
+ "type": "guide",
162
+ "url": "/docs/mixedbread-retrieval"
163
+ },
155
164
  {
156
165
  "description": "Add multi-language support to your documentation site",
157
166
  "path": "pages/internationalization.md",
@@ -208,5 +217,5 @@
208
217
  }
209
218
  ],
210
219
  "source": "apps/template/content/docs",
211
- "version": "1.25.2"
220
+ "version": "1.26.0"
212
221
  }
@@ -10,6 +10,7 @@ prerequisites:
10
10
  related:
11
11
  - /docs/open-in-chat
12
12
  - /docs/llms-txt
13
+ - /docs/mixedbread-retrieval
13
14
  - /docs/configuration
14
15
  ---
15
16
 
@@ -174,6 +175,8 @@ By default, the AI assistant includes a built-in `search_docs` tool that:
174
175
 
175
176
  When `GEISTDOCS_CHAT_PROXY_URL` is set, Geistdocs runs local documentation retrieval on the first user message before forwarding the request to the configured proxy. This gives proxy-backed services access to the current page and related local documentation without requiring them to read the site's source files directly.
176
177
 
178
+ Set `ai.retrieval` to `"mixedbread"` to replace local keyword retrieval with semantic retrieval for default, proxy, and hosted eve modes. Mixedbread returns the matching content chunk, while the AI model and the visible search dialog remain unchanged. Geistdocs falls back to local Orama retrieval when Mixedbread is unavailable. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) to provision a Store and configure production sync.
179
+
177
180
  ### Persistent Chat History
178
181
 
179
182
  Conversations are automatically saved to the browser's IndexedDB, providing:
@@ -116,6 +116,7 @@ On desktop, the group opens as a full-width panel below the navbar, following th
116
116
  import { defineConfig } from "@vercel/geistdocs/config";
117
117
  import {
118
118
  agent,
119
+ ai,
119
120
  basePath,
120
121
  github,
121
122
  Logo,
@@ -140,6 +141,7 @@ export const config = defineConfig({
140
141
  ai: {
141
142
  prompt,
142
143
  suggestions,
144
+ ...ai,
143
145
  },
144
146
  });
145
147
  ```
@@ -170,15 +172,16 @@ export const config = defineConfig({
170
172
  });
171
173
  ```
172
174
 
173
- The `ai` config also accepts `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
175
+ The `ai` config accepts `retrieval: "mixedbread"` to use semantic documentation retrieval and `eveAgent` to answer Ask AI requests with a hosted eve framework agent:
174
176
 
175
177
  ```tsx title="geistdocs.tsx"
176
178
  export const ai = {
179
+ retrieval: "mixedbread",
177
180
  eveAgent: { url: "https://help-eve.example.dev" },
178
181
  };
179
182
  ```
180
183
 
181
- See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication.
184
+ See [Ask AI](/docs/ask-ai) for the full eve agent mode behavior, including authentication. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) before enabling semantic retrieval.
182
185
 
183
186
  Use [Versioned docs](/docs/versioned-docs) for versioned source setup and [Proxy and markdown routes](/docs/proxy) for route mappings.
184
187
 
@@ -2,7 +2,7 @@
2
2
  title: Deploy to Vercel
3
3
  description: Learn how to deploy your Geistdocs site to Vercel
4
4
  type: guide
5
- summary: Deploy your Geistdocs site to Vercel from the dashboard with the correct project settings.
5
+ summary: Deploy a Geistdocs site to Vercel with the required project settings, environment variables, and private-package access.
6
6
  url: /docs/deployment
7
7
  source: apps/template/content/docs/deployment.mdx
8
8
  prerequisites:
@@ -14,9 +14,9 @@ related:
14
14
 
15
15
  # Deploy to Vercel
16
16
 
17
- Deploy a Geistdocs site to Vercel as a Next.js app. Make sure your package dependency, environment variables, and production URL are configured before shipping.
17
+ Deploy a Geistdocs site to Vercel as a Next.js app. Configure package access, environment variables, and the production URL before shipping.
18
18
 
19
- Help me deploy this Geistdocs project to Vercel. Check the package scripts, required environment variables, and Vercel project settings, then give me a deploy checklist for production.
19
+ Help me deploy this Geistdocs project to Vercel. Check whether it uses the Geistcn canary and therefore needs private npm access, then review the package scripts, environment variables, GitHub Actions authentication, and Vercel project settings.
20
20
 
21
21
  ## Prerequisites
22
22
 
@@ -26,6 +26,31 @@ Before deploying, you need:
26
26
  - A [Vercel account](https://vercel.com) (sign up at [vercel.com](https://vercel.com))
27
27
  - Your Vercel account connected to your GitHub account
28
28
  - Environment variables ready (see [Environment Variables](/docs/env))
29
+ - Access to restricted `@vercel` npm packages if the project uses the Geistcn canary
30
+
31
+ ## Configure private package access
32
+
33
+ The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Package installation fails without npm authentication.
34
+
35
+ For a Vercel deployment, ask `#help-core-platform` to add your Vercel project to the shared `NPM_TOKEN` environment variable list. Include the project link and the environments that need access. When `NPM_TOKEN` is available, Vercel creates the npm authentication configuration before installing dependencies. Do not copy the shared token into your repository or project documentation.
36
+
37
+ For GitHub Actions, ask `#help-it` to add your repository to the allowlist for the `NPM_TOKEN` organization secret. Pass that secret to npm authentication during the install job:
38
+
39
+ ```yaml title=".github/workflows/check.yml"
40
+ - uses: pnpm/action-setup@v4
41
+
42
+ - uses: actions/setup-node@v4
43
+ with:
44
+ node-version: 20
45
+ cache: pnpm
46
+ registry-url: https://registry.npmjs.org
47
+
48
+ - run: pnpm install
49
+ env:
50
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
51
+ ```
52
+
53
+ Read [How do I use private dependencies with Vercel?](https://vercel.com/kb/guide/using-private-dependencies-with-vercel) for the platform's npm authentication behavior.
29
54
 
30
55
  ## Deploy to Vercel
31
56
 
@@ -35,9 +60,9 @@ To deploy from the Vercel dashboard:
35
60
  2. Select your Geistdocs repository
36
61
  3. Configure your project settings:
37
62
  - **Framework Preset**: Next.js (automatically detected)
38
- - **Build Command**: `pnpm build` or `npm run build`
63
+ - **Build Command**: `pnpm build`
39
64
  - **Output Directory**: `.next` (default)
40
- - **Install Command**: `pnpm install` or `npm install`
65
+ - **Install Command**: `pnpm install`
41
66
  4. Add your environment variables (see [Environment Variables](/docs/env))
42
67
  5. Click "Deploy"
43
68
 
package/docs/pages/env.md CHANGED
@@ -2,7 +2,7 @@
2
2
  title: Environment Variables
3
3
  description: Learn about the environment variables used in Geistdocs
4
4
  type: reference
5
- summary: Environment variables required by Geistdocs for AI chat, proxy mode, and production URL configuration.
5
+ summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, and production URL configuration.
6
6
  url: /docs/env
7
7
  source: apps/template/content/docs/env.mdx
8
8
  prerequisites:
@@ -14,9 +14,9 @@ related:
14
14
 
15
15
  # Environment Variables
16
16
 
17
- Geistdocs uses environment variables to configure Ask AI, optional Vertex-backed proxy mode, and production URL behavior.
17
+ Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, and production URL behavior.
18
18
 
19
- Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `GEISTDOCS_CHAT_PROXY_URL`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
19
+ Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `MXBAI_API_KEY`, `MXBAI_STORE_ID`, `GEISTDOCS_CHAT_PROXY_URL`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel.
20
20
 
21
21
  ## `AI_GATEWAY_API_KEY`
22
22
 
@@ -26,6 +26,16 @@ The API key for the AI Gateway. This is used to power the default local AI chat
26
26
 
27
27
  Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode.
28
28
 
29
+ ## `MXBAI_API_KEY`
30
+
31
+ The server-only API key for Mixedbread retrieval. The Mixedbread Vercel Marketplace integration injects this value when you provision a Store and connect it to the consumer site's Vercel project.
32
+
33
+ ## `MXBAI_STORE_ID`
34
+
35
+ The Mixedbread Store used by one consumer site. Set `ai.retrieval` to `"mixedbread"` and configure a unique `siteId` before using this value.
36
+
37
+ Provision the Store by running `vercel integration add mixedbread` from the root of the consumer site's repository, where Vercel CLI is linked to that site's project. Do not run the provisioning command from the Geistdocs package repository. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) for the complete setup.
38
+
29
39
  ## `GEISTDOCS_CHAT_PROXY_URL`
30
40
 
31
41
  An optional URL for a chat proxy. When set, Geistdocs searches the local documentation on the first user message, injects the current page and related docs as context, and forwards the request to this proxy.
@@ -16,35 +16,55 @@ related:
16
16
 
17
17
  Create a Geistdocs site with the package CLI, then edit the generated content and configuration files. If you already have a Fumadocs or custom Geist docs site, read [Migration guide](/docs/migration) before moving route adapters and middleware behavior.
18
18
 
19
- Create a Geistdocs project with `pnpm dlx @vercel/geistdocs init --name my-docs`. Then open `my-docs`, run `pnpm dev`, and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
19
+ Help me create a Geistdocs project. Use `@vercel/geistdocs@latest` for the stable release or `@vercel/geistdocs@canary` when I specifically need the Geistcn migration. Then run `pnpm dev` and explain which files I should edit first: `geistdocs.tsx`, `content/docs`, `content/docs/meta.json`, and `components/geistdocs/mdx-components.tsx`.
20
20
 
21
21
  ## Prerequisites
22
22
 
23
23
  Before you begin, install:
24
24
 
25
- - Node.js 18 or later
26
- - pnpm, npm, or another package manager
25
+ - Node.js 20.9 or later
26
+ - pnpm
27
27
  - Git
28
28
 
29
+ The Geistdocs CLI always uses pnpm to install the generated project's dependencies. Running the CLI through `npx` does not remove the pnpm requirement.
30
+
31
+ ## Choose a release channel
32
+
33
+ Use `@vercel/geistdocs@latest` for the current stable package-backed release. Use `@vercel/geistdocs@canary` only when you need changes being evaluated on the `canary` branch, including the current Geistcn migration.
34
+
35
+ The canary dist-tag can move several times in one day. The CLI resolves the tag once and writes that exact version to the generated `package.json`.
36
+
37
+ ## Authenticate for the Geistcn canary
38
+
39
+ The Geistcn canary depends on restricted `@vercel/geistcn` and `@vercel/geistcn-assets` packages. Configure npm authentication before running the canary CLI. Add this configuration to your user-level `~/.npmrc`:
40
+
41
+ ```ini title="~/.npmrc"
42
+ @vercel:registry=https://registry.npmjs.org/
43
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
44
+ always-auth=true
45
+ ```
46
+
47
+ Set `NPM_TOKEN` from an approved internal source and keep its value out of files and Git. Stable Geistdocs does not currently require these restricted packages. Read [Deploy to Vercel](/docs/deployment) before configuring automated installs.
48
+
29
49
  ## Create a project
30
50
 
31
- Run the Geistdocs CLI from an empty parent folder:
51
+ Run the Geistdocs CLI from an empty parent folder. For stable Geistdocs, run:
32
52
 
33
53
  ```bash title="Terminal"
34
- pnpm dlx @vercel/geistdocs init --name my-docs
54
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
35
55
  ```
36
56
 
37
- You can also use npm:
57
+ For the Geistcn canary, run:
38
58
 
39
59
  ```bash title="Terminal"
40
- npx @vercel/geistdocs init --name my-docs
60
+ pnpm dlx @vercel/geistdocs@canary init --name my-docs
41
61
  ```
42
62
 
43
63
  The CLI copies the template bundled in the package, rewrites the generated app to depend on the same `@vercel/geistdocs` version, installs dependencies, copies `.env.example` to `.env.local`, and initializes Git.
44
64
 
45
65
  ## Understand generated dependencies
46
66
 
47
- Generated projects include `@vercel/geistdocs`, `ai` v6, and `@ai-sdk/react` v3. Geistdocs uses those AI SDK packages for Ask AI, including the chat client transport and `createChatRoute` server behavior.
67
+ Generated projects include `@vercel/geistdocs`, `ai` v6, and `@ai-sdk/react` v3. Geistdocs uses those AI SDK packages for Ask AI, including the chat client transport and `createChatRoute` server behavior. Canary projects also declare the matching `@vercel/geistcn` and `@vercel/geistcn-assets` versions directly because generated application files import them.
48
68
 
49
69
  Update Ask AI by updating `@vercel/geistdocs`, not by copying package chat internals into the app. If your project uses the AI SDK directly for separate product features, keep that code compatible with the app's installed AI SDK version; package-owned Ask AI does not need to match another consumer project's `ai` version.
50
70
 
@@ -109,7 +129,7 @@ Read [Configuration](/docs/configuration) for the full configuration surface.
109
129
 
110
130
  ## Update Geistdocs
111
131
 
112
- For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files.
132
+ For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files. Projects already using a canary version continue to follow the `canary` dist-tag; stable projects follow `latest`.
113
133
 
114
134
  ```bash title="Terminal"
115
135
  pnpm exec geistdocs update
@@ -28,7 +28,7 @@ Geistdocs has three main parts:
28
28
  ```mermaid
29
29
  flowchart TB
30
30
  subgraph Package["@vercel/geistdocs package"]
31
- cli["CLI: init, update, translate"]
31
+ cli["CLI: init, update, translate, search sync"]
32
32
  runtime["Runtime: layout, routes, MDX, controls"]
33
33
  bundledTemplate["Bundled template snapshot"]
34
34
  end
@@ -78,6 +78,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
78
78
  - MDX documentation with custom components
79
79
  - Local content in `content/docs`
80
80
  - Search and Ask AI
81
+ - Optional Mixedbread semantic retrieval for Ask AI
81
82
  - Page actions, including feedback, copy page, open in chat, and edit on GitHub
82
83
  - Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
83
84
  - Raw Markdown routes for AI tools
@@ -87,7 +88,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
87
88
  - RSS feed
88
89
  - Theme-aware images
89
90
  - Internationalized routes
90
- - CLI commands for init, update, and translation
91
+ - CLI commands for init, update, translation, and Mixedbread search sync
91
92
 
92
93
  ## Next steps
93
94
 
package/docs/pages/md.md CHANGED
@@ -39,7 +39,7 @@ The `.mdx` version returns:
39
39
 
40
40
  For a docs section mounted at `/docs`, the section root remains `/docs.md`. For a source mounted at the app root with `baseUrl: "/"`, Geistdocs uses `/index.md` for the root page. If Next.js has `basePath: "/docs"`, that public root Markdown URL is `/docs/index.md`.
41
41
 
42
- Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
42
+ Copy Page, View as Markdown, and the `text/markdown` metadata alternate all use the same package resolver. View as Markdown opens the resolved `.md` URL in a new tab from a button, which keeps the URL shareable without adding an anchor to the page. Use `createDocsPage({ getMarkdownUrl })` only when the deployment needs a different public contract.
43
43
 
44
44
  ## Use cases
45
45
 
@@ -18,7 +18,10 @@ related:
18
18
 
19
19
  Migrate an existing Fumadocs or custom Geist documentation site to `@vercel/geistdocs` by moving shared behavior into package APIs and keeping site-specific adapters local. The safest migration keeps content, routing decisions, and product-specific UI in your app while replacing copied runtime code with thin package-backed adapters.
20
20
 
21
- Help me migrate this existing docs site to package-backed Geistdocs. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. Then produce a step-by-step migration plan using `@vercel/geistdocs` package APIs without copying package internals.
21
+ > Note:
22
+ The current Geistcn migration is available from the `canary` dist-tag, not `latest`. The canary depends on restricted `@vercel/geistcn` packages and is intended for Vercel-internal projects while the migration is evaluated.
23
+
24
+ Help me migrate this existing docs site to package-backed Geistdocs. First determine whether I should use the stable release or the Geistcn canary. Inspect `source.config.ts`, `lib/geistdocs/source.ts`, app route files, `proxy.ts` or `middleware.ts`, `public/llms.txt`, Open Graph routes, Tailwind CSS setup, `package.json` AI SDK dependencies, and environment variables. For the Geistcn canary, also inspect package authentication, `@vercel/geistdocs` component and asset imports, root HTML classes, and Next.js configuration. Pin the selected version and use package APIs without copying package internals.
22
25
 
23
26
  ## Before you migrate
24
27
 
@@ -30,6 +33,7 @@ Create a working branch and inventory the current site before replacing code:
30
33
  - Static files that overlap package routes, such as `public/llms.txt`.
31
34
  - Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, `/.well-known/mcp.json`, RSS, and Open Graph routes.
32
35
  - Tailwind CSS version and custom plugins.
36
+ - Imports from `@vercel/geistdocs/components/*` or `@vercel/geistdocs/assets/*` that the Geistcn canary removes.
33
37
  - Direct app usage of `ai` or `@ai-sdk/react` outside Geistdocs.
34
38
  - Environment variables required by the homepage, docs routes, or API routes.
35
39
 
@@ -44,20 +48,76 @@ Fix unrelated build failures first. A migration is safer when the starting point
44
48
 
45
49
  ## Install Geistdocs
46
50
 
47
- Add `@vercel/geistdocs` and align the supported Fumadocs and Next.js dependencies for the package version you are adopting. Geistdocs requires Next.js 16.3.3 or later within 16.x. Earlier 16.3 releases can retain an optional catch-all route's index content after a client navigation to a child page when Cache Components and Partial Prefetching are enabled.
51
+ For the current stable package-backed release, install `latest` and record the exact resolved version:
52
+
53
+ ```bash title="Terminal"
54
+ pnpm add --save-exact @vercel/geistdocs@latest
55
+ ```
56
+
57
+ Geistdocs requires Node.js 20.9 or later and Next.js 16.3.3 or later within 16.x. Earlier 16.3 releases can retain an optional catch-all route's index content after a client navigation to a child page when Cache Components and Partial Prefetching are enabled.
58
+
59
+ If you are starting from a generated stable Geistdocs project and moving content into it, run the CLI from an empty parent folder:
60
+
61
+ ```bash title="Terminal"
62
+ pnpm dlx @vercel/geistdocs@latest init --name my-docs
63
+ ```
64
+
65
+ ### Install the Geistcn canary
66
+
67
+ The Geistcn canary requires npm access to restricted `@vercel` packages. Configure your user-level npm authentication before installation:
68
+
69
+ ```ini title="~/.npmrc"
70
+ @vercel:registry=https://registry.npmjs.org/
71
+ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
72
+ always-auth=true
73
+ ```
74
+
75
+ Set `NPM_TOKEN` from an approved internal source and keep its value out of files and Git. Read [Deploy to Vercel](/docs/deployment#configure-private-package-access) for Vercel and GitHub Actions access.
76
+
77
+ For an existing standalone project, install the canary and the direct Geistcn dependencies used by application files. The current canary template uses `@vercel/geistcn` 1.0.3 and `@vercel/geistcn-assets` 2.0.1:
78
+
79
+ ```bash title="Terminal"
80
+ pnpm add --save-exact \
81
+ @vercel/geistdocs@canary \
82
+ @vercel/geistcn@1.0.3 \
83
+ @vercel/geistcn-assets@2.0.1
84
+ ```
85
+
86
+ `--save-exact` records the canary resolved at install time instead of a range. Before upgrading later, check the next canary and test that exact version:
87
+
88
+ ```bash title="Terminal"
89
+ npm view @vercel/geistdocs dist-tags.canary
90
+ ```
48
91
 
49
- For an existing project, use your package manager directly:
92
+ In a monorepo that owns the Geistcn packages, such as `vercel/front`, keep their existing `workspace:*` dependency specifications and pin only `@vercel/geistdocs` to the tested canary.
93
+
94
+ If you are starting from a generated Geistdocs project and moving content into it, run the canary CLI from an empty parent folder:
50
95
 
51
96
  ```bash title="Terminal"
52
- pnpm add @vercel/geistdocs
97
+ pnpm dlx @vercel/geistdocs@canary init --name my-docs
53
98
  ```
54
99
 
55
- If you are starting from a generated Geistdocs project and moving content into it, use the CLI:
100
+ ## Replace imports for the Geistcn canary
101
+
102
+ The Geistcn canary removes generic design-system components and assets from the Geistdocs public API. Search for affected imports before upgrading:
56
103
 
57
104
  ```bash title="Terminal"
58
- pnpm dlx @vercel/geistdocs init --name my-docs
105
+ rg '@vercel/geistdocs/(components|assets)' .
59
106
  ```
60
107
 
108
+ Replace imports according to this table:
109
+
110
+ | Previous Geistdocs import | Replacement |
111
+ | --- | --- |
112
+ | `components/badge`, `components/button`, `components/dialog`, `components/drawer`, `components/input`, `components/kbd`, `components/separator`, `components/sheet`, `components/spinner`, `components/textarea`, `components/theme-switcher`, or `components/tooltip` | Import the matching component directly from `@vercel/geistcn/components/<name>`. |
113
+ | `components/switch` | Import toggle controls from `@vercel/geistcn/components/toggle`. |
114
+ | `components/sonner` | Use `Toasts` and `useToasts` from `@vercel/geistcn/components/toasts`. |
115
+ | `components/theme-aware-image` | Use `Image` from `@vercel/geistcn/components/image` with `srcLight` and `srcDark`. |
116
+ | `assets/icons`, `assets/icons/*`, `assets/logos`, or `assets/logos/*` | Import from `@vercel/geistcn-assets/icons`, `@vercel/geistcn-assets/icons/*`, `@vercel/geistcn-assets/logos`, or `@vercel/geistcn-assets/logos/*`. |
117
+ | `components/button-group`, `components/card`, or `components/input-group` | Use an appropriate Geistcn component or keep an application-owned composition. There is no direct Geistcn replacement with the same API. |
118
+
119
+ Keep documentation-specific composites such as `Callout`, `CodeBlock`, `CodeBlockTabs`, `CommandPrompt`, `CopyPrompt`, and `Mermaid` imported from `@vercel/geistdocs/components/*`.
120
+
61
121
  ## Configure Next.js
62
122
 
63
123
  The Geistdocs Next.js integration composes Fumadocs MDX, enables automatic app-route discovery for agent-readable 404s, and preserves your Next.js configuration. Enable Cache Components in the same file:
@@ -76,6 +136,39 @@ const config: NextConfig = {
76
136
  export default withGeistdocs(config);
77
137
  ```
78
138
 
139
+ ### Configure Next.js for the Geistcn canary
140
+
141
+ Geistcn publishes TypeScript source from supporting packages. A project using the Geistcn canary also needs the matching transpilation and modular import settings:
142
+
143
+ ```ts title="next.config.ts"
144
+ import { createGeistdocs } from "@vercel/geistdocs/next";
145
+ import type { NextConfig } from "next";
146
+
147
+ const withGeistdocs = createGeistdocs();
148
+
149
+ const config: NextConfig = {
150
+ modularizeImports: {
151
+ "@vercel/geistcn/components": {
152
+ skipDefaultConversion: true,
153
+ transform: "@vercel/geistcn/components/{{ kebabCase member }}",
154
+ },
155
+ "@vercel/geistcn/core": {
156
+ skipDefaultConversion: true,
157
+ transform: "@vercel/geistcn/core",
158
+ },
159
+ },
160
+ transpilePackages: [
161
+ "@vercel/geistcn",
162
+ "@vercel/geist-test-utils",
163
+ "@vercel/next-themes",
164
+ ],
165
+ cacheComponents: true,
166
+ partialPrefetching: true,
167
+ };
168
+
169
+ export default withGeistdocs(config);
170
+ ```
171
+
79
172
  Restart `next dev` after adding, deleting, or renaming an App Router page or route. Production builds always regenerate the route manifest.
80
173
 
81
174
  Every root dynamic parameter needs at least one value from `generateStaticParams`. For a site with a `[lang]` root segment, return every configured language from the root layout:
@@ -104,6 +197,33 @@ Keep `partialPrefetching` enabled so links reuse each route's static and cached
104
197
 
105
198
  For unknown HTML pages, browsers can receive the docs loading shell with a `200` response before the page resolves to the not-found UI. Crawlers wait for the complete response and receive `404`. Machine-readable Markdown routes keep their configured status behavior.
106
199
 
200
+ ## Configure the root layout for the Geistcn canary
201
+
202
+ Geistcn provides the fonts, theme classes, and Tailwind preflight used by the package UI. Apply them to the root `<html>` element:
203
+
204
+ ```tsx title="app/[lang]/layout.tsx"
205
+ import { geistFontClasses } from "@vercel/geistcn/core";
206
+ import { cn } from "@vercel/geistcn/utils";
207
+ import type { ReactNode } from "react";
208
+
209
+ export default function RootLayout({ children }: { children: ReactNode }) {
210
+ return (
211
+ <html
212
+ className={cn(
213
+ geistFontClasses,
214
+ "tailwind tailwind-preflight antialiased"
215
+ )}
216
+ lang="en"
217
+ suppressHydrationWarning
218
+ >
219
+ <body>{children}</body>
220
+ </html>
221
+ );
222
+ }
223
+ ```
224
+
225
+ Keep the site's existing providers and metadata inside this structure. If the route has a `[lang]` parameter, use the active language instead of the hardcoded `en` value.
226
+
107
227
  ## Align Ask AI dependencies
108
228
 
109
229
  Geistdocs Ask AI uses AI SDK v6. Generated projects install `ai` v6 and `@ai-sdk/react` v3 so package-owned chat components and route helpers use the supported AI SDK APIs.
@@ -374,7 +494,7 @@ For a base-path application whose root page is documentation, add `"/"` to the s
374
494
 
375
495
  ## Configure Tailwind CSS
376
496
 
377
- Tailwind CSS v4 requires `@source` entries for package components and related dependencies.
497
+ Stable Geistdocs uses Tailwind CSS v4 with source entries for package components and related dependencies:
378
498
 
379
499
  ```css title="app/styles/geistdocs.css"
380
500
  @import "tailwindcss";
@@ -388,6 +508,23 @@ Tailwind CSS v4 requires `@source` entries for package components and related de
388
508
 
389
509
  Move Tailwind CSS v3 plugin utilities into CSS-first v4 utilities or theme variables. Keep custom token names stable while you migrate components.
390
510
 
511
+ ### Configure Tailwind CSS for the Geistcn canary
512
+
513
+ For the Geistcn canary, use the import order and narrow Geistcn source scan from the canary template:
514
+
515
+ ```css title="app/styles/geistdocs.css"
516
+ @import "@vercel/geistcn/tailwind.css";
517
+ @import "fumadocs-ui/css/shadcn.css";
518
+ @import "fumadocs-ui/css/preset.css";
519
+ @import "@vercel/geistdocs/theme.css";
520
+ @import "@vercel/geistcn/styles.css";
521
+ @import "@vercel/geistcn/marketing-typography.css";
522
+
523
+ @source "../../node_modules/@vercel/geistcn/src/components/**/*.{ts,tsx}";
524
+ ```
525
+
526
+ Geistcn owns the Geist tokens, theme, typography, preflight, and animation utilities. The Geistdocs theme entry point contains documentation and Fumadocs integration rules and sources the compiled Geistdocs runtime. Do not scan all of `@vercel/geistcn/src`; font internals in the published package can reference paths outside the application root and cause Turbopack to fail.
527
+
391
528
  ## Handle environment variables
392
529
 
393
530
  Do not require production secrets for local migration builds. If a homepage or API route depends on a production-only secret, add a local fallback or disable that integration in development.
@@ -398,7 +535,7 @@ export const flagsSecret =
398
535
  (process.env.NODE_ENV === "development" ? "local-development-secret" : undefined);
399
536
  ```
400
537
 
401
- Keep real secrets in `.env.local` and out of Git.
538
+ Keep real application secrets in `.env.local` and out of Git. `NPM_TOKEN` is an install-time credential, not an application environment variable. Keep it in your shell, Vercel project settings, or GitHub Actions secrets, and never prefix it with `NEXT_PUBLIC_`.
402
539
 
403
540
  ## Verify the migration
404
541
 
@@ -406,10 +543,13 @@ Run the same checks after each routing or source change:
406
543
 
407
544
  ```bash title="Terminal"
408
545
  pnpm postinstall
546
+ pnpm list @vercel/geistdocs
409
547
  pnpm build
410
548
  pnpm dev
411
549
  ```
412
550
 
551
+ For the Geistcn canary, also run `pnpm list @vercel/geistcn @vercel/geistcn-assets` and confirm the versions match the selected canary template.
552
+
413
553
  Check these URLs locally:
414
554
 
415
555
  - `/docs` or the migrated docs root.