Astro

Add Flame using the shared setup. Astro owns the application pages, and Flame owns /docs. Keep meta.baseURL set to the URL visitors use for the combined site.

Local development

Merge the following into the existing Astro configuration:

import { defineConfig } from "astro/config";

const docsProxy = {
  target: "http://localhost:3001",
  changeOrigin: true,
};

export default defineConfig({
  vite: {
    server: {
      proxy: {
        "^/docs(?:/|$)": docsProxy,
        "/__hmr": docsProxy,
      },
    },
  },
});

Astro accepts additional Vite configuration. The docs proxy preserves /docs and forwards Flame's SSE reload stream.

Run npm run dev and npm run docs:dev in separate terminals. Astro normally serves the application at http://localhost:4321/; the documentation is available at http://localhost:4321/docs/.

Both Flame commands write to the same .docu/dist/ tree. flame dev serves its own bundle from there and leaves the bundles and manifest.json of the last flame build untouched, so a built artifact stays valid while the dev server runs. A dev-server bundle is not deployable: it is unminified and carries no precompiled MDX modules, so always run flame build before copying docs into the application's output. Dev bundles accumulate in .docu/dist/docs/_flame/ until the next flame build cleans them.

Link from Astro

<a href="/docs/" data-astro-reload>Documentation</a>

The anchor performs a full document navigation. If the application uses Astro's client router, data-astro-reload keeps the docs link on that path so Flame's scripts initialize in their own document.

Static build

For Astro's static output, build the application first: astro build empties dist/, so docs copied before it would be removed. Then build Flame and copy its whole output, keeping the /docs prefix:

npx astro build
npm run docs:build
cp -R .docu/dist/. dist/

As one build script, with Flame's docs 404 promoted to the site's root 404 so missing URLs anywhere on the host get a 404 page:

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

Publish dist/. Update the destination if Astro's outDir is customized. Keep the Flame tree's /docs prefix intact, and reserve that route prefix in Astro's page tree: a src/pages/docs/ directory in Astro would collide with it.

Flame writes depth-relative asset URLs such as ../../docs/_flame/client-abc123.js, which resolve from the docs page's own URL. Serve docs pages at their extensionless or .html URL, never with a trailing slash: at /docs/guide/ the browser resolves the bundle one directory too deep, the request 404s and no interactive component on the page initializes. On Vercel this is trailingSlash: false. astro preview serves /docs/guide/ as-is without redirecting, so verify locally with /docs/guide.

In a monorepo where the Astro app and the docs are separate workspaces, the copy path crosses workspaces, for example cp -R ../docs/.docu/dist/. dist/; see project layouts and the Vercel monorepo example.

Choose Vercel, Cloudflare, Heroku or Netlify for the production configuration. Astro's local proxy does not configure the production host.

Server-rendered build

For an Astro application with server rendering, keep its adapter and deployment settings. Deploy Flame's .docu/dist/ independently and forward /docs plus /docs/* using the host's external rewrite. This keeps the integration independent of the adapter's output layout.

See Vercel, Cloudflare or Netlify. Check the upstream docs 404 and clean-URL behavior as well as the app homepage using the shared verification steps.