Deployment
Build
pnpm build
npm run build
yarn build
bun run build
nuxt build prerenders the home page and every page reachable through links, and produces the server code in .output/. Preview it locally:
node .output/server/index.mjs
Building and running both need Node.js 22.22.3+ (22.x), 24.15.0+ (24.x), or 26+: Nuxt Content uses the built-in node:sqlite, so better-sqlite3 is not required.
Catch dead links
The layer sets nitro.prerender.failOnError: false, so a dead link found during prerendering does not stop the build; it only logs [request error]. Fail CI on that line instead:
pnpm build 2>&1 | tee build.log
! grep '\[request error\]' build.log
Environment variables
| Variable | Required | Description |
|---|---|---|
NUXT_GITHUB_TOKEN | In production | GitHub access token. CommitChangelog and PageLastCommit show nothing without it; the releases page can call GitHub anonymously but is limited to 60 requests per hour |
AI_API_KEY | No | Master switch for AI Chat: if present at build time, AI Chat is enabled. See AI Chat |
AI_BASE_URL | No | OpenAI-compatible endpoint such as https://api.deepseek.com/v1; when empty, requests go through the Vercel AI Gateway |
NUXT_APP_SECRET | With runtime OG image signing | A stable private value of at least 32 characters, configured in the production runtime environment |
AI_API_KEY decides at build time whether AI Chat is bundled, and is used at runtime to call the model, so set it in both the build and the runtime environment. The token only needs read access to public repositories.
The layer enables ogImage.zeroRuntime by default, so prerendered OG images do not need an application secret. If you switch to runtime rendering and keep URL signing enabled, configure NUXT_APP_SECRET as described in the OG Image v7 migration guide.
Vercel
Vercel detects Nuxt projects, so no build settings need to change after importing the repository:
- Create a project on Vercel and import the Git repository;
- Add the environment variables above under Settings → Environment Variables;
- Deploy. The build command is
nuxt build, and Nitro picks thevercelpreset and writes to.vercel/output/.
With the vercel preset, Markdown content negotiation for agent discovery is rewritten at the edge without invoking a function.
Netlify
Netlify also detects Nuxt projects, and Nitro picks the netlify preset in Netlify builds:
- Import the Git repository on Netlify and keep
nuxt buildas the build command; - Add the environment variables under Site configuration → Environment variables, and set
NODE_VERSIONto a supported version listed above, such as24; - Deploy.
Cloudflare
Use the cloudflare_module preset to deploy to Cloudflare Workers and let Nitro generate the Wrangler configuration with the ASSETS binding:
export default defineNuxtConfig({
nitro: {
preset: 'cloudflare_module',
cloudflare: { deployConfig: true, nodeCompat: true }
}
})
The Workers runtime has no node:sqlite, so under the Cloudflare preset Nuxt Content switches to a D1 database bound as DB. Create a D1 database in the Cloudflare dashboard, bind it to the Worker as DB, then deploy. Set environment variables under the Worker's Settings → Variables and Secrets.
If the MCP Server is enabled, install agents for MCP Toolkit's Cloudflare transport.
For prerendered HTML pages, route the page requests through the Worker first so Nitro can negotiate Markdown. Test the same URL with both Accept: text/html and Accept: text/markdown.
wrangler configuration, see the Nuxt deployment docs.Node.js server
Run the build output on any server with one of the supported Node.js versions above:
NUXT_GITHUB_TOKEN=xxx PORT=3000 node .output/server/index.mjs
Copy the whole .output/ directory to the server; node_modules is not needed at runtime.
Static generation
When no server is needed, generate a fully static site and deploy it to GitHub Pages, object storage or any static host:
pnpm nuxt generate
npx nuxt generate
yarn nuxt generate
bunx nuxt generate
The output is in .output/public/. Pages, full-text search, component props and examples, llms.txt, sitemap.xml and OG images are all produced at build time and work on static hosting. These features need a server and are unavailable on a static site:
| Feature | Reason |
|---|---|
| AI Chat | Conversations call the model through /api/ai-chat at runtime |
| MCP Server | /mcp is a runtime endpoint |
CommitChangelog, PageLastCommit | They request /api/github/* from the browser, and a static site has no such endpoints |
| Markdown content negotiation | Returning Markdown based on the Accept header needs server middleware or an edge rewrite |
Release data on the releases page is fetched during prerendering and baked into the page; it does not follow GitHub until the next build.
Resources
OG Images
Every docs page gets a social sharing image (OG image) generated at build time. This page covers the fields the built-in template reads, generating images for custom pages, replacing the template, and what happens when the feature is off.
AI Chat
Turn on the built-in AI assistant for your docs site. Covers the enable conditions and dependencies, model and endpoint routing, adding other providers, and the component and composable API, so readers can ask the docs directly within minutes.