Bring Your Own Pages

experimental.pages lets an existing application own the homepage while Flame builds the documentation under a prefix such as /docs. The application and the docs can use different frameworks, live in the same project or separate workspaces, and share a public origin.

This is an experimental option: its configuration and behavior may change. The integration happens through static files and HTTP routes. Flame still renders its own docs with React; the application keeps its own router, layouts and state.

Feature scope

The framework and hosting guides are integration recipes. The flag changes Flame's output and root-page behavior; the application and hosting configuration complete the integration.

Application pages stay with their framework. This flag does not discover project pages/ files containing React, Vue or Svelte components, share application routers or state, or provide application APIs and authentication. Flame reads documentation from docs/ and renders it with its own components. Its output directory remains .docu/dist/.

The recipes have not all been exercised through real deployments of every framework and hosting combination. Use the verification steps below on the actual combined application, including its adapter and routing configuration.

Prerequisites

The examples use npm and a POSIX shell. Use your project's package manager throughout and commit its lockfile. In Windows PowerShell, set a port with $env:PORT = "3001" before running npx flame dev instead of using PORT=3001 inline.

Configure Flame

From the directory that will contain docu.json, install Flame:

npm install -D @docubook/flame

Add the configuration and content manually when extending an existing application. flame init copies a standalone project template, including package.json, so reserve it for a new, empty directory.

{
  "$schema": "https://cdn.jsdelivr.net/npm/@docubook/flame/docu.schema.json",
  "meta": {
    "title": "Acme Docs",
    "baseURL": "https://acme.example",
    "basePath": "/docs"
  },
  "experimental": {
    "pages": true
  }
}

Use the public application URL for meta.baseURL, including any deployment subpath. Keep the docs prefix in meta.basePath only: putting /docs in both settings produces /docs/docs/…. Local development ignores the deployment subpath.

The framework and hosting examples assume deployment at the origin root. If the combined site is published under /product, use baseURL: "https://acme.example/product", keep basePath: "/docs", and adjust production links and public routing rules to /product/docs/….

Create docs/index.mdx and docs/guide.mdx, each with frontmatter and some content:

---
title: Guide
description: Learn how to use Acme.
---

Welcome to the guide.

Merge these scripts into the existing package.json; keep the application's scripts:

{
  "scripts": {
    "docs:dev": "PORT=3001 flame dev",
    "docs:build": "flame build",
    "docs:preview": "flame preview"
  }
}

With the flag enabled, a normal flame build produces:

.docu/dist/
└── docs/
    ├── index.html
    ├── guide.html
    ├── 404.html
    ├── assets/       # copied from docs/assets, when present
    └── _flame/       # JS, CSS, manifest and search index

Flame skips the generated landing page and its bundle, ignores home, and moves its 404 and browser bundles under the docs prefix. Remove home to silence the warning. docs/index.mdx is optional; without it there is no generated docs index.

Choose a framework and hosting model

For a static application, build both projects and copy Flame's output into the application's output after its build. Flame always writes to its own .docu/dist/; it has no custom output-directory option. Build tools may empty their output directory, so copying the docs first can remove them again. Keep .docu/dist/ as Flame's build directory and copy from it into the final artifact.

For an application with server rendering, keep the framework's deployment adapter and deploy the docs separately. Forward /docs and /docs/* to that docs deployment, preserving the prefix, query string, response status and content type. The public URL can still be https://acme.example/docs/….

See project layouts and monorepos, then choose Vercel, Cloudflare, Heroku or Netlify.

Develop and verify

Run npm run docs:dev and the application's dev server in separate terminals. flame dev serves docs only; its / redirects to /docs. The framework guides show local proxy rules where supported. Forward /__hmr as well as /docs: Flame uses a server-sent event stream at /__hmr for reload notifications. This development endpoint is separate from the production docs prefix.

Restart flame dev after editing docu.json, including changes to experimental.pages, basePath, routes or icons. Configuration is loaded and cached at startup; the Markdown watcher does not reload it. Changes to the app's proxy configuration may also require restarting its dev server.

Navigate from the application to docs with a full document navigation so the browser loads Flame's HTML, styles and scripts. Each framework guide shows the appropriate link. Service workers and application-wide navigation handlers must also leave /docs requests to the network.

After deployment, verify the following with the browser and curl -I (follow redirects with curl -IL):

flame preview previews Flame's own artifact. Use the host's local preview or a preview deployment to verify the combined application and its routing rules.