Installation
Add the package, add the plugin, and create a migration on Postgres and SQLite.
Install the package
Section titled “Install the package”bun add @payloadpack/pathWith another package manager, run npm install, pnpm add or yarn add instead. Its peer dependencies are payload, @payloadcms/ui and react.
Add the plugin
Section titled “Add the plugin”import { pathPlugin } from '@payloadpack/path'
export default buildConfig({ plugins: [pathPlugin({ collections: ['pages', 'posts'] })]})Pages and posts now have a slug, a parent and their path in the sidebar. A page sits below a page and a post below a post. To start the posts at /blog, list them as { slug: 'posts', basePath: '/blog' }, a base path. List pathPlugin() after any plugin that adds one of its collections.
A collection whose documents never sit below each other, as posts often don’t, takes parent: false, and a collection with Payload’s hierarchy keeps Payload’s parent in place of the plugin’s. See Collections.
The slug field has an admin component, @payloadpack/path/client#SlugField, so the admin’s import map must hold it. Payload’s dev server regenerates the import map. Otherwise run:
bunx payload generate:importmapTransactions
Section titled “Transactions”The plugin works with database transactions and without them, on MongoDB, Postgres and SQLite. It reads and writes through Payload’s own database API, so there is nothing to set up per database.
With transactions, a save, move or delete that fails leaves everything as it was. Without them, which is SQLite’s default, a move that stops halfway leaves some documents at their old paths, and backfillPaths puts them right.
Migrate Postgres and SQLite
Section titled “Migrate Postgres and SQLite”The plugin adds its fields to each collection, so on Postgres and SQLite create a migration for them:
bunx payload migrate:createWith push: true in development, Payload adds the columns on its own.
Documents you already have
Section titled “Documents you already have”The plugin gives a document its path when it is saved. For the documents from before the plugin, run backfillPaths once, in a script or in a migration:
import { backfillPaths } from '@payloadpack/path'
const { left, unchanged, updated } = await backfillPaths({ payload })A collection with Payload’s hierarchy that already has documents with parents needs this run before anything in it is deleted.
A collection that already has a slug or a parent field keeps what its documents hold in them. The plugin adds its own fields with those names, so remove yours first, or remove @payloadcms/plugin-nested-docs from your config when it is what adds parent. The run then makes each document’s path from the slugs and parents that are there. In a site with localization, a slug that isn’t localized today stays one slug with localized: false.
Generate types
Section titled “Generate types”bunx payload generate:typesYour documents then have slug and path in their types, and parent and ancestors in a collection that has them.