TypematterInternal Docs
English
简体中文English✓
System
Get started

Deployment

Experimentalv0.4.0-rc
Version links
Currentv0.4.0-rcChangelogv0.4.0-rc

Typematter currently targets Next.js static export, so npm run build writes a fully static site into out/.

The official Typematter repository is best treated as:

  • official documentation site
  • live demo
  • capability showcase

For real adoption, generate a separate docs repository for each team or product instead of continuing to author inside the official repo. That keeps official examples, demos, and product-specific content isolated, and makes configuration and release workflows easier to manage.

Recommended setup

Treat the official repository as a reference implementation or demo site. For actual use, generate a clean project with npm run typematter -- init --dir ../my-docs and maintain docs in that new repository.

Generate a Standalone Project From the Official Repo

  1. Clone the official Typematter repository.

  2. Run npm run typematter -- init --dir ../my-docs outside the repo.

  3. Enter the new directory and run npm install and npm run dev.

  4. Replace content/, then update site.config.ts and nav.config.ts for the target information architecture.

Required environment variables before build

Required:

  • TYPEMATTER_SITE_URL=https://docs.example.com

Optional but recommended:

  • NEXT_PUBLIC_SITE_URL=https://docs.example.com
  • NEXT_PUBLIC_TYPEMATTER_ASK_AI_ENDPOINT=https://<your-worker-domain>
  • NEXT_PUBLIC_TYPEMATTER_ASK_AI_TIMEOUT_MS=25000
  • NEXT_PUBLIC_TYPEMATTER_ASK_AI_ENABLED=true
Why TYPEMATTER_SITE_URL is the only must-have

It controls the absolute domain emitted into robots.txt and sitemap.xml during the build. Without it, the build falls back to the example domain.

Production deployment

  1. Copy .env.example and fill in the site domain and optional Ask AI values.

  2. Run npm run validate:docs to verify content, navigation, and links before deployment.

  3. Run npm run build to generate the static site and search artifacts.

  4. Deploy the out/ directory to any static host.

What the build generates

  • out/: final static site
  • .typematter/registry.json: content registry cache
  • public/typematter/search/: search manifest, docs index, shards
  • public/robots.txt
  • public/sitemap.xml

Good hosting targets

  • Vercel

    Build and publish the static output directly.

  • Cloudflare Pages

    Good fit for edge-distributed static hosting.

  • Nginx / OSS / S3

    Anything that can serve HTML, CSS, and JS works.

Vercel

  • Build Command: npm run build
  • Output Directory: out
  • Environment Variables: at least TYPEMATTER_SITE_URL

Cloudflare Pages

  • Build Command: npm run build
  • Build Output Directory: out
  • If you want Ask AI, deploy integrations/cloudflare-ask-ai-worker/ separately

Nginx / OSS / S3

  • Upload the generated out/ directory
  • Serve the files as plain static assets
  • If you run Nginx yourself, point the site root at out/

Local preview of the production build

npm
>_Terminal
npm run buildnpx serve out

Ask AI is optional and separate from static hosting

The static docs site does not depend on the Worker. Additional setup is only required when Ask AI should be enabled:

  • integrations/cloudflare-ask-ai-worker/README.md
  • NEXT_PUBLIC_TYPEMATTER_ASK_AI_ENDPOINT

Troubleshooting

robots.txt / sitemap.xml still points to example.com

TYPEMATTER_SITE_URL was not set when the build ran.

Typematter validates doc quality before building. Run npm run validate:docs first, then fix the reported content, navigation, or link issue.

I want a clean project without the official docs content

Use npm run typematter -- init --dir ../my-docs instead of continuing to write inside the official repository.

Why TYPEMATTER_SITE_URL is required

Typematter uses it to emit absolute URLs inside robots.txt and sitemap.xml. Without it, the generated files fall back to an example domain.