Installation

Prerequisites

• Node.js 20.9 or newer. An active LTS release is recommended.
• Git for cloning and upgrades.
• pnpm 10, which matches the included lockfile. npm, Yarn, and Bun also work, but regenerate only one lockfile.

Verify your tools:

node --version
pnpm --version
git --version

Install dependencies

git clone https://github.com/your-org/your-docs.git
cd your-docs
pnpm install

Equivalent package-manager commands:

Warning: Do not commit multiple lockfiles. The lockfile makes local, CI, and production installations resolve the same dependency graph.

Run locally

pnpm dev

Open http://localhost:3000. Changes to MDX, components, and styles update during development.

To expose the server on your local network:

pnpm dev --hostname 0.0.0.0

Production build

pnpm lint
pnpm build
pnpm start

pnpm build compiles MDX, type-checks the application, generates known documentation routes, and produces the optimized Next.js output. Test search, theme switching, and a deep link such as /documentation/overview against the production server.

Common issues

Generated collection modules are missing

If TypeScript cannot resolve collections/server, stop the dev server, remove the generated build output, and rebuild:

Remove-Item -Recurse -Force .next, .source -ErrorAction SilentlyContinue
pnpm dev

The .source directory is generated by the Fumadocs MDX integration and should not be edited.

Port 3000 is already in use

pnpm dev --port 3001

A new page returns 404

Confirm that the file is under content/docs, uses the .mdx extension, and contains valid frontmatter. Restart the development server after changing source.config.ts.

Installation fails after switching package managers

Remove node_modules and lockfiles that do not belong to the selected manager, then install again. Keep pnpm-lock.yaml when using the template's default workflow.

Note: Environment variables are not required for the unmodified template. Add them only for services you integrate; see Configuration.