Payload CMS: one variable picks the database, and v4 is still canary.37

The scaffold is pnpx create-payload-app, and the examples runner is npx

There is one way in, and it is a generator rather than a library add:

pnpx create-payload-app@latest

The README steers newcomers to the website template, passed as a flag to the same command, and describes it as the one that shows how to do everything, including custom rich text blocks, on-demand revalidation and live preview, with a Tailwind frontend in the same /app folder. What it does not include is a prerequisite list you can read locally: the setup step is a link to the installation page in the documentation, so the Node version and database tooling you need are described on a website rather than in the repository.

The examples work differently, and the difference is easy to miss because the package runner changes:

npx create-payload-app --example example_name

One command uses pnpx and the other uses npx, and the second takes a name from the examples directory rather than a template name. There are thirteen example directories in the tree, covering auth, custom components, a custom server, draft preview, email, a form builder, live preview, localization, multi-tenant, Tailwind with shadcn/ui and a whitelabel setup, plus Astro and Remix. None of them is a starting point for a plain content site, so the website template remains the default choice.

PAYLOAD_DATABASE is one variable with fifteen values behind it

The adapter is chosen in the environment, and the example file names the whole set in a single line:

# Database adapters: mongodb, mongodb-atlas, cosmosdb, documentdb, firestore, postgres, postgres-custom-schema, postgres-uuid, postgres-read-replica, vercel-postgres-read-replica, sqlite, sqlite-uuid, supabase, d1
PAYLOAD_DATABASE=mongodb

The default in that file is MongoDB, which is worth knowing before you assume a Postgres project. Each adapter is also a separately built package in the monorepo, with its own turbo target for db-mongodb, db-postgres, db-sqlite, db-d1-sqlite and db-vercel-postgres, so a Postgres deployment never has to install the MongoDB driver and the choice is a real dependency decision rather than a runtime flag.

Two entries in that list carry more than a name. The read-replica variants need a second connection string, and the example file shows it, with the replica reachable on port 5434 when the project's Docker profile starts it. So a replica topology costs you a second environment variable and a second database to provision, and the comment in the file is the only place that requirement appears.

The two one-click deploys hand you different databases and different storage

The README offers one-click serverless deployment on two platforms, and the two are not variations on the same thing. The Cloudflare path deploys Payload with Workers, R2 for uploads and D1 described as a globally replicated database. The Vercel path deploys a Next.js frontend, a Neon database and Vercel Blob for media storage.

Read that as a platform decision rather than a hosting preference. A one-click deployment chooses your database engine and your object storage for you, and both are named products with their own constraints: R2 against Vercel Blob, D1 against Neon. Moving a project from one to the other later means changing the adapter and the upload plugin, not just moving a DNS record. The project also states that you can deploy anywhere, including serverlessly on Vercel for free, which puts cost in the pitch without stating any limits, so the free path is worth measuring against your own traffic rather than assuming.

For self-hosting, none of this applies and none of it is documented here. The repository shows you adapters, plugins and a generated app, and leaves the deployment to you.

The README calls Payload Next.js native, and the monorepo already holds app-tanstack

The headline claim is that Payload is the first Next.js native CMS, installable directly into an existing /app folder. The repository says something more complicated. There is an app-tanstack directory beside app at the top level, the turbo build filters reference both blank and blank-tanstack templates, and the examples directory contains Astro and Remix projects alongside a custom-server example.

None of that contradicts the default, which is still a Next.js app, but it does change what the positioning means. Next.js native describes the path of least resistance rather than a boundary, and a framework that installs into your app folder is by construction coupled to that folder's runtime. If you are on Astro, Remix or something else, the interesting question is which of those is supported at which version, and the README does not answer it, so you would be finding out from release notes.

The custom-server example is the one that changes the deployment story rather than the runtime story: it suggests Payload can run as its own server instead of only inside a Next.js application, which is the shape you want when the frontend is not Next.js at all.

v4 is shipping as canary.37 while v3.90.x carries the stable tags

The newest releases are two different product lines. v3.90.1 was published on 2026-09-18 and v3.90.2 on 2026-09-23, both stable patches. Between and after them, v4.0.0-canary.37 appeared on 2026-09-24, and the repository's own package.json sits at that same canary version on a branch whose last push was 2026-09-17. The canary number is itself the signal: thirty-seven pre-release builds of v4 have been published, which is a public iteration loop rather than a private one.

For an adopter, the practical effect is that two lines move within days of each other and you have to choose deliberately. Pin a v3 tag if you want stability, and accept that you are choosing the line whose migration story is already written. There is one more detail that matters more than it looks: the README points migrating users at the 3.0 Migration Guide for going from v2 to v3, and the repository contains no equivalent guide for v3 to v4. A team on v3 planning a move to v4 is therefore reading release notes and a canary diff rather than a document written for the transition.

The licence is MIT in LICENSE.md, so the code carries no copyleft obligation either way.

payload-types.ts is committed, so a schema change is a diff you review

Payload generates TypeScript types for your data, and the generated file is committed at the repository root as payload-types.ts. That single fact shapes how development feels. A field added to a collection produces a change in a file you did not write, which lands in your pull request as a large mechanical diff, and it is the clearest signal available that a schema edit landed where you thought it did.

The tooling around that is worth knowing before you contribute. tstyche.json at the top level means types are themselves under test, so a change that breaks the generated types fails a check that never runs your code. The compiler is SWC rather than Babel, configured in .swcrc, and instrumentation.ts plus sentry.client.config.ts and sentry.server.config.ts show error reporting wired into both the client and the server side. Builds run through turbo over a pnpm workspace of packages/* and test/*, with a release.config.js at the root driving releases.

Consequence for an outside contributor: the toolchain is pnpm plus turbo, not npm, and a first build compiles a large workspace before you have changed anything.

Plugins can remove functionality, which moves the floor under your admin panel

Extensibility runs through the admin panel as well as the API. Plugins may add or remove functionality, and the project splits them into officially-supported and community-supported, discoverable through the payload-plugin topic on GitHub. The admin is described as a customizable React app, access control is granular down to the document and field, and there are hooks for every action the framework provides.

That combination is the reason people stay, and it is also the source of the maintenance question. Your app's behaviour is the core plus whatever packages you installed, and those packages move on their own schedules with their own peer ranges against the framework. A core upgrade can therefore change behaviour through a plugin rather than through your code, and the README does not publish a compatibility matrix to check against, so the honest answer is that you test the combination you actually ship.

The practical rule is narrower than the marketing: prefer official plugins where they exist, treat a community plugin as code you own, and read its peer range before every core upgrade rather than after.

Server components replace the API layer, and other clients are unaddressed

One of the feature bullets says you can query your database directly in server components, with no need for REST or GraphQL, and another says the admin and backend are fully extensible. Together they describe a world where the frontend and the data share one process, which is the strongest argument for the framework and also its most quoted limitation.

If every reader is React code inside your app folder, that is exactly the right design. If something else has to read your content, a phone app, a partner integration, a script, then the server-component path does not serve it, and the README does not say which API surfaces a generated project enables by default. That is a question worth answering before you commit, because the shape of the answer decides whether your content is reachable at all.

Authentication is part of the same boundary. The security story is built on HTTP-only cookies and CSRF protection, which is a browser session model. A non-browser client needs a different path, and nothing in the repository describes one, so plan for that before you promise an API to anyone outside the app.

Editorial conclusion

Choose Payload when you want a typed backend and an admin panel inside the same Next.js app folder, and when you are willing to let the framework own your data model instead of bolting a CMS onto a separate frontend. Do not choose it if you need a documented v3 to v4 upgrade path, or a runtime other than Next.js today, because the published migration guide covers v2 to v3 only and the examples already include Astro, Remix and a TanStack app. Verify two things before committing: which database adapter your deploy target supports, since one one-click path hands you D1 and the other Neon, and which build you are on, since the newest tag is a canary published days away from the v3.90 patches.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes