Quick start

Scaffold a brand-new Atomic Payload project and land on a running dev server.

Prerequisites

Node.js 18+
pnpm (recommended). Install it with npm install -g pnpm.
A MongoDB connection string, only for the full atomic-payload template. The minimal examples ship with SQLite and need no database server.

Scaffold

Run the CLI

Point the scaffolder at a new project directory (or . for the current one):

npx @pro-laico/create-atomic-payload my-project

pnpm dlx @pro-laico/create-atomic-payload my-project

To scaffold into the current directory instead, pass .:

npx @pro-laico/create-atomic-payload .

Choose a scaffold

The CLI prompts for which scaffold to create. Pick one, or skip the prompt with the --template <name> (-t) flag:

Scaffold	What you get
`atomic-payload`	Full starter (the default): Payload + Next.js + Tailwind, every plugin
`fonts-only`	Minimal example: `@pro-laico/fonts` in isolation
`icons-only`	Minimal example: `@pro-laico/icons` in isolation
`styles-only`	Minimal example: `@pro-laico/styles` in isolation

npx @pro-laico/create-atomic-payload my-icons --template icons-only

When no name is given, the project folder defaults to my-<scaffold>. Project names use only lowercase letters, numbers, and hyphens (or . for the current directory).

Let it install and set up

Once you've chosen a scaffold, the CLI does the rest:

Copies the template into your target directory.
Installs dependencies with pnpm.
Rebuilds sharp for your platform.
Downloads fonts (for scaffolds that ship a font step).

It also copies .env.example to .env so the project is ready to run. When it finishes, you'll see the next steps printed in your terminal.

Configure and run

How much you configure depends on the scaffold. The full template wires up a real database and storage; the examples run on SQLite out of the box, so there's much less to fill in.

Open .env and fill in the four required values: a MongoDB connection string, a Vercel Blob token, your PAYLOAD_SECRET, and NEXT_PUBLIC_SERVER_URL. Environment & prerequisites walks through each one. Then generate types and the import map, and start dev:

pnpm generate:types        # src/payload-types.ts + augment
pnpm generate:importmap    # src/app/(payload)/admin/importMap.js
pnpm dev

The examples ship with SQLite (./<example>.db), so there's no database server to set up. Just set a long PAYLOAD_SECRET in .env, then generate types and the import map, and start dev:

pnpm generate:types        # src/payload-types.ts + augment
pnpm generate:importmap    # src/app/(payload)/admin/importMap.js
pnpm dev

Swap SQLite for any Payload-supported adapter by editing src/payload.config.ts and setting the matching connection string in .env.

Configure your database, Payload secret, and storage in Environment & prerequisites.