atomic-payload
The full Payload + Next.js + Tailwind starter that wires up every Atomic Payload plugin: environment setup, deployment, and optional Mux/Resend integrations.
Overview
Atomic Payload is the complete starter template that brings the whole platform together: Payload for the CMS and admin, Next.js for the frontend and API routes, and Tailwind for styling, with every Atomic Payload plugin already installed and configured. Use this guide whether you scaffolded a project with npx @pro-laico/create-atomic-payload or you're developing from the monorepo template folder.
Developing the monorepo itself? See MONOREPO.md in the repo root for structure, local dev, and per-plugin instructions.
What's pre-wired
You don't need to install or configure any Atomic Payload plugin yourself. They're all registered in src/plugins/index.ts as a flat plugin array. Each plugin bakes its own cache-revalidation hooks, and the shared atomic hook is handed to the plugins that own atomic content, so the wiring is explicit with no magic step to reason about.
| Plugin | What it gives you |
|---|---|
| site | The Pages, Header, and Footer collections plus the SiteMetaData and Settings globals. |
| atomic | The page-building layer: the child blocks that render content, the default form blocks, and the action blocks. |
| styles | The designSet and shortcutSet collections plus the CSS storage globals behind Tailwind-driven styling. |
| fonts | Typeface management (variable fonts or weight files) the site self-hosts via next/font/local. |
| icons | Icon uploads and the IconSet collection, with the Requested icons panel and runtime request tracking turned on. |
| images | The Images and Favicons collections, with on-demand transforms and low-res placeholders. |
| mux-video | The MuxVideo collection for uploading and streaming video through Mux. |
| tracking | The Tracking global for toggling PostHog, Google Tag Manager, or Vercel Analytics from the admin. |
| seed | Tooling rather than a content feature: the Seed database dashboard banner and the POST /api/seed endpoint. |
| richtext | Tooling rather than a content feature: the preconfigured Lexical editor that src/payload.config.ts sets as the editor. |
| zap | Tooling rather than a content feature: the shared schema layer that flows block shapes into your generated types. |
| core | Tooling rather than a content feature: the cache + revalidation helpers, revalidationPlugin, and the jsonSchemaPlugin used during type generation. |
Alongside these, the template registers Payload's form builder and nested docs plugins and Vercel Blob storage for uploads, each configured in its own file under src/plugins/. The form builder's forms and form-submissions collections are the one thing that needs explicit cache wiring (they're third-party, so they don't bake the hooks themselves): revalidationPlugin at the end of src/plugins/index.ts handles them.
Setup
Get required connections
Set up the two external services the template needs:
- Obtain a
MONGODB_URI. The easiest path is through Vercel for a free-tier cluster:Storage → Create Database → MongoDB Atlas. - Create a Blob store in Vercel (
Storage → Create Database → Blob) and copy theBLOB_READ_WRITE_TOKENfrom.env.local.
Configure your project
Copy .env.example to .env, then add the MongoDB URI and Blob token, and generate the Payload and Preview secrets.
# Mongo DB connection string
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster-name>.mongodb.net/my_database?retryWrites=true&w=majority"
# Vercel Blob Read Write Secret
BLOB_READ_WRITE_TOKEN="vercel_blob_rw_laogivGHAOSNeoFS_KJAGsjmeHSkaLQUVhUSHmfPGIXCbHe"
# Used to encrypt JWT tokens
PAYLOAD_SECRET=524AFEAC8E77853C6AC1C2EBCB266
# Used to validate preview requests
PREVIEW_SECRET=77E41879964C5D1C251661663DCD3Create the first admin user
Start the dev server:
pnpm devOpen http://localhost:3000/admin and create the first admin user.
Once running, it's recommended to seed the database from the Seed database banner on the main admin dashboard. Seeding wipes and replaces existing data, so once you've seeded, pass enabled: false to seedPlugin() in src/plugins/index.ts to drop the seed endpoint and its dashboard banner. The Seeding guide walks through the full flow.
Optional integrations
Deploy
Every build runs the template's prebuild script first: pnpm generate:fonts && pnpm generate:icons. The first downloads your uploaded font files from the URL in FONT_DOWNLOAD_URL so the site can self-host them; the second scans src and writes the icon-usage manifest that the IconSet admin panel reads (see Requested icons).
Import your repo into Vercel
Create a new project in Vercel by importing your repo, but before hitting Create, point your local .env at the deployed URL so it's ready to copy into Vercel:
NEXT_PUBLIC_SERVER_URL='https://<project-name>.vercel.app'
FONT_DOWNLOAD_URL='https://<project-name>.vercel.app' # the build's font download targets thisConfigure Vercel environment variables
- Copy all environment variables above into the Vercel project settings.
- Set both
NEXT_PUBLIC_SERVER_URLandFONT_DOWNLOAD_URLto your deployed URL (e.g.https://<project-name>.vercel.app).
Deploy
Trigger a deploy and wait for the build to complete. You now have a working version of Atomic Payload.