Development Setup

Local setup for working on HeadlessX and the companion docs site.

by @saifyxpro

Product workspace

Recommended prerequisites:

  • Node.js 22
  • pnpm 9 or newer
  • mise if you want a task runner and tool version management
  • Python 3.10 or newer
  • Go for the markdown service
  • PostgreSQL
  • Redis

Clone and install:

Environment file layout

For the product workspace:

  • HeadlessX/.env is the main shared config file
  • HeadlessX/apps/api/.env.local is the API-local override file
  • HeadlessX/apps/web/.env.local is the dashboard-local override file

Use the root .env first, then add app-local override files only when needed.

Manual service boot

If you do not want pnpm dev, the common manual entry points are:

Nx, mise, and Knip

HeadlessX uses three important root-level tools:

ToolWhat it does
Nxorchestrates multi-app tasks like dev, build, and DB commands
miseoptional task runner and tool version manager for local development
Knipfinds unused files, exports, and dependencies

Nx

The root pnpm dev command delegates into Nx:

mise

If you use mise, the repo already defines tasks in HeadlessX/mise.toml:

Knip

Run Knip from the workspace root when cleaning imports and dependencies: