Adding support for Payload in your Nx workspace.

 

• Prerequisites
• 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
• Migrate from Payload v2 to v3
  • Preparation
  • Packages
• Versions Compatibility

• You have already created an Nx workspace
• Node 20+
• Docker

The commands in this readme assume that Nx is installed globally.

nx [...]

If you prefer not to, you can use your preferred package manager to prefix the commands like this example for npm.

npx nx [...]
# or
npm run nx [...]

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.

nx add @cdwr/nx-payload

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

Plugin configuration is added to nx.json by default.

{
  "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"
      }
    }
  ]
}

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

nx g @cdwr/nx-payload:app

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

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

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

// MongoDB @ payload.config.ts

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

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

// Postgres/Supabase @ payload.config.ts

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

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

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

nx show project [app-name]

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.

nx dx:start [app-name]

Open your browser and navigate to http://localhost:3000 to setup your first user.

Shutdown database and Payload containers.

nx dx:stop [app-name]

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

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

Run MongoDB in Docker

nx dx:mongodb [app-name]

Run Postgres in Docker

nx dx:postgres [app-name]

Supabase has its own powerful toolset running local dev with CLI

npx supabase init

npx supabase start

Edit DATABASE_URI in .env.local when needed.

Payload application is served in watch mode.

nx dev [app-name]

Open your browser and navigate to http://localhost:3000.

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

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

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

nx payload [app-name] migrate:status

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

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.

nx payload [app-name] generate:types
nx payload-graphql [app-name] generate:schema

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.

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

nx dev [app-name]

Create a migration.

nx payload [app-name] migrate:create

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

Just use the plugin sibling to get started from scratch.

See create-nx-payload for more details.

Initialize the @cdwr/nx-payload plugin.

No options.

Alias: app

Generate a Payload application powered by Next.js.

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

Most of the setup is the same, but there are some breaking changes that you need to be aware of. Besides that, follow the type errors to update the code.

• Nx must have version 20.4.2 or higher.
• React must have version 19.0.0 or higher.
• Install @nx/next plugin.
• Install @nx/eslint plugin.
  • Convert to flat file configuration.
  • Use eslint.config.mjs files.
• Install graphql package.

Payload now use a common version for its packages.

Install new packages:

• @payloadcms/next
• @payloadcms/graphql (dev dependency)

Update to latest:

• payload
• @payloadcms/db-mongodb
• @payloadcms/db-postgres
• @payloadcms/richtext-lexical

Remove deprecated packages:

• @payloadcms/bundler-webpack
• @payloadcms/richtext-slate
• @nx/express (used elsewhere?)

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