Vercel

Complete the shared configuration and your framework guide first. Set meta.baseURL to the public application URL and keep meta.basePath: "/docs".

One static deployment

Use this path when the application produces static files. Set npm run build to build the application, build Flame, then copy .docu/dist/. into the application's output. For a Vite app, use:

{
  "scripts": {
    "build:app": "vite build",
    "docs:build": "flame build",
    "build": "npm run build:app && npm run docs:build && cp -R .docu/dist/. dist/"
  }
}

Configure the Vercel project to publish the combined artifact:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "cleanUrls": true
}

Use out for a Next.js static export, build for SvelteKit's default static adapter output, or .output/public for Nuxt static generation. Keep the copy destination and output directory aligned. These are settings for the static application deployment; a server-rendered application keeps its framework's deployment output.

With cleanUrls, a request for a docs .html URL redirects to its extensionless form. Add "trailingSlash": false as well: Flame's asset URLs are relative to the docs page, and a page served at /docs/guide/ would request its bundle from /docs/docs/_flame/, which does not exist. With trailingSlash: false Vercel redirects /docs/guide/ to /docs/guide.

Monorepo with Turborepo

When the application and the docs are separate workspaces, let the task runner build the docs workspace before the application and let the application's build script do the copy. This is the configuration that publishes docubook.pro, where the Astro app is the @docubook/web workspace in pages/ and depends on the Flame workspace:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "installCommand": "pnpm install --filter=@docubook/web...",
  "buildCommand": "turbo build --filter=@docubook/web...",
  "outputDirectory": "pages/dist",
  "cleanUrls": true,
  "trailingSlash": false
}

{
  "scripts": {
    "build": "astro build && cp -R ../packages/flame/.docu/dist/. dist/ && cp dist/docs/404.html dist/404.html"
  }
}

The ... suffix on the filter includes the workspace's dependencies, so Turborepo runs the Flame workspace's build first and .docu/dist/ is fresh when Astro's script copies it. framework: null keeps Vercel from applying the Astro preset to a root that is not the Astro project. Set the project root to the repository root in the Vercel dashboard so both workspaces are available to the build.

SPA routes

If the static application needs a client-side routing fallback, exclude the docs prefix from that fallback. Add this rewrites array to the configuration above:

{
  "rewrites": [
    {
      "source": "/((?!docs(?:/|$)).*)",
      "destination": "/index"
    }
  ]
}

The destination is /index because this example enables cleanUrls. Existing files are served before the fallback. A nonexistent /docs/... URL stays outside the app shell and returns a platform or application 404. See Vercel routing configuration.

The presence of docs/404.html alone does not configure a docs-specific 404 on Vercel. To return Flame's 404 with the correct status, use the separate docs deployment below or a request handler. Rewriting every missing guide to the 404 file as an ordinary successful rewrite would return the wrong status.

Separate docs deployment

This path also supports Next.js, Nuxt, SvelteKit and Astro applications with server rendering.

Create a second Vercel project for the directory containing docu.json. Use the Other framework preset, a supported Node version and these build settings:

If the workspace calls its Flame build script build, use npm run build in that command. The copy adds a root fallback only to the dedicated docs artifact, allowing Vercel to return Flame's page for missing docs. Verify that the docs origin serves /docs/guide and returns HTTP 404 for a missing guide before adding the proxy.

In the application project's vercel.json, merge this external rewrite before any application catch-all:

{
  "rewrites": [
    {
      "source": "/docs/:path*",
      "destination": "https://acme-docs.vercel.app/docs/:path*"
    }
  ]
}

The destination must preserve /docs. This is an external rewrite, so the browser continues to use the application URL. Vercel documents external rewrites across frameworks. Ensure the docs deployment is reachable from the proxy and its access protection permits these requests.

For Next.js, configure the rule here or in next.config, with one owner for the production boundary. Build and output settings remain those of the application framework.

Monorepos and verification

The project root controls where Vercel reads its configuration. Select the application workspace for the app project and the docs workspace for the docs project, with workspace-aware dependency installation. If the build needs both workspaces, use a repository-root build and the monorepo copy paths.

Use a preview deployment to run the combined-site checks. Confirm /docs as well as /docs/guide.html and its extensionless destination, check the search index, and inspect the status of a missing docs page. Vercel's routing configuration does not replace the framework guide's local development proxy.