Development Setup | nextjs-cms Contributing

Install the monorepo, run the reference admin app against MySQL, and run the docs site.

Prerequisites

Tool	Version	Used for
Node.js	20.9+	Everything
pnpm	11 (see `packageManager` in the root `package.json`)	Workspaces, catalogs
MySQL 8 or MariaDB	any recent	Running `apps/cms`
Docker	any recent	The integration-test database

Enable pnpm through Corepack if you don't have it: corepack enable.

Install

Terminal

git clone https://github.com/FadiObaji/nextjs-cms.git
cd nextjs-cms
pnpm install

postinstall runs sherif to lint the workspace (consistent dependency versions, no duplicated ranges). Shared versions live in the catalog: section of pnpm-workspace.yaml; reference them as "next": "catalog:" in a package's package.json.

Run everything in watch mode

Terminal

pnpm dev

This runs turbo watch dev across the workspace:

packages/nextjs-cms, packages/translations, and the plugins run tsc --watch and write to dist/.
apps/cms runs next dev on port 3000 and picks up rebuilt packages.
apps/docs runs next dev on port 3001.

Run a single app with a filter:

Terminal

pnpm --filter nextjs-cms-app dev   # the admin
pnpm --filter docs dev             # this site

Good to know:

apps/cms imports nextjs-cms from its compiled dist/, not its source. If a change in the core doesn't show up in the admin, check that the package's tsc --watch is running (it is when you use pnpm dev at the root) and has no type errors.

Connect the admin to a database

apps/cms is a regular nextjs-cms project. Create a MySQL database, then use the CLI from the app folder:

Terminal

cd apps/cms
pnpm nextjs-cms -d setup           # DB credentials → .env.development, system tables, Master admin
pnpm nextjs-cms -d update-sections # create tables for apps/cms/sections

apps/cms/sections contains many sample sections, including __TESTS__ sections that exercise every field type. They're a quick way to reproduce bugs.

apps/cms/.env needs the auth secrets (ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET, CSRF_TOKEN_SECRET, ACCESS_TOKEN_EXPIRATION, REFRESH_TOKEN_EXPIRATION). Any random strings work locally.

The integration-test database

Integration tests run against a disposable MariaDB in Docker on port 3307 (so it never touches your dev database):

Terminal

pnpm test:db:up       # start
pnpm test:integration # run
pnpm test:db:down     # stop (data lives in tmpfs and disappears)

Defaults: host localhost, port 3307, user root, password password, database nextjs_cms_test. Override with TEST_DB_HOST, TEST_DB_PORT, TEST_DB_USER, TEST_DB_PASSWORD, TEST_DB_NAME. See Testing.

Useful commands

Command	What it does
`pnpm build`	Build every package and app
`pnpm build:release`	Build the published core packages (`nextjs-cms`, `create-nextjs-cms`, `@nextjscms/translations`)
`pnpm build:plugins`	Build the official plugins
`pnpm typecheck`	`tsc --noEmit` everywhere
`pnpm lint` / `pnpm lint:fix`	ESLint
`pnpm format` / `pnpm format:fix`	Prettier
`pnpm test:unit`	Unit tests (Node)
`pnpm test:component`	React component tests in headless Chromium
`pnpm test:integration`	Tests against the Docker database
`pnpm vitest run path/to/file.test.ts`	One test file
`pnpm changeset`	Describe your change for the changelog

Editor setup

Use the workspace TypeScript version.
Enable ESLint and Prettier. Formatting is 4 spaces, 120 columns, single quotes, no semicolons, trailing commas, sorted imports and Tailwind classes.