@cdwr/nx-payload

Adding support for Payload in your Nx workspace.





 

Contents

- Prerequisites
- Next.js Version
- Installation
- Add Payload plugin to an existing workspace
- Inferred tasks
- Configuration
- Usage
- Generate a Payload application
- MongoDB, Postgres, Supabase or SQLite?
- Developer Experience (DX)
- Start Payload and database in Docker
- Start a local database instance of choice
- Serve Payload application in development mode
- Run Payload commands
- Generate TypeScript types and GraphQL schema
- Troubleshooting
- You don't have an Nx workspace?
- Plugin Generators
- Versions Compatibility

Prerequisites

- You have already created an Nx workspace
- Node 20+
- Docker is needed for some of the DX targets

> [!TIP]
> The commands in this readme assume that Nx is installed globally.
>
> ``sh
> nx [...]
> `
>
> If you prefer not to, you can use your preferred package manager to prefix the commands like this example for npm.
>
> `sh
> npx nx [...]
> # or
> npm run nx [...]
> `

Next.js Version

> [!IMPORTANT]
> This plugin installs Next.js v15 when generating a new Payload application, unless your workspace already has a Next.js version installed.

$3

Although Nx v22 scaffolds new Next.js apps using the latest major (currently Next.js v16), the Payload team has not yet marked v16 as fully stable or officially supported.

- Payload v3.42 (the version used during plugin testing) is validated against Next.js v15
- Next.js v16 introduces bundler changes that may impact Payload’s adapters

Next.js v15 provides a predictable experience and avoids subtle compatibility issues.

$3

Yes — the plugin does not prevent you from using Next.js v16. If your workspace already has Next.js v16 installed, the generator will not downgrade it.

However, note that:

- Payload’s official Next.js support currently targets Next.js v15
- Payload v3.54 is required for Next.js v16
- Payload CLI show compatibility issues with pnpm workspaces in version v3.43 and later
- Next.js v16 may require additional configuration depending on your Payload version
- Future releases of Payload (and this plugin) will expand support once the ecosystem stabilizes

If you intentionally want to use Next.js v16, ensure it's installed before adding this plugin, or manually update afterwards.

Installation

> [!IMPORTANT]
> This documentation is aimed for a Payload v3 setup.
>
> To install Payload v2 you should use plugin version 1.x.

_Though it's possible to have applications using Payload v2 and v3 in the same workspace, it's not recommended. Payload v2 supports React 18 and v3 has moved to React 19. But with individual package.json files for the applications and some Dockerfiles sed magic it's possible to make it work._

$3

`sh
nx add @cdwr/nx-payload
`

$3

The plugin automatically generates Payload tasks for projects that has a payload.config.ts file somewhere in the project. The default location is in {projectRoot}/src.

- gen
- payload
- payload-graphql

> [!TIP]
> A couple of targets to improve Developer Experience (DX) are also generated:
>
> - dx:mongodb
> - dx:postgres
> - dx:start
> - dx:stop

$3

Plugin configuration is added to nx.json by default.

`json
{
"plugins": [
{
"plugin": "@cdwr/nx-payload/plugin",
"options": {
"generateTargetName": "gen",
"payloadTargetName": "payload",
"payloadGraphqlTargetName": "payload-graphql",
"dxMongodbTargetName": "dx:mongodb",
"dxPostgresTargetName": "dx:postgres",
"dxStartTargetName": "dx:start",
"dxStopTargetName": "dx:stop"
}
}
]
}
`

#### Opt out from automatic inferrence

To disable automatic targets generation and write explicit targets to project.json, use one of these two options:

- Set useInferencePlugins in nx.json to false
- Set environment variable NX_ADD_PLUGINS to false

Usage

$3

`sh
nx g @cdwr/nx-payload:app
`

$3

Payload has official support for database adapters MongoDB, Postgres and SQLite.

> [!TIP]
>
> Supabase is set up using the Postgres adapter

Changing the adapter for a generated application must be done manually in payload.config.ts.

> [!IMPORTANT]
> We don't want to infer opinionated complexity into the Payload configuration. A new application is just a working template that you will customize and evolve to your needs.

Fortunately, changing the database is straightforward, and only a few parts need to be replaced.

`ts
// MongoDB @ payload.config.ts

import { mongooseAdapter } from '@payloadcms/db-mongodb';

export default buildConfig({
db: mongooseAdapter({
url: process.env.DATABASE_URI
})
});
`

`ts
// Postgres/Supabase @ payload.config.ts

import { postgresAdapter } from '@payloadcms/db-postgres';

export default buildConfig({
db: postgresAdapter({
pool: {
connectionString: process.env.DATABASE_URI
}
})
});
`

> [!TIP]
> More information can be found on the official Payload Database page.

Developer Experience (DX)

The application come with a set of opinionatedtargets to improve developer experience. These targets are prefixed with dx: are optional to use.

> [!TIP]
> Display all the targets with extensive details for an application
>
> `sh
> nx show project [app-name]
> `

$3

This is the quickest way to get Payload up and running in no time.

Using docker compose, both MongoDB and Postgres are started in each container, as well as the Payload application.

`sh
nx dx:start [app-name]
`

Open your browser and navigate to to setup your first user.

#### Stop

Shutdown database and Payload containers.

`sh
nx dx:stop [app-name]
`

Database volumes are persistent, hence all data is available on next launch.

$3

You can also start the preferred database first, to be properly initialized before Payload is served.

#### MongoDB

Run MongoDB in Docker

`sh
nx dx:mongodb [app-name]
`

#### Postgres

Run Postgres in Docker

`sh
nx dx:postgres [app-name]
`

#### Supabase

Supabase has its own powerful toolset running local dev with CLI

`sh
npx supabase init
`

`sh
npx supabase start
`

Edit DATABASE_URI in .env.local when needed.

$3

Payload application is served in watch mode.

> [!NOTE]
> The configured database must have been started, see local database

`sh
nx dev [app-name]
`

Open your browser and navigate to .

$3

All commands available from Payload can be used for the application via targets payload and payload-graphql.

`sh
nx payload [app-name] [payload-command]
`

This is specially useful for managing migrations, for example to check database migration status.

`sh
nx payload [app-name] migrate:status
`

$3

To provide a better developer experience for client development, the plugin can generate TypeScript types and GraphQL schema files from the Payload configuration.

> [!IMPORTANT]
> GraphQL schema will not be generated if graphQL.disable is set to true in payload.config.ts

`sh
nx gen [app-name]
`

The generated files are written to the generated folder.
The types can be distributed to the client developer manually or saved to a shared library in the monorepo.

> [!NOTE]
> The gen target is actually an alias for the following commands.
>
> `sh
> nx payload [app-name] generate:types
> nx payload-graphql [app-name] generate:schema
> `

$3

#### I can't get Payload to start properly with Postgres in prod mode

Using Postgres in development mode enables automatic database synchronization with the Payload collections. But when starting in production mode it's turned off and the database is expected to have been setup with the collections. So when Postgres is started without a database, Payload will encounter errors.

The solution is to have an initial migration ready for Payload to load during startup.

##### Create a migration

Make sure Postgres is running. Start Payload in development mode to setup your database with the collections.

`sh
nx dev [app-name]
`

Create a migration.

`sh
nx payload [app-name] migrate:create
`

Now Payload will run migrations automatically when starting in production mode.

> [!IMPORTANT]
> The property db.prodMigrations in payload.config.ts must be set for this to work.

You don't have an Nx workspace?

Just use the plugin sibling to get started from scratch.

See create-nx-payload for more details.

Plugin Generators

$3

Initialize the @cdwr/nx-payload plugin.

_No options_.

$3

Alias: app

Generate a Payload application powered by Next.js.

| Option | Type | Required | Default | Description |
| ---------------- | ------ | :------: | --------- | ------------------------------------------------------- |
| name | string | ✅ | | The name of the application. |
| directory | string | ✅ | | The path of the application files. |
| database | string | | mongodb | Preferred database to setup [mongodb, postgres]. |
| tags | string | | '' | Comma separated tags. |
| e2eTestRunner | string | | none | The preferred e2e test runner [ playwright, none ]. |
| linter | string | | eslint | The tool to use for running lint checks. |
| unitTestRunner | string | | jest | The preferred unit test runner [ jest, none ]. |

> 💡 name can also be provided as the first argument (used in the examples in this readme)

Versions Compatibility

Later versions of Nx or Payload might work as well, but the versions below have been used during tests.

| Plugin | Nx | Payload | React | Next.js |
| --------- | --------- | --------- | --------- | --------- |
| ^2.2.0 | 22.x | ~3.42.0 | ^19.0.0 | ^15.0.0 |
| ^2.1.0 | 21.x | ~3.42.0 | ^19.0.0 | ^15.0.0 |
| ^2.0.0 | ^20.4.2 | ^3.0.0 | ^19.0.0 | ^15.0.0 |
| ^1.0.0 | 20.x | ^2.30.3 | ^18.0.0 | - |
| ^0.11.0 | 20.x | ^2.30.3 | ^18.0.0 | - |
| ^0.10.0 | 19.x | ^2.8.2 | - | - |
| ^0.9.5 | ^19.5.7 | ^2.8.2 | - | - |
| ^0.9.0 | ^19.0.2 | ^2.8.2 | - | - |
| ^0.8.0 | ^18.3.4 | ^2.8.2 | - | - |
| ^0.7.0 | ~18.2.2 | ^2.8.2 | - | - |
| ^0.6.0 | ~18.1.1 | ^2.8.2 | - | - |
| ^0.5.0 | ~18.0.3 | ^2.8.2 | - | - |
| ^0.1.0 | ^17.0.0 | ^2.5.0` | - | - |