Project setup

1. Copy the source. Place the contents of source/ into your project root or a subdirectory such as ./keystone-src/.

2. Extend the root tsconfig. In your project's tsconfig.json:

   {
     "extends": "./keystone-src/tsconfig.json",
     "compilerOptions": {
       "rootDir": ".",
       "outDir": "./dist"
     },
     "include": ["src", "keystone-src/docs", "keystone-src/packages"]
   }
   

3. Configure pnpm workspaces (if using the full monorepo structure). Copy pnpm-workspace.yaml to your project root and adjust glob patterns to match your layout.

4. Set required environment variables. Create a .env file:

   DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
   SESSION_SECRET="a-secret-at-least-32-characters-long"
   ASSET_BASE_URL="http://localhost:3000"
   

5. Run Prisma migrations after setting up your Keystone schema:

   npx keystone dev
   # or for production
   npx keystone build && npx keystone start
   

6. For the docs site only, navigate to source/docs/ and run pnpm dev or npm run dev. The docs site reads content via Keystatic and renders it with Markdoc.

Public API

getNavigationMap

import { getNavigationMap } from './docs/components/docs/docs-navigation'

async function getNavigationMap(): Promise<
  Array<{
    groupName: string
    items: Array<{
      label: string
      href: string
      status: unknown
    }>
  }> | undefined
>

Reads navigation groups and doc page slugs from the Keystatic reader, joins them, and returns a structured navigation tree. Use this in a Next.js server component or getStaticProps to build sidebar navigation for a documentation site.

DocsNavigation

import { DocsNavigation } from './docs/components/docs/docs-navigation'

async function DocsNavigation(): Promise<JSX.Element>

An async React server component that calls getNavigationMap internally and delegates rendering to DocsNavigationClient. Drop it into any Next.js App Router layout to render a fully data-driven documentation sidebar without manual data fetching.

readDocsContent

import { readDocsContent } from './docs/markdoc'

async function readDocsContent(filepath: string): Promise<{
  content: Tag   // Markdoc Tag tree ready for rendering
  title: string
  description: string
}>

Reads a Markdoc .md file from disk, extracts YAML frontmatter for title and description, validates the document against the base Markdoc config, and returns the transformed tag tree. Use this when building a custom docs renderer or static site generator on top of the Keystone docs content pipeline.

printValidationError

import { printValidationError } from './docs/markdoc'
import type { ValidateError } from '@markdoc/markdoc'

function printValidationError(error: ValidateError): string

Formats a Markdoc ValidateError into a human-readable string including file path, 1-based line number, optional character offset, and the error message. Use this in build scripts or CI to surface authoring errors in Markdoc documents without crashing the process.

Working examples

Scenario - Render documentation navigation in a Next.js App Router layout

Server-side navigation assembled from Keystatic content collections and rendered into a sidebar.

// app/docs/layout.tsx
import { DocsNavigation } from '../../keystone-src/docs/components/docs/docs-navigation'

export default function DocsLayout({ children }: { children: React.ReactNode }) {
  return (
    <div style={{ display: 'flex' }}>
      <aside style={{ width: 260 }}>
        <DocsNavigation />
      </aside>
      <main style={{ flex: 1 }}>{children}</main>
    </div>
  )
}

Scenario - Build a static documentation page from a Markdoc file

Read and transform a Markdoc document into a renderable tag tree for a Next.js page.

// scripts/build-docs.ts
import path from 'path'
import Markdoc from '@markdoc/markdoc'
import { readDocsContent, printValidationError } from '../keystone-src/docs/markdoc'

async function main() {
  const filepath = path.resolve('content/docs/getting-started.md')

  try {
    const { content, title, description } = await readDocsContent(filepath)
    const html = Markdoc.renderers.html(content)
    console.log(`Title: ${title}`)
    console.log(`Description: ${description}`)
    console.log(`HTML length: ${html.length}`)
  } catch (err) {
    console.error('Failed to build doc:', err)
    process.exit(1)
  }
}

main()

Scenario - Custom navigation map consumer

Use getNavigationMap directly to generate a JSON sitemap or validate all hrefs at build time.

// scripts/validate-nav.ts
import { getNavigationMap } from '../keystone-src/docs/components/docs/docs-navigation'

async function validateNav() {
  const navigationMap = await getNavigationMap()
  if (!navigationMap) {
    console.warn('No navigation defined.')
    return
  }

  const broken: string[] = []
  for (const group of navigationMap) {
    for (const item of group.items) {
      if (!item.href) {
        broken.push(`${group.groupName} > ${item.label}: missing href`)
      }
    }
  }

  if (broken.length > 0) {
    console.error('Broken navigation entries:\n' + broken.join('\n'))
    process.exit(1)
  }

  console.log(`Navigation valid: ${navigationMap.length} groups.`)
}

validateNav()

File walkthrough

• .changeset/ - Per-PR markdown changesets consumed by changeset version and changeset publish to automate semver bumps and CHANGELOG entries.
• .devcontainer/ - Defines the Docker-based VS Code development container so all contributors get an identical Node/pnpm environment.
• .github/ - CI pipelines (lint, type-check, test, release) and community health files.
• docs/ - Next.js 14 App Router documentation website. Contains Markdoc rendering pipeline, Keystatic reader integration, React server components for navigation and featured content, and all icon components.
• examples/ - Self-contained Keystone projects demonstrating auth, relationships, custom fields, REST API, and more. Each is runnable independently.
• packages/ - Source for every published @keystone-6/* npm package including core, auth, fields-document, and cloudinary.
• prisma-utils/ - Helpers for Prisma schema management used internally by @keystone-6/core during migrations.
• scripts/ - Internal scripts for workspace maintenance, contributor tooling, and release automation.
• tests2/ - Integration tests that spin up real Keystone instances against a live database to verify end-to-end behavior.
• babel.config.js - Root Babel config used by Jest for CJS transforms of ESM packages.
• eslint.config.mjs - Flat ESLint config enforcing consistent style across all packages and the docs site.
• jest.config.mjs / vitest.config.ts - Test runner configurations; Jest is used for integration tests, Vitest for fast unit tests.
• pnpm-workspace.yaml - Declares all workspace package glob patterns so pnpm can hoist and link local packages.
• tsconfig.json - Root TypeScript project references config; individual packages extend it.

Common pitfalls and fixes

• DATABASE_URL not set at build time. Keystone and Prisma both read DATABASE_URL at startup; missing it throws a cryptic Prisma client error. Fix: ensure .env is loaded before running any Keystone or Prisma commands.
• pnpm vs npm workspace incompatibility. The monorepo uses pnpm-workspace.yaml; running npm install at the root will not link local packages correctly. Fix: install pnpm globally (npm i -g pnpm) and use pnpm install.
• Keystatic reader failing in non-Next.js contexts. docs/keystatic/reader.ts is wired for the Next.js file system. Using it in a plain Node script requires setting the correct cwd or mocking the file reader. Fix: only call getNavigationMap / readDocsContent inside a Next.js server context or a script that runs from the docs/ directory.
• Markdoc validation errors swallowed silently. If you skip calling printValidationError in your error handler, validation failures from readDocsContent will produce an opaque MarkdocValidationFailure. Fix: wrap calls in try/catch and log err.message which already contains formatted line numbers.
• ESM/CJS interop with date-fns and js-yaml. Some bundlers fail when mixing ESM and CJS. Fix: add "type": "module" to your root package.json and ensure babel.config.js transforms only test files, not production builds.
• React server component boundaries. DocsNavigation is an async server component and cannot be imported into a client component directly. Fix: wrap it in a <Suspense> boundary or keep it strictly in server-only layout files.

Vibe-coding prompt template

I have purchased the Keystone CMS monorepo source block. The source is in ./keystone-src/
and there is a USAGE.md at the root explaining all exports and setup steps.

The upstream package is @keystone-6/mono-repo (keystonejs/keystone on GitHub).

Please help me integrate this into my existing Next.js 14 App Router project step by step:

1. Read USAGE.md and source/docs/components/docs/docs-navigation/index.tsx to understand
   the DocsNavigation server component and getNavigationMap function.
2. Read source/docs/markdoc/index.ts to understand readDocsContent and printValidationError.
3. Add DocsNavigation to my app/docs/layout.tsx sidebar.
4. Create a script at scripts/build-docs.ts that uses readDocsContent to pre-render all
   markdown files under content/docs/ to HTML and writes them to public/docs/.
5. Add a CI step in .github/workflows/ci.yml that runs the validate-nav script shown in USAGE.md.
6. Make sure all required environment variables (DATABASE_URL, SESSION_SECRET) are documented
   in a .env.example file.
7. Point out any TypeScript errors or missing peer dependencies and fix them.

License and credit

Keystone is released under the MIT License. See source/LICENSE for the full text.

Upstream project: keystonejs/keystone — maintained by Thinkmill. Published to npm as @keystone-6/core.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Webiny Serverless CMS Platform for AWS Enterprises

CRM, ERP, Admin & Internal Tools

Free