---
title: "Deployment"
description: "Deploy the docs site to Vercel, Netlify, Cloudflare or any Node.js server, or generate a fully static site. This page lists the build commands, environment variables, per-platform notes and the features that are unavailable on static hosting."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/guide/deployment"
---
# Deployment

> Deploy the docs site to Vercel, Netlify, Cloudflare or any Node.js server, or generate a fully static site. This page lists the build commands, environment variables, per-platform notes and the features that are unavailable on static hosting.

## Build

```bash [pnpm]
pnpm build
```

```bash [npm]
npm run build
```

```bash [yarn]
yarn build
```

```bash [bun]
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:

```bash [terminal]
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:

```bash [terminal]
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`](https://docs.mhaibaraai.cn/en/docs/components/commit-changelog) and [`PageLastCommit`](https://docs.mhaibaraai.cn/en/docs/components/page-last-commit) 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](https://docs.mhaibaraai.cn/en/docs/ai/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](https://nuxtseo.com/docs/og-image/migration-guide/v7#move-signing-to-nuxt_app_secret).

## Vercel

Vercel detects Nuxt projects, so no build settings need to change after importing the repository:

1. Create a project on Vercel and import the Git repository;
2. Add the environment variables above under **Settings → Environment Variables**;
3. Deploy. The build command is `nuxt build`, and Nitro picks the `vercel` preset and writes to `.vercel/output/`.

With the `vercel` preset, Markdown content negotiation for [agent discovery](https://docs.mhaibaraai.cn/en/docs/ai/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:

1. Import the Git repository on Netlify and keep `nuxt build` as the build command;
2. Add the environment variables under **Site configuration → Environment variables**, and set `NODE_VERSION` to a supported version listed above, such as `24`;
3. Deploy.

## Cloudflare

Use the `cloudflare_module` preset to deploy to Cloudflare Workers and let Nitro generate the Wrangler configuration with the `ASSETS` binding:

```ts [nuxt.config.ts]
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`.

> [!NOTE]
> 
> For the full Cloudflare walkthrough and 
> 
> 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:

```bash [terminal]
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:

```bash [pnpm]
pnpm nuxt generate
```

```bash [npm]
npx nuxt generate
```

```bash [yarn]
yarn nuxt generate
```

```bash [bun]
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](https://docs.mhaibaraai.cn/en/docs/ai/ai-chat) | Conversations call the model through `/api/ai-chat` at runtime |
| [MCP Server](https://docs.mhaibaraai.cn/en/docs/ai/mcp) | `/mcp` is a runtime endpoint |
| [`CommitChangelog`](https://docs.mhaibaraai.cn/en/docs/components/commit-changelog), [`PageLastCommit`](https://docs.mhaibaraai.cn/en/docs/components/page-last-commit) | 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

- [Nuxt deployment docs](https://nuxt.com/deploy)
- [Nitro deployment guide](https://nitro.build/deploy)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
