nx-payload

    

@cdwr/nx-payload

Adding support for Payload in your Nx workspace.

 

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
  • Build and run application in Docker
  • 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
• mongodb
• payload-build
• payload-cli
• postgres
• start
• stop
• docker-build
• docker-run

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",
        "dockerBuildTargetName": "my-docker-build",
        "dockerRunTargetName": "my-docker-run",
        "mongodbTargetName": "my-mongodb",
        "payloadBuildTargetName": "my-payload-build",
        "payloadCliTargetName": "my-payload-cli",
        "postgresTargetName": "my-postgres",
        "startTargetName": "my-start",
        "stopTargetName": "my-stop"
      }
    }
  ]
}

Opt out from automatic inferrence

Plugin configuration is created automatically, but you can opt out using one of these two options:

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

Note! Created targets will be limited to build, payload-build and payload-cli.

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.

Build and run application in Docker

This is commands that could be used as input to a hosting provider supporting Dockerfile.

It's also an alternative to the docker compose commands start and stop, when you have a custom database setup.

npx nx docker-build [app-name]

Edit application .env file to match the database setup and start the application

npx nx docker-run [app-name]

Hint! Run nx show project [app-name] --web to find the docker build command

Run Payload commands

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

npx nx payload-cli [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-cli [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-cli [app-name] migrate:create

View migration files

npx nx payload-cli [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.

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.
unitTestRunner	string		jest	The preferred unit test runner [ jest, none ].
linter	string		eslint	The tool to use for running lint checks.
skipE2e	boolean		false	Skip generating e2e application.

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

Plugin Executors

build

Build the Express application.

Option	Type	Required	Inferred	Description
main	string	✅	apps/{name}/src/main.ts	The name of the main entry-point. file
outputPath	string	✅	dist/apps/{name}	The output path of the generated. files
outputFileName	string	✅	src/main.js	The relative path, from outputPath, to the output main file. A webpack property required to make serve find the main file.
tsConfig	string	✅	apps/{name}/tsconfig.app.json	The path to the Typescript configuration file.
assets	array of object or string		[]	List of static assets.
clean	boolean		false	Remove previous output before build.

payload-build

Build Payload admin page.

It's usually not needed to run this target manually since it will always run as part of the build target, due to usage of the dependsOn property.

No options.

payload-cli

Run Payload cli commands for an application.

No options.

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

For example to check database migration status

npx nx payload-cli 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.

Plugin version	Nx version	Payload version
^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