@cdwr/nx-payload v0.7.1

Contents

• Prerequisites
• Installation
  • Add Payload plugin to an existing workspace
  • Inferred tasks
  • Configuration
• Usage
  • Generate a Payload application
  • MongoDB, Postgres or Supabase?
• DX
  • Start Payload and database in Docker
  • Start a local database instance of choice
  • Serve Payload application in development mode
  • Run Payload commands
  • Troubleshooting
    • I can't get Payload to start properly with Postgres in prod mode
• You don't have an Nx workspace?
• Plugin Generators
• Plugin Executors
• Plugin Migrations
• Versions Compatibility

Prerequisites

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

Installation

Add Payload plugin to an existing workspace

npx nx add @cdwr/nx-payload

Inferred tasks

The plugin automatically creates tasks for projects with a payload.config.ts configuration file:

• build
• payload

Configuration

// nx.json
{
  "plugins": [
    "@cdwr/nx-payload/plugin"
  ]
}

or use options to assign custom target names

// nx.json
{
  "plugins": [
    {
      "plugin": "@cdwr/nx-payload/plugin",
      "options": {
        "buildTargetName": "my-build",
        "payloadTargetName": "my-payload"
      }
    }
  ]
}

Plugin configuration is created automatically, but you can opt out by setting useInferencePlugins = false in nx.json

Usage

Generate a Payload application

npx nx generate @cdwr/nx-payload:app

MongoDB, Postgres or Supabase?

Payload has official support for database adapters MongoDB and Postgres.

This plugin supports setting up either one via the database option.

Supabase should be set up using the Postgres adapter

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

We don't want to infer opinionated complexity into Payload configuration

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.MONGO_URL,
    migrationDir: resolve(__dirname, 'migrations')
  })
});

// Postgres/Supabase @ payload.config.ts

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

export default buildConfig({
  db: postgresAdapter({
    pool: {
      connectionString: process.env.POSTGRES_URL
    },
    migrationDir: resolve(__dirname, 'migrations')
  })
});

More information can be found on the official Payload Database page.

DX

Generated applications come with a set of Nx targets to help you get started.

Start Payload and database in Docker

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.

npx nx start [app-name]

The app name is optional for the default app specified in nx.json. Specify the app name when launching a non-default app.

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

Supabase is not included in this Docker setup. Instead, start your preferred database manually and run the Payload app in development mode.

Stop

Shutdown database and Payload containers.

npx nx stop [app-name]

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

Start a local database instance of choice

It's better to start the preferred database first, to be properly initialized before Payload is served.

MongoDB

Run MongoDB in Docker

npx nx mongodb

Postgres

Run Postgres in Docker

npx nx postgres

Supabase

Supabase has its own powerful toolset running local dev with CLI

npx supabase init

npx supabase start

Edit POSTGRES_URL in .env.

Serve Payload application in development mode

Payload application is served in watch mode.

The configured database must have been started, see local database

npx nx serve [app-name]

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

Run Payload commands

All commands available from Payload can be used by the generated application via target payload.

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

This is specially useful for managing migrations.

Troubleshooting

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

Using Postgres in dev mode (serve) enables automatic migration. But when starting in prod mode it's turned off. So when the database is started without data, Payload will encounter errors once started (e.g. in Docker).

The solution is to run a migration on the database before Payload is started.

npx nx payload [app-name] migrate

How do I create a migration file?

Start Payload in dev mode to seed your collection data. Then create a migration file in a second terminal.

npx nx serve [app-name]

npx nx payload [app-name] migrate:create

View migration files

npx nx payload [app-name] migrate:status

You don't have an Nx workspace?

Just use the plugin create package to get started from scratch.

See create-nx-payload for more details.

Plugin Generators

init (internal)

Initialize the @cdwr/nx-payload plugin.

No options.

application

Alias: app

Generate a Payload application served by Express.

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

Plugin Executors

build

Build a Payload application.

payload

Run Payload commands for an application.

No options.

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

For example to check database migration status

npx nx payload my-app migrate:status

Plugin Migrations

None.

Versions Compatibility

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