Configuration
One key is required, the collections. A collection may have a base path or go without a parent, and the rest is optional.
pathPlugin({ collections: ['pages', { slug: 'posts', basePath: '/blog', parent: false }], rootSlug: 'home', reservedSegments: { root: { admin: 'the CMS', api: "the CMS's API" }, anyDepth: { '-': 'starts the page and filters of a listing' } }, // makeSlug is yours. slugify: ({ valueToSlugify }) => makeSlug(valueToSlugify), onPathsChanged: ({ changedPaths, payload, req }) => { // Purge your cache here. }})| Key | What it sets | Default |
|---|---|---|
collections |
The collections whose documents get a path, each by its slug or as { slug, basePath, parent, localized, slugField, parentField } |
|
rootSlug |
The slug that makes a top-level document the home page | home |
reservedSegments |
Segments your site serves itself, as a list or each with why | Payload’s admin and API routes |
slugify |
What makes a slug from a title, from what an editor typed and for the slug field’s button, as the slugify of Payload’s own slug field. It may be async |
Accents off Latin letters, other scripts kept |
onPathsChanged |
A function that hears which paths changed | none |
Collections
Section titled “Collections”List a collection by its slug, or as an object when it needs more than that:
pathPlugin({ collections: [ { slug: 'pages', localized: true }, { slug: 'posts', basePath: '/blog', parent: false }, { slug: 'topics', basePath: '/topics' } ]})| Key | What it sets | Default |
|---|---|---|
slug |
The collection | |
basePath |
What the paths of its top-level documents start with, such as /blog |
None, so they start at the root |
parent |
false when its documents have no parent |
Its documents have a parent |
localized |
true when its documents have a path per locale |
One slug and one path, the same in every locale |
slugField |
Field options for the slug field: access, admin, hooks, label and validate |
The plugin’s own |
parentField |
Field options for the plugin’s own parent field: access, admin, filterOptions, hooks and label |
The plugin’s own |
With basePath: '/blog' a top-level post is at /blog/my-post. Leave it out and the collection’s top-level documents sit at the root, like pages. A base path is no document of its own, so a page may sit at /blog beside the posts.
A parent is always a document of the same collection: a page sits below a page and a topic below a topic, and a post below a page isn’t supported. A path still belongs to one document across all your collections.
Each collection gets its parent in one of three ways. In the example above, pages have the plugin’s own parent, posts have none, and topics have Payload’s hierarchy, which the topics collection has in its own config.
| Way | What you write | When it fits |
|---|---|---|
| The plugin’s own parent | The collection, with nothing more | An editor picks the parent in the document’s sidebar |
| No parent | parent: false |
No document sits below another, as with posts below /blog |
| Payload’s hierarchy | hierarchy in the collection’s own config |
You want Payload’s tree in the admin, or the collection has it already |
The plugin’s own parent
Section titled “The plugin’s own parent”This is the default, for a collection listed as 'pages' or as an object without parent. The collection gets a parent field in the sidebar, where an editor picks a document of the same collection.
No parent
Section titled “No parent”With parent: false, every document of the collection is top-level, so its path is the base path, a slash and its slug, such as /blog/hello-world. The collection gets no parent field. Nothing sits below anything, so a rename moves that one document and a delete lifts nothing.
false is the only value parent takes. Leave the key out for a collection whose documents have a parent.
Payload’s hierarchy
Section titled “Payload’s hierarchy”A collection whose own config has Payload’s hierarchy, or its folders or tags preset, keeps Payload’s parent. The plugin adds no parent field of its own and reads the parent from Payload’s, the one hierarchy.parentFieldName names, which is _h_topics for topics by default. Nothing is set in the plugin for it:
export default buildConfig({ collections: [{ slug: 'topics', hierarchy: true, fields: [{ name: 'title', type: 'text' }] }], plugins: [pathPlugin({ collections: [{ slug: 'topics', basePath: '/topics' }] })]})Your site gets Payload’s tree in the admin, and an editor moves a document with the button in the document’s header. The rest works as with the plugin’s own parent: a move takes the branch along, and drafts, languages, taken paths, backfillPaths and onPathsChanged are the same.
A few things are good to know before you start:
- Give
hierarchyastrue, or as an object withparentFieldName. In Payload 4.0.0-beta.10 an object without it breaks every delete in the collection, with or without the plugin. - A delete lifts the documents right below one level, as in any collection. On its own, Payload deletes them.
- Where the collection already has documents with parents, run
backfillPathsonce after you add the plugin, before anything in the collection is deleted. Until then a delete also deletes the documents right below, as Payload does on its own. - Payload’s hierarchy has no parent field in the form, so a refused parent, such as a document below itself, shows on the slug field.
- With
parent: falseas well, the collection keeps Payload’s tree in the admin and gets paths without a parent in them. The plugin lifts nothing there, so a delete deletes the documents right below, as Payload does.
A path per locale
Section titled “A path per locale”A collection’s documents have one slug and one path, the same in every locale, also when your Payload config has localization. With localized: true, they have a slug and a path per locale, so a page can be at /about in English and at /om-oss in Swedish.
true is the only value localized takes, and it goes together with basePath, parent: false and Payload’s hierarchy. In a site without localization it changes nothing. See Languages for how each locale gets its path, and what to do in a collection that already has documents.
Field options
Section titled “Field options”slugField and parentField set Payload’s own field options on the slug field and the parent field the plugin adds. In a site where only the default locale may change a slug, give the slug field Payload’s field access:
pathPlugin({ collections: [ { slug: 'pages', slugField: { access: { update: ({ req }) => req.locale === 'en' } } } ]})In another locale the admin then shows the slug read-only, without its lock and refresh buttons. A save there that sends another slug keeps the slug and the path the page has, and saves the rest of the page.
access,labelandvalidateare used as you give them.admingoes over the plugin’s own, and so do itscomponents, so the slug field keeps its lock and its place in the sidebar unless you set your own.- Your
hooksrun after the plugin’s own, so abeforeValidatehook on the slug gets it cleaned. - Your
filterOptionson the parent holds together with the plugin’s own, so the picker still leaves out the document itself and the home page. It takes what Payload’s ownfilterOptionstakes. parentFieldis only for a collection with the plugin’s own parent, so not for one withparent: falseor Payload’s hierarchy.
Home page
Section titled “Home page”pathPlugin({ collections: ['pages', 'posts'], rootSlug: 'start' })- The top-level document with this slug is the home page, and its path is
/. WithoutrootSlug, the slug ishome. - Only a top-level document in a collection without a base path can be it. A page below another page with the slug
startsits at/about/start, and with posts at/blog, a post with it sits at/blog/start. - The home page holds no documents, since their paths would start with
/start/, which the home page doesn’t answer. - In a collection with a path per locale it is checked per locale, so a page is the home page in the locales where its slug is the root slug.
Reserved slugs
Section titled “Reserved slugs”pathPlugin({ collections: ['pages', 'posts'], reservedSegments: { root: { admin: 'the CMS', api: "the CMS's API" }, anyDepth: { '-': 'starts the page and filters of a listing' } }})- A segment in
rootis refused as a path’s first segment, base path included. Below a parent it is free, so/docs/apiis fine. - A segment in
anyDepthis refused anywhere in a path, such as the-in/journal/-/page/2. - Without
root, the plugin reserves the first segment of Payload’sroutes.adminandroutes.api. Arootyou give is the whole list, so name those two in it, as above. - Each also takes a list, such as
root: ['admin', 'api', 'shop'], and the refusal then gives no reason. - A move or a delete that would put a document on a reserved slug is refused too, and
findByPathanswers a path with one withnull, without asking the database.
Slugify
Section titled “Slugify”import { defaultSlugify, pathPlugin } from '@payloadpack/path'
pathPlugin({ collections: ['pages', 'posts'], // toLatin is yours. slugify: (args) => defaultSlugify({ ...args, valueToSlugify: toLatin(args.valueToSlugify) })})defaultSlugify is what the plugin uses without a slugify of your own, so a rule of yours can run before or after it, as above.
The fields it adds
Section titled “The fields it adds”Each collection in collections gets these fields, after its own:
| Field | What it holds | Which collections get it |
|---|---|---|
parent |
The parent, a relationship to the document’s own collection. Its picker leaves out the document itself and the home page | One with the plugin’s own parent |
slug |
The document’s own segment of the path, shown as Payload’s own slug field, with its lock | Every one |
path |
The stored path, read-only and indexed | Every one |
ancestors |
The ids of the documents above, top-down, an indexed relationship to the document’s own collection. The API returns it and filters by it, and the admin leaves it out | One whose documents have a parent, the plugin’s own or Payload’s |
In a collection given with localized: true, slug and path are localized fields.
When the config is wrong
Section titled “When the config is wrong”The plugin checks its options when Payload builds the config, and stops with one of these:
| Message | What to change |
|---|---|
| @payloadpack/path was given collections the config doesn’t have: posts. | Fix the slug, or list the plugin after the plugin that adds the collection |
| @payloadpack/path was given pages more than once, so list each collection once. | Keep one entry for the collection, with its base path if it has one |
| @payloadpack/path adds slug to pages, so remove its own. | Remove or rename the collection’s own field |
| @payloadpack/path adds no parent field to posts, so leave out its parentField. | Remove parentField, which only the plugin’s own parent field takes |
| @payloadpack/path was given the base path blog for posts, which doesn’t start with a slash, so start it with one. | Write it as /blog |
| @payloadpack/path was given the base path /blog/ for posts, which ends with a slash, so remove that slash. | Write it as /blog |
| @payloadpack/path was given the base path /blog//news for posts, which has an empty segment, so remove the extra slash. | Write it as /blog/news |
| @payloadpack/path was given the base path / for posts, which is the root already, so leave basePath out. | Remove basePath, or give it a segment such as /blog |