Payload template

Scaffold, configure and maintain the Payload + Next.js starter.

On this page

Scaffold the Payload and Next.js starter with the CLI, configure it and keep it current. To build the same setup by hand, see Install in a Payload project.

Quick startLink to this section

1. Configure registry accessLink to this section

Set up the .npmrc and GITHUB_TOKEN described in Registry access before installing.

2. Scaffold the projectLink to this section

Use the global CLI:

pnpm dlx @systhemaui/cli@latest create my-app --template payload

# Or with the global CLI installed.
pnpm add -g @systhemaui/cli
systhema create my-app --template payload

Run one scaffold command, then enter its output directory:

cd my-app

3. Install dependenciesLink to this section

pnpm install

4. Copy design tokensLink to this section

Place exported token JSON files in src/tokens/. They come out of the Figma plugin.

5. Sync tokens and typesLink to this section

Synchronize the project's token files into the @systhemaui/core package, generate payload-types.ts, and rebuild Payload's importMap.js:

pnpm sync

The template's sync script chains together Systhema's sync, Payload type generation, and import-map generation. Re-run it whenever tokens, config, or @systhemaui/* packages change. Its install hook refreshes the package token cache when generated artifacts already exist. Otherwise, run pnpm sync before the first type check.

6. Start buildingLink to this section

pnpm dev

You're ready to use Systhema components in your Payload + Next.js app.

Replacing the placeholder brandingLink to this section

Everything the visitor sees ships with Systhema's mark as a placeholder. It's there so a fresh scaffold is never iconless, and so you have a checklist of what a real project needs. Replace all of it with the project's own branding before launch:

File(s)	What it is
The `Logo` component in `src/app/(site)/template.tsx`	Header and footer logo
`src/app/icon.svg`	Browser tab icon, vector, swaps color with the visitor's light/dark theme
`src/app/favicon.ico`	Legacy fallback (16/32/48px) for browsers without SVG favicon support
`src/app/apple-icon.png`	iOS home-screen icon
`src/app/manifest.json`, `public/web-app-manifest-{192x192,512x512}.png`	Web app manifest and its `maskable` install icons, edit the name and theme colors
General Settings → SEO → default share image	The social/OG card image, set in the admin rather than as a file

These are never overwritten by an upgrade. (site)/template.tsx is a scaffold file (user-owned, written once), and the favicons only ship with systhema create, so once you've replaced them, they stay replaced.

To build the same project by hand and see what each piece does, follow Install in a Payload project.

Ongoing maintenanceLink to this section

Re-run pnpm sync (or the three sub-commands) after any design-system update.
Keep your GITHUB_TOKEN active. Package installs fail immediately if it expires.
Check in exported token inputs so every environment uses the same baseline.
Run systhema upgrade when new Systhema versions ship, see @systhemaui/cli.
After upgrading @systhemaui/payload, the upgrade flow re-runs pnpm systhema-core payload create-app-files --override for you. Managed files use .systhema/managed-files.json to distinguish an old Systhema version from local edits. An edited managed file stays in place and the latest template appears beside it as <path>.new; scaffold files (your customized layout.tsx, globals.css, template.tsx, etc.) are left alone. Diff the files, merge the changes, and delete the .new file. The first differing pre-ledger managed file is backed up to <path>.bak before refresh, except a customized src/proxy.ts, which is kept with the template beside it as src/proxy.ts.new.
For production builds and hosting, see Deploying.