docs: misc improvements (#7107)

This commit is contained in:
Jacob Fletcher
2024-07-11 09:54:21 -04:00
committed by GitHub
parent e2b06abb60
commit a1bb661a1a
65 changed files with 215 additions and 199 deletions

View File

@@ -6,7 +6,7 @@ desc: Manage your data and customize the Payload Admin Panel by swapping in your
keywords: admin, components, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: admin, components, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
Payload dynamically generates a beautiful, [fully type-safe](../typescript/overview) admin panel to manage your users and data. It is highly performant, even with 100+ fields, and is translated in over 30 languages. Within the Admin Panel you can manage content, [render your site](../live-preview/overview), preview drafts, [diff versions](../versions/overview), and so much more. Payload dynamically generates a beautiful, [fully type-safe](../typescript/overview) Admin Panel to manage your users and data. It is highly performant, even with 100+ fields, and is translated in over 30 languages. Within the Admin Panel you can manage content, [render your site](../live-preview/overview), preview drafts, [diff versions](../versions/overview), and so much more.
The Admin Panel is designed to [white-label your brand](https://payloadcms.com/blog/white-label-admin-ui). You can endlessly customize and extend the Admin UI by swapping in your own [Custom Components](./components)—everything from simple field labels to entire views can be modified or replaced to perfectly tailor the interface for your editors. The Admin Panel is designed to [white-label your brand](https://payloadcms.com/blog/white-label-admin-ui). You can endlessly customize and extend the Admin UI by swapping in your own [Custom Components](./components)—everything from simple field labels to entire views can be modified or replaced to perfectly tailor the interface for your editors.

View File

@@ -169,7 +169,7 @@ Example:
### Admin autologin ### Admin autologin
For testing and demo purposes you may want to skip forcing the admin user to login in order to access the panel. For testing and demo purposes you may want to skip forcing the admin user to login in order to access the panel.
The `admin.autologin` property is used to configure the how visitors are handled when accessing the admin panel. The `admin.autologin` property is used to configure the how visitors are handled when accessing the Admin Panel.
The default is that all users will have to login and this should not be enabled for environments where data needs to protected. The default is that all users will have to login and this should not be enabled for environments where data needs to protected.
#### autoLogin Options #### autoLogin Options

View File

@@ -65,7 +65,7 @@ In this scenario, if your cookie was still valid, malicious-intent.com would be
### CSRF Prevention ### CSRF Prevention
Define domains that your trust and are willing to accept Payload HTTP-only cookie based requests from. Use the `csrf` option on the base Payload config to do this: Define domains that your trust and are willing to accept Payload HTTP-only cookie based requests from. Use the `csrf` option on the base Payload Config to do this:
```ts ```ts
// payload.config.ts // payload.config.ts

View File

@@ -18,7 +18,7 @@ keywords: authentication, config, configuration, overview, documentation, Conten
Authentication is used within the [Admin Panel](../admin/overview) itself as well as throughout your app(s) themselves however you determine necessary. Authentication is used within the [Admin Panel](../admin/overview) itself as well as throughout your app(s) themselves however you determine necessary.
![Authentication admin panel functionality](https://payloadcms.com/images/docs/auth-admin.jpg) ![Authentication Admin Panel functionality](https://payloadcms.com/images/docs/auth-admin.jpg)
_Admin Panel screenshot depicting an Admins Collection with Auth enabled_ _Admin Panel screenshot depicting an Admins Collection with Auth enabled_
**Here are some common use cases of Authentication outside of Payload's dashboard itself:** **Here are some common use cases of Authentication outside of Payload's dashboard itself:**
@@ -73,7 +73,7 @@ Once enabled, each document that is created within the Collection can be thought
## Authentication Strategies ## Authentication Strategies
Out of the box Payload ships with a few powerful authentication strategies. HTTP-Only Cookies, JWT's and API-Keys, they can work together or individually. You can also have multiple collections that have auth enabled, but only 1 of them can be used to log into the admin panel. Out of the box Payload ships with a few powerful authentication strategies. HTTP-Only Cookies, JWT's and API-Keys, they can work together or individually. You can also have multiple collections that have auth enabled, but only 1 of them can be used to log into the Admin Panel.
### HTTP-Only Cookies ### HTTP-Only Cookies

View File

@@ -98,7 +98,7 @@ From there, you are ready to make updates to your project. When you are ready to
## Cloud Plugin ## Cloud Plugin
Projects generated from a template will come pre-configured with the official Cloud Plugin, but if you are using your own repository you will need to add this into your project. To do so, add the plugin to your Payload config: Projects generated from a template will come pre-configured with the official Cloud Plugin, but if you are using your own repository you will need to add this into your project. To do so, add the plugin to your Payload Config:
`yarn add @payloadcms/plugin-cloud` `yarn add @payloadcms/plugin-cloud`
@@ -113,7 +113,7 @@ export default buildConfig({
``` ```
<Banner type="warning"> <Banner type="warning">
**Note:** If your Payload config already has an email with transport, this will take precedence **Note:** If your Payload Config already has an email with transport, this will take precedence
over Payload Cloud's email service. over Payload Cloud's email service.
</Banner> </Banner>

View File

@@ -6,7 +6,11 @@ desc: Structure your Collections for your needs by defining fields, adding slugs
keywords: collections, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: collections, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
A Collection is a group of records, called Documents, that share a schema. You can define as many Collections as your application needs. Each Collection will automatically scaffold a new collection or table in your [Database](../database/overview) based on the [Fields](../fields/overview) that you define. A Collection is a group of records, called Documents, that share a common schema. You can define as many Collections as your application needs. Each Collection saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define.
Collections are the primary way to structure recurring data in your application, such as users, products, pages, posts, and other types of content that you might want to manage. Each Collection can have its own unique [Access Control](../access-control/overview), [Hooks](../hooks/overview), [Admin Options](#admin-options), and more.
Collections will automatically generate their own [Local API](../local-api/overview). If your application is using the [Admin Panel](../admin/overview), you will also get a fully-featured [REST API](../rest-api/overview) and [GraphQL API](../graphql/overview) without any additional configuration.
To define a Collection Config, use the `collection` property in your [Payload Config](./overview): To define a Collection Config, use the `collection` property in your [Payload Config](./overview):
@@ -43,7 +47,7 @@ export const Posts: CollectionConfig = {
<Banner type="success"> <Banner type="success">
<strong>Reminder:</strong> <strong>Reminder:</strong>
For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub. For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub, or the [Templates](https://github.com/payloadcms/payload/tree/main/templates) and [Examples](https://github.com/payloadcms/payload/tree/main/examples) directories in the Payload repository.
</Banner> </Banner>
The following options are available: The following options are available:
@@ -60,7 +64,7 @@ The following options are available:
| **`endpoints`** | Add custom routes to the REST API. Set to `false` to disable routes. [More details](../rest-api/overview#custom-endpoints). | | **`endpoints`** | Add custom routes to the REST API. Set to `false` to disable routes. [More details](../rest-api/overview#custom-endpoints). |
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Collection. [Click here](../fields/overview) for a full list of field types as well as how to configure them. | | **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Collection. [Click here](../fields/overview) for a full list of field types as well as how to configure them. |
| **`graphQL`** | An object with `singularName` and `pluralName` strings used in schema generation. Auto-generated from slug if not defined. Set to `false` to disable GraphQL. | | **`graphQL`** | An object with `singularName` and `pluralName` strings used in schema generation. Auto-generated from slug if not defined. Set to `false` to disable GraphQL. |
| **`hooks`** | Entry points to "tie in" to Collection actions at specific points. [More details](../hooks/overview#collection-hooks). | | **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#collection-hooks). |
| **`labels`** | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined. | | **`labels`** | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined. |
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Collection. | | **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Collection. |
| **`timestamps`** | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps. | | **`timestamps`** | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps. |
@@ -70,11 +74,23 @@ The following options are available:
_\* An asterisk denotes that a property is required._ _\* An asterisk denotes that a property is required._
## Admin Options ### Fields
Fields define the schema of the Documents within a Collection. To learn more, go to the [Fields](../fields/overview) documentation.
### Access Control
Access Control determines what a user can and cannot do with a Document. To learn more, go to the [Access Control](../access-control/overview) docs.
### Hooks
Hooks allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the [Hooks](../hooks/overview) documentation.
### Admin Options
You can customize the way that the [Admin Panel](../admin/overview) behaves on a Collection-by-Collection basis. You can customize the way that the [Admin Panel](../admin/overview) behaves on a Collection-by-Collection basis.
To configure Collection Admin Options, use the `admin` property in your Collection Config: To configure Admin Options for Collections, use the `admin` property in your Collection Config:
```ts ```ts
import { CollectionConfig } from 'payload' import { CollectionConfig } from 'payload'
@@ -144,7 +160,7 @@ The preview function receives two arguments:
For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples). For fully working example of this, check of the official [Draft Preview Example](https://github.com/payloadcms/payload/tree/main/examples/draft-preview) in the [Examples Directory](https://github.com/payloadcms/payload/tree/main/examples).
</Banner> </Banner>
### Pagination #### Pagination
All Collections receive their own List View which displays a paginated list of documents that can be sorted and filtered. The pagination behavior of the List View can be customized on a per-Collection basis. All Collections receive their own List View which displays a paginated list of documents that can be sorted and filtered. The pagination behavior of the List View can be customized on a per-Collection basis.
@@ -173,17 +189,7 @@ The following options are available:
| `defaultLimit` | Integer that specifies the default per-page limit that should be used. Defaults to 10. | | `defaultLimit` | Integer that specifies the default per-page limit that should be used. Defaults to 10. |
| `limits` | Provide an array of integers to use as per-page options for admins to choose from in the List View. | | `limits` | Provide an array of integers to use as per-page options for admins to choose from in the List View. |
### Access Control #### List Searchable Fields
You can specify extremely granular access control (what users can do with documents in a Collection) on a Collection by
Collection basis. To learn more, go to the [Access Control](../access-control/overview) docs.
### Hooks
Hooks are a powerful way to extend Collection functionality and execute your own logic, and can be defined on a
Collection by Collection basis. To learn more, go to the [Hooks](../hooks/overview) documentation.
### List Searchable Fields
In the List View, there is a "search" box that allows you to quickly find a document through a simple text search. By default, it searches on the ID field. If defined, the `admin.useAsTitle` field is used. Or, you can explicitly define which fields to search based on the needs of your application. In the List View, there is a "search" box that allows you to quickly find a document through a simple text search. By default, it searches on the ID field. If defined, the `admin.useAsTitle` field is used. Or, you can explicitly define which fields to search based on the needs of your application.

View File

@@ -25,7 +25,7 @@ SERVER_URL=localhost:3000
DATABASE_URI=mongodb://localhost:27017/my-database DATABASE_URI=mongodb://localhost:27017/my-database
``` ```
To use Environment Variables in your Payload config, you can access them directly from `process.env`: To use Environment Variables in your Payload Config, you can access them directly from `process.env`:
```ts ```ts
import { buildConfig } from 'payload' import { buildConfig } from 'payload'

View File

@@ -6,7 +6,11 @@ desc: Set up your Global config for your needs by defining fields, adding slugs
keywords: globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
Globals are in many ways similar to [Collections](../configuration/collections), except they correspond to only a single Document. Globals are perfect for things like header nav, site-wide banner alerts, app-wide localized strings, and other "global" data that your site or app might rely on. Globals are in many ways similar to [Collections](../configuration/collections), except they correspond to only a single Document. You can define as many Globals as your application needs. Each Global saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define.
Globals are the primary way to structure singletons in Payload, such as a header navigation, site-wide banner alerts, or app-wide localized strings. Each Global can have its own unique [Access Control](../access-control/overview), [Hooks](../hooks/overview), [Admin Options](#admin-options), and more.
Globals will automatically generate their own [Local API](../local-api/overview). If your application is using the [Admin Panel](../admin/overview), you will also get a fully-featured [REST API](../rest-api/overview) and [GraphQL API](../graphql/overview) without any additional configuration.
To define a Global Config, use the `globals` property in your [Payload Config](./overview): To define a Global Config, use the `globals` property in your [Payload Config](./overview):
@@ -53,7 +57,7 @@ export const Nav: GlobalConfig = {
<Banner type="success"> <Banner type="success">
<strong>Reminder:</strong> <strong>Reminder:</strong>
For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub. For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub, or the [Templates](https://github.com/payloadcms/payload/tree/main/templates) and [Examples](https://github.com/payloadcms/payload/tree/main/examples) directories in the Payload repository.
</Banner> </Banner>
The following options are available: The following options are available:
@@ -68,7 +72,7 @@ The following options are available:
| **`endpoints`** | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints). | | **`endpoints`** | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints). |
| **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [Click here](../fields/overview) for a full list of field types as well as how to configure them. | | **`fields`** \* | Array of field types that will determine the structure and functionality of the data stored within this Global. [Click here](../fields/overview) for a full list of field types as well as how to configure them. |
| **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined. | | **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined. |
| **`hooks`** | Entry points to "tie in" to collection actions at specific points. [More details](../hooks/overview#global-hooks). | | **`hooks`** | Entry point for Hooks. [More details](../hooks/overview#global-hooks). |
| **`label`** | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined. | | **`label`** | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined. |
| **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Global. | | **`slug`** \* | Unique, URL-friendly string that will act as an identifier for this Global. |
| **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. | | **`typescript`** | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined. |
@@ -76,20 +80,23 @@ The following options are available:
_\* An asterisk denotes that a property is required._ _\* An asterisk denotes that a property is required._
### Fields
Fields define the schema of the Global. To learn more, go to the [Fields](../fields/overview) documentation.
### Access Control ### Access Control
As with Collections, you can specify extremely granular access control (what users can do with this Global) on a Global-by-Global basis. However, Globals only have `update` and `read` access control due to their nature of only having one document. To learn more, go to the [Access Control](../access-control/overview) docs. Access Control determines what a user can and cannot do with a Document. To learn more, go to the [Access Control](../access-control/overview) docs.
### Hooks ### Hooks
Globals also fully support a smaller subset of Hooks. To learn more, go to the [Hooks](../hooks/overview) documentation. Hooks allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the [Hooks](../hooks/overview) documentation.
### Admin Options ### Admin Options
You can customize the way that the [Admin Panel](../admin/overview) behaves on a Global-by-Global basis. You can customize the way that the [Admin Panel](../admin/overview) behaves on a Global-by-Global basis.
To configure Collection Admin Options, use the `admin` property in your Global Config: To configure Admin Options for Globals, use the `admin` property in your Global Config:
```ts ```ts
import { GlobalConfig } from 'payload' import { GlobalConfig } from 'payload'

View File

@@ -135,7 +135,7 @@ export const Articles: CollectionConfig = {
Payload's backend sets the language on incoming requests before they are handled. This allows backend validation to return error messages in the user's own language or system generated emails to be sent using the correct translation. You can make HTTP requests with the `accept-language` header and Payload will use that language. Payload's backend sets the language on incoming requests before they are handled. This allows backend validation to return error messages in the user's own language or system generated emails to be sent using the correct translation. You can make HTTP requests with the `accept-language` header and Payload will use that language.
Anywhere in your Payload app that you have access to the `req` object, you can access payload's extensive internationalization features assigned to `req.i18n`. To access text translations you can use `req.t('namespace:key')`. Anywhere in your Payload app that you have access to the `req` object, you can access Payload's extensive internationalization features assigned to `req.i18n`. To access text translations you can use `req.t('namespace:key')`.
## TypeScript ## TypeScript
@@ -169,7 +169,7 @@ export const MyComponent: React.FC = () => {
``` ```
Additionally, payload exposes the `t` function in various places, for example in labels. Here is how you would type those: Additionally, Payload exposes the `t` function in various places, for example in labels. Here is how you would type those:
```ts ```ts
import type { import type {

View File

@@ -2,19 +2,19 @@
title: Localization title: Localization
label: Localization label: Localization
order: 50 order: 50
desc: Add and maintain as many locales as you need by adding Localization to your Payload config, set options for default locale, fallbacks, fields and more. desc: Add and maintain as many locales as you need by adding Localization to your Payload Config, set options for default locale, fallbacks, fields and more.
keywords: localization, internationalization, i18n, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: localization, internationalization, i18n, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
Payload features deep field-based localization support. Maintaining as many locales as you need is easy. All Payload features deep field-based localization support. Maintaining as many locales as you need is easy. All
localization support is opt-in by default. To do so, follow the two steps below. localization support is opt-in by default. To do so, follow the two steps below.
## Enabling in the Payload config ## Enabling in the Payload Config
Add the `localization` property to your Payload config to enable localization project-wide. You'll need to provide a Add the `localization` property to your Payload Config to enable localization project-wide. You'll need to provide a
list of all locales that you'd like to support as well as set a few other options. list of all locales that you'd like to support as well as set a few other options.
**Example Payload config set up for localization:** **Example Payload Config set up for localization:**
```ts ```ts
import { buildConfig } from 'payload' import { buildConfig } from 'payload'
@@ -31,7 +31,7 @@ export default buildConfig({
}) })
``` ```
**Example Payload config set up for localization with full locales objects:** **Example Payload Config set up for localization with full locales objects:**
```ts ```ts
import { buildConfig } from 'payload' import { buildConfig } from 'payload'
@@ -60,7 +60,7 @@ export default buildConfig({
}) })
``` ```
**Example Payload config set up for localization with full locales objects ( **Example Payload Config set up for localization with full locales objects (
including [internationalization](/docs/configuration/i18n) support):** including [internationalization](/docs/configuration/i18n) support):**
```ts ```ts
@@ -127,7 +127,7 @@ fall back to the fallback locale value. If this property is not enabled, the val
## Field by field localization ## Field by field localization
Payload localization works on a **field** level—not a document level. In addition to configuring the base Payload config Payload localization works on a **field** level—not a document level. In addition to configuring the base Payload Config
to support localization, you need to specify each field that you would like to localize. to support localization, you need to specify each field that you would like to localize.
**Here is an example of how to enable localization for a field:** **Here is an example of how to enable localization for a field:**
@@ -182,7 +182,7 @@ Specify your desired locale by providing the `locale` query parameter directly i
**`?fallback-locale=`** **`?fallback-locale=`**
Specify fallback locale to be used by providing the `fallback-locale` query parameter. This can be provided as either a Specify fallback locale to be used by providing the `fallback-locale` query parameter. This can be provided as either a
valid locale as provided to your base Payload config, or `'null'`, `'false'`, or `'none'` to disable falling back. valid locale as provided to your base Payload Config, or `'null'`, `'false'`, or `'none'` to disable falling back.
**Example:** **Example:**

View File

@@ -59,7 +59,7 @@ export default buildConfig({
<Banner type="success"> <Banner type="success">
<strong>Reminder:</strong> <strong>Reminder:</strong>
For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub. For a more complex example, see the [Public Demo](https://github.com/payloadcms/public-demo) source code on GitHub, or the [Templates](https://github.com/payloadcms/payload/tree/main/templates) and [Examples](https://github.com/payloadcms/payload/tree/main/examples) directories in the Payload repository.
</Banner> </Banner>
The following options are available: The following options are available:

View File

@@ -34,7 +34,7 @@ that will be called if for some reason the migration fails to complete successfu
all changes that you attempt to make within the migration, and the `down` should ideally revert any changes you make. all changes that you attempt to make within the migration, and the `down` should ideally revert any changes you make.
For an added level of safety, migrations should leverage Payload [transactions](/docs/database/transactions). Migration For an added level of safety, migrations should leverage Payload [transactions](/docs/database/transactions). Migration
functions should make use of the `req` by adding it to the arguments of your payload local API calls such functions should make use of the `req` by adding it to the arguments of your Payload Local API calls such
as `payload.create` and database adapter methods like `payload.db.create`. as `payload.create` and database adapter methods like `payload.db.create`.
Here is an example migration file: Here is an example migration file:
@@ -139,7 +139,7 @@ In this case, you can create a migration by running `pnpm payload migrate:create
#### Postgres #### Postgres
In relational databases like Postgres, migrations are a bit more important, because each time you add a new field or a new collection, you'll need to update the shape of your database to match your Payload config (otherwise you'll see errors upon trying to read / write your data). In relational databases like Postgres, migrations are a bit more important, because each time you add a new field or a new collection, you'll need to update the shape of your database to match your Payload Config (otherwise you'll see errors upon trying to read / write your data).
That means that Postgres users of Payload should become familiar with the entire migration workflow from top to bottom. That means that Postgres users of Payload should become familiar with the entire migration workflow from top to bottom.
@@ -167,14 +167,14 @@ But importantly, you do not need to run migrations against your development data
**2 - create a migration** **2 - create a migration**
Once you're done with working in your Payload config, you can create a migration. It's best practice to try and complete a specific task or fully build out a feature before you create a migration. Once you're done with working in your Payload Config, you can create a migration. It's best practice to try and complete a specific task or fully build out a feature before you create a migration.
But once you're ready, you can run `pnpm payload migrate:create`, which will perform the following steps for you: But once you're ready, you can run `pnpm payload migrate:create`, which will perform the following steps for you:
- We will look for any existing migrations, and automatically generate SQL changes necessary to convert your schema from its prior state to the new state of your Payload config - We will look for any existing migrations, and automatically generate SQL changes necessary to convert your schema from its prior state to the new state of your Payload Config
- We will then create a new migration file in your `/migrations` folder that contains all the SQL necessary to be run - We will then create a new migration file in your `/migrations` folder that contains all the SQL necessary to be run
We won't immediately run this migration for you, however. We won't immediately run this migration for you, however.
<Banner type="success"> <Banner type="success">
Tip: migrations created by Payload are relatively programmatic in nature, so there should not be any surprises, but before you check in the created migration it's a good idea to always double-check the contents of the migration files. Tip: migrations created by Payload are relatively programmatic in nature, so there should not be any surprises, but before you check in the created migration it's a good idea to always double-check the contents of the migration files.
@@ -210,4 +210,4 @@ In the example above, we've specified a `ci` script which we can use as our "bui
This will require that your build pipeline can connect to your database, and it will simply run the `payload migrate` command prior to starting the build process. By calling `payload migrate`, Payload will automatically execute any migrations in your `/migrations` folder that have not yet been executed against your production database, in the order that they were created. This will require that your build pipeline can connect to your database, and it will simply run the `payload migrate` command prior to starting the build process. By calling `payload migrate`, Payload will automatically execute any migrations in your `/migrations` folder that have not yet been executed against your production database, in the order that they were created.
If it fails, the deployment will be rejected. But now, with your build script set up to run your migrations, you will be all set! Next time you deploy, your CI will execute the required migrations for you, and your database will be caught up with the shape that your Payload config requires. If it fails, the deployment will be rejected. But now, with your build script set up to run your migrations, you will be all set! Next time you deploy, your CI will execute the required migrations for you, and your database will be caught up with the shape that your Payload Config requires.

View File

@@ -9,7 +9,7 @@ keywords: MongoDB, documentation, typescript, Content Management System, cms, he
To use Payload with MongoDB, install the package `@payloadcms/db-mongodb`. It will come with everything you need to To use Payload with MongoDB, install the package `@payloadcms/db-mongodb`. It will come with everything you need to
store your Payload data in MongoDB. store your Payload data in MongoDB.
Then from there, pass it to your Payload config as follows: Then from there, pass it to your Payload Config as follows:
```ts ```ts
import { mongooseAdapter } from '@payloadcms/db-mongodb' import { mongooseAdapter } from '@payloadcms/db-mongodb'

View File

@@ -6,20 +6,23 @@ keywords: database, mongodb, postgres, documentation, Content Management System,
desc: With Payload, you bring your own database and own your data. You have full control. desc: With Payload, you bring your own database and own your data. You have full control.
--- ---
Payload interacts with your database via the database adapter that you choose. Right now, Payload officially supports two database adapters: Payload interacts with your database via the Database Adapter that you choose. Currently, Payload officially supports the following Database Adapters:
1. [MongoDB](/docs/database/mongodb) w/ [Mongoose](https://mongoosejs.com/) - [MongoDB](/docs/database/mongodb) with [Mongoose](https://mongoosejs.com/)
1. [Postgres](/docs/database/postgres) w/ [Drizzle](https://drizzle.team/) - [Postgres](/docs/database/postgres) with [Drizzle](https://drizzle.team/)
We will be adding support for SQLite and MySQL in the near future using Drizzle ORM.
To use a specific database adapter, you need to install it and configure it according to its own specifications. Visit the documentation for your applicable database adapter to learn more. To use a specific database adapter, you need to install it and configure it according to its own specifications. Visit the documentation for your applicable database adapter to learn more.
## Selecting a database <Banner type="success">
<strong>Note:</strong>
In the future, we will be adding support for SQLite and MySQL using Drizzle.
</Banner>
## Selecting a Database
There are several factors to consider when choosing which database technology and hosting option is right for your project and workload. Payload can theoretically support any database, but it's up to you to decide which database to use. There are several factors to consider when choosing which database technology and hosting option is right for your project and workload. Payload can theoretically support any database, but it's up to you to decide which database to use.
### When to use MongoDB ### Non-Relational Databases
If your project has a lot of dynamic fields, and you are comfortable with allowing Payload to enforce data integrity across your documents, MongoDB is a great choice. With it, your Payload documents are stored as _one_ document in your database—no matter if you have localization enabled, how many block or array fields you have, etc. This means that the shape of your data in your database will very closely reflect your field schema, and there is minimal complexity involved in storing or retrieving your data. If your project has a lot of dynamic fields, and you are comfortable with allowing Payload to enforce data integrity across your documents, MongoDB is a great choice. With it, your Payload documents are stored as _one_ document in your database—no matter if you have localization enabled, how many block or array fields you have, etc. This means that the shape of your data in your database will very closely reflect your field schema, and there is minimal complexity involved in storing or retrieving your data.
@@ -27,32 +30,30 @@ You should prefer MongoDB if:
- You prefer simplicity within your database - You prefer simplicity within your database
- You don't want to deal with keeping production / staging databases in sync via [DDL changes](https://en.wikipedia.org/wiki/Data_definition_language) - You don't want to deal with keeping production / staging databases in sync via [DDL changes](https://en.wikipedia.org/wiki/Data_definition_language)
- Most (or everything) in your project is localized - Most (or everything) in your project is [Localized](../configuration/localization)
- You leverage a lot of array fields, block fields, or `hasMany` select fields and similar - You leverage a lot of [Arrays](../fields/array), [Blocks](../fields/blocks), or `hasMany` [Select](../fields/select) fields
### When to use a relational DB ### Relational Databases
Many projects might call for more rigid database architecture where the shape of your data is strongly enforced at the database level. For example, if you know the shape of your data and it's relatively "flat", and you don't anticipate it to change often, your workload might suit relational databases like Postgres very well. Many projects might call for more rigid database architecture where the shape of your data is strongly enforced at the database level. For example, if you know the shape of your data and it's relatively "flat", and you don't anticipate it to change often, your workload might suit relational databases like Postgres very well.
You should prefer a relational DB like Postgres if: You should prefer a relational DB like Postgres if:
- You are comfortable with migration workflows - You are comfortable with [Migrations](./migrations)
- You require enforced data consistency at the database level - You require enforced data consistency at the database level
- You have a lot of relationships between collections and require relationships to be enforced - You have a lot of relationships between collections and require relationships to be enforced
### Differences in Payload features ### Payload Differences
It's important to note that almost everything Payload does is available in all of our officially supported database adapters, including localization, arrays, blocks, etc. It's important to note that nearly every Payload feature is available in all of our officially supported Database Adapters, including [Localization](../configuration/localization), [Arrays](../fields/array), [Blocks](../fields/blocks), etc.
The only thing that is not supported in Postgres yet is the [Point field](/docs/fields/point), but that should be added soon. The only thing that is not supported in Postgres yet is the [Point Field](/docs/fields/point), but that should be added soon.
It's up to you to choose which database you would like to use. It's up to you to choose which database you would like to use based on the requirements of your project. Payload has no opinion on which database you should ultimately choose.
## Configuration ## Configuration
To configure the database for your Payload application, an adapter can be assigned to `config.db`. This property is required within your Payload config. To add a Database Adapter, use the `db` property in your [Payload Config](../configuration/overview):
Here's an example:
```ts ```ts
import { postgresAdapter } from '@payloadcms/db-postgres' import { postgresAdapter } from '@payloadcms/db-postgres'
@@ -64,10 +65,12 @@ export default buildConfig({
], ],
// Here is where you pass your database adapter // Here is where you pass your database adapter
// and the adapter will require options specific to itself // and the adapter will require options specific to itself
// highlight-start
db: postgresAdapter({ db: postgresAdapter({
pool: { pool: {
connectionString: process.env.DATABASE_URI, connectionString: process.env.DATABASE_URI,
}, },
}), }),
// highlight-end
}) })
``` ```

View File

@@ -10,7 +10,7 @@ To use Payload with Postgres, install the package `@payloadcms/db-postgres`. It
It automatically manages changes to your database for you in development mode, and exposes a full suite of migration controls for you to leverage in order to keep other database environments in sync with your schema. DDL transformations are automatically generated. It automatically manages changes to your database for you in development mode, and exposes a full suite of migration controls for you to leverage in order to keep other database environments in sync with your schema. DDL transformations are automatically generated.
To configure Payload to use Postgres, pass the `postgresAdapter` to your Payload config as follows: To configure Payload to use Postgres, pass the `postgresAdapter` to your Payload Config as follows:
```ts ```ts
import { postgresAdapter } from '@payloadcms/db-postgres' import { postgresAdapter } from '@payloadcms/db-postgres'
@@ -68,11 +68,11 @@ In addition to exposing Drizzle directly, all of the tables, Drizzle relations,
Drizzle exposes two ways to work locally in development mode. Drizzle exposes two ways to work locally in development mode.
The first is [`db push`](https://orm.drizzle.team/kit-docs/overview#prototyping-with-db-push), which automatically pushes changes you make to your Payload config (and therefore, Drizzle schema) to your database so you don't have to manually migrate every time you change your Payload config. This only works in development mode, and should not be mixed with manually running [`migrate`](/docs/database/migrations) commands. The first is [`db push`](https://orm.drizzle.team/kit-docs/overview#prototyping-with-db-push), which automatically pushes changes you make to your Payload Config (and therefore, Drizzle schema) to your database so you don't have to manually migrate every time you change your Payload Config. This only works in development mode, and should not be mixed with manually running [`migrate`](/docs/database/migrations) commands.
You will be warned if any changes that you make will entail data loss while in development mode. Push is enabled by default, but you can opt out if you'd like. You will be warned if any changes that you make will entail data loss while in development mode. Push is enabled by default, but you can opt out if you'd like.
Alternatively, you can disable `push` and rely solely on migrations to keep your local database in sync with your Payload config. Alternatively, you can disable `push` and rely solely on migrations to keep your local database in sync with your Payload Config.
## Migration workflows ## Migration workflows

View File

@@ -10,7 +10,7 @@ keywords: email, overview, config, configuration, documentation, Content Managem
Payload has a few email adapters that can be imported to enable email functionality. The [@payloadcms/email-nodemailer](https://www.npmjs.com/package/@payloadcms/email-nodemailer) package will be the package most will want to install. This package provides an easy way to use [Nodemailer](https://nodemailer.com) for email and won't get in your way for those already familiar. Payload has a few email adapters that can be imported to enable email functionality. The [@payloadcms/email-nodemailer](https://www.npmjs.com/package/@payloadcms/email-nodemailer) package will be the package most will want to install. This package provides an easy way to use [Nodemailer](https://nodemailer.com) for email and won't get in your way for those already familiar.
The email adapter should be passed into the `email` property of the Payload config. This will allow Payload to send emails for things like password resets, new user verification, and any other email sending needs you may have. The email adapter should be passed into the `email` property of the Payload Config. This will allow Payload to send emails for things like password resets, new user verification, and any other email sending needs you may have.
## Configuration ## Configuration
@@ -150,7 +150,7 @@ export default buildConfig({
## Sending Mail ## Sending Mail
With a working transport you can call it anywhere you have access to payload by calling `payload.sendEmail(message)`. The `message` will contain the `to`, `subject` and `html` or `text` for the email being sent. Other options are also available and can be seen in the sendEmail args. Support for these will depend on the adapter being used. With a working transport you can call it anywhere you have access to Payload by calling `payload.sendEmail(message)`. The `message` will contain the `to`, `subject` and `html` or `text` for the email being sent. Other options are also available and can be seen in the sendEmail args. Support for these will depend on the adapter being used.
```ts ```ts
// Example of sending an email // Example of sending an email

View File

@@ -14,7 +14,7 @@ keywords: array, fields, config, configuration, documentation, Content Managemen
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/array.png" srcLight="https://payloadcms.com/images/docs/fields/array.png"
srcDark="https://payloadcms.com/images/docs/fields/array-dark.png" srcDark="https://payloadcms.com/images/docs/fields/array-dark.png"
alt="Array field with two Rows in Payload admin panel" alt="Array field with two Rows in Payload Admin Panel"
caption="Admin Panel screenshot of an Array field with two Rows" caption="Admin Panel screenshot of an Array field with two Rows"
/> />

View File

@@ -11,7 +11,7 @@ keywords: checkbox, fields, config, configuration, documentation, Content Manage
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/checkbox.png" srcLight="https://payloadcms.com/images/docs/fields/checkbox.png"
srcDark="https://payloadcms.com/images/docs/fields/checkbox-dark.png" srcDark="https://payloadcms.com/images/docs/fields/checkbox-dark.png"
alt="Checkbox field with text field in Payload admin panel" alt="Checkbox field with text field in Payload Admin Panel"
caption="Admin Panel screenshot of Checkbox field with Text field below" caption="Admin Panel screenshot of Checkbox field with Text field below"
/> />

View File

@@ -15,7 +15,7 @@ keywords: code, fields, config, configuration, documentation, Content Management
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/code.png" srcLight="https://payloadcms.com/images/docs/fields/code.png"
srcDark="https://payloadcms.com/images/docs/fields/code-dark.png" srcDark="https://payloadcms.com/images/docs/fields/code-dark.png"
alt="Shows a Code field in the Payload admin panel" alt="Shows a Code field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Code field" caption="Admin Panel screenshot of a Code field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: row, fields, config, configuration, documentation, Content Management
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/collapsible.png" srcLight="https://payloadcms.com/images/docs/fields/collapsible.png"
srcDark="https://payloadcms.com/images/docs/fields/collapsible-dark.png" srcDark="https://payloadcms.com/images/docs/fields/collapsible-dark.png"
alt="Shows a Collapsible field in the Payload admin panel" alt="Shows a Collapsible field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Collapsible field" caption="Admin Panel screenshot of a Collapsible field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: date, fields, config, configuration, documentation, Content Management
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/date.png" srcLight="https://payloadcms.com/images/docs/fields/date.png"
srcDark="https://payloadcms.com/images/docs/fields/date-dark.png" srcDark="https://payloadcms.com/images/docs/fields/date-dark.png"
alt="Shows a Date field in the Payload admin panel" alt="Shows a Date field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Date field" caption="Admin Panel screenshot of a Date field"
/> />
@@ -43,7 +43,7 @@ _\* An asterisk denotes that a property is required._
## Admin Config ## Admin Config
In addition to the default [field admin config](/docs/fields/overview#admin-config), you can customize the following fields that will adjust how the component displays in the admin panel via the `date` property. In addition to the default [field admin config](/docs/fields/overview#admin-config), you can customize the following fields that will adjust how the component displays in the Admin Panel via the `date` property.
| Property | Description | | Property | Description |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |

View File

@@ -11,7 +11,7 @@ keywords: email, fields, config, configuration, documentation, Content Managemen
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/email.png" srcLight="https://payloadcms.com/images/docs/fields/email.png"
srcDark="https://payloadcms.com/images/docs/fields/email-dark.png" srcDark="https://payloadcms.com/images/docs/fields/email-dark.png"
alt="Shows an Email field in the Payload admin panel" alt="Shows an Email field in the Payload Admin Panel"
caption="Admin Panel screenshot of an Email field" caption="Admin Panel screenshot of an Email field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: group, fields, config, configuration, documentation, Content Managemen
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/group.png" srcLight="https://payloadcms.com/images/docs/fields/group.png"
srcDark="https://payloadcms.com/images/docs/fields/group-dark.png" srcDark="https://payloadcms.com/images/docs/fields/group-dark.png"
alt="Shows a Group field in the Payload admin panel" alt="Shows a Group field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Group field" caption="Admin Panel screenshot of a Group field"
/> />
@@ -45,7 +45,7 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
**`hideGutter`** **`hideGutter`**
Set this property to `true` to hide this field's gutter within the admin panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter. Set this property to `true` to hide this field's gutter within the Admin Panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter.
## Example ## Example

View File

@@ -15,7 +15,7 @@ keywords: json, jsonSchema, schema, validation, fields, config, configuration, d
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/json.png" srcLight="https://payloadcms.com/images/docs/fields/json.png"
srcDark="https://payloadcms.com/images/docs/fields/json-dark.png" srcDark="https://payloadcms.com/images/docs/fields/json-dark.png"
alt="Shows a JSON field in the Payload admin panel" alt="Shows a JSON field in the Payload Admin Panel"
caption="Admin Panel screenshot of a JSON field" caption="Admin Panel screenshot of a JSON field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: number, fields, config, configuration, documentation, Content Manageme
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/number.png" srcLight="https://payloadcms.com/images/docs/fields/number.png"
srcDark="https://payloadcms.com/images/docs/fields/number-dark.png" srcDark="https://payloadcms.com/images/docs/fields/number-dark.png"
alt="Shows a Number field in the Payload admin panel" alt="Shows a Number field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Number field" caption="Admin Panel screenshot of a Number field"
/> />

View File

@@ -6,7 +6,7 @@ desc: Fields are the building blocks of Payload, find out how to add or remove a
keywords: overview, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: overview, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
Fields are the building blocks of Payload. Both [Collections](../configuration/collections) and [Globals](../configuration/globals) use fields to define the shape of the data that will be stored in the [Database](../database/overview), as well as automatically generate the corresponding UI within the [Admin Panel](../admin/overview). Fields are the building blocks of Payload. They are to define the schema of [Collection](../configuration/collections) and [Global](../configuration/globals) Documents that will be stored in the [Database](../database/overview), as well as automatically generate the corresponding UI within the [Admin Panel](../admin/overview).
There are many [Field Types](#field-types) to choose from, ranging anywhere from simple text strings to nested arrays and blocks. Most fields save data to the database, while others are strictly presentational. Fields can have [Custom Validations](#validations), [Conditional Logic](../admin/fields#conditional-logic), [Access Control](#field-level-access-control), [Hooks](#field-level-hooks), and so much more. There are many [Field Types](#field-types) to choose from, ranging anywhere from simple text strings to nested arrays and blocks. Most fields save data to the database, while others are strictly presentational. Fields can have [Custom Validations](#validations), [Conditional Logic](../admin/fields#conditional-logic), [Access Control](#field-level-access-control), [Hooks](#field-level-hooks), and so much more.

View File

@@ -19,7 +19,7 @@ keywords: point, geolocation, geospatial, geojson, 2dsphere, config, configurati
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/point.png" srcLight="https://payloadcms.com/images/docs/fields/point.png"
srcDark="https://payloadcms.com/images/docs/fields/point-dark.png" srcDark="https://payloadcms.com/images/docs/fields/point-dark.png"
alt="Shows a Point field in the Payload admin panel" alt="Shows a Point field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Point field" caption="Admin Panel screenshot of a Point field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: radio, fields, config, configuration, documentation, Content Managemen
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/radio.png" srcLight="https://payloadcms.com/images/docs/fields/radio.png"
srcDark="https://payloadcms.com/images/docs/fields/radio-dark.png" srcDark="https://payloadcms.com/images/docs/fields/radio-dark.png"
alt="Shows a Radio field in the Payload admin panel" alt="Shows a Radio field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Radio field" caption="Admin Panel screenshot of a Radio field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: relationship, fields, config, configuration, documentation, Content Ma
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/relationship.png" srcLight="https://payloadcms.com/images/docs/fields/relationship.png"
srcDark="https://payloadcms.com/images/docs/fields/relationship-dark.png" srcDark="https://payloadcms.com/images/docs/fields/relationship-dark.png"
alt="Shows a relationship field in the Payload admin panel" alt="Shows a relationship field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Relationship field" caption="Admin Panel screenshot of a Relationship field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: rich text, fields, config, configuration, documentation, Content Manag
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/richtext.png" srcLight="https://payloadcms.com/images/docs/fields/richtext.png"
srcDark="https://payloadcms.com/images/docs/fields/richtext-dark.png" srcDark="https://payloadcms.com/images/docs/fields/richtext-dark.png"
alt="Shows a Rich Text field in the Payload admin panel" alt="Shows a Rich Text field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Rich Text field" caption="Admin Panel screenshot of a Rich Text field"
/> />
@@ -70,7 +70,7 @@ Set this property to define a placeholder string in the text input.
**`hideGutter`** **`hideGutter`**
Set this property to `true` to hide this field's gutter within the admin panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter. Set this property to `true` to hide this field's gutter within the Admin Panel. The field gutter is rendered as a vertical line and padding, but often if this field is nested within a Group, Block, or Array, you may want to hide the gutter.
**`rtl`** **`rtl`**

View File

@@ -14,7 +14,7 @@ keywords: row, fields, config, configuration, documentation, Content Management
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/row.png" srcLight="https://payloadcms.com/images/docs/fields/row.png"
srcDark="https://payloadcms.com/images/docs/fields/row-dark.png" srcDark="https://payloadcms.com/images/docs/fields/row-dark.png"
alt="Shows a row field in the Payload admin panel" alt="Shows a row field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Row field" caption="Admin Panel screenshot of a Row field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: select, multi-select, fields, config, configuration, documentation, Co
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/select.png" srcLight="https://payloadcms.com/images/docs/fields/select.png"
srcDark="https://payloadcms.com/images/docs/fields/select-dark.png" srcDark="https://payloadcms.com/images/docs/fields/select-dark.png"
alt="Shows a Select field in the Payload admin panel" alt="Shows a Select field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Select field" caption="Admin Panel screenshot of a Select field"
/> />

View File

@@ -15,7 +15,7 @@ keywords: tabs, fields, config, configuration, documentation, Content Management
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/tabs.png" srcLight="https://payloadcms.com/images/docs/fields/tabs.png"
srcDark="https://payloadcms.com/images/docs/fields/tabs-dark.png" srcDark="https://payloadcms.com/images/docs/fields/tabs-dark.png"
alt="Shows a tabs field used to separate Hero and Page layout in the Payload admin panel" alt="Shows a tabs field used to separate Hero and Page layout in the Payload Admin Panel"
caption="Tabs field type used to separate Hero fields from Page Layout" caption="Tabs field type used to separate Hero fields from Page Layout"
/> />

View File

@@ -14,7 +14,7 @@ keywords: text, fields, config, configuration, documentation, Content Management
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/text.png" srcLight="https://payloadcms.com/images/docs/fields/text.png"
srcDark="https://payloadcms.com/images/docs/fields/text-dark.png" srcDark="https://payloadcms.com/images/docs/fields/text-dark.png"
alt="Shows a text field and read-only text field in the Payload admin panel" alt="Shows a text field and read-only text field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Text field and read-only Text field" caption="Admin Panel screenshot of a Text field and read-only Text field"
/> />

View File

@@ -14,7 +14,7 @@ keywords: textarea, fields, config, configuration, documentation, Content Manage
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/textarea.png" srcLight="https://payloadcms.com/images/docs/fields/textarea.png"
srcDark="https://payloadcms.com/images/docs/fields/textarea-dark.png" srcDark="https://payloadcms.com/images/docs/fields/textarea-dark.png"
alt="Shows a textarea field and read-only textarea field in the Payload admin panel" alt="Shows a textarea field and read-only textarea field in the Payload Admin Panel"
caption="Admin Panel screenshot of a Textarea field and read-only Textarea field" caption="Admin Panel screenshot of a Textarea field and read-only Textarea field"
/> />

View File

@@ -2,7 +2,7 @@
title: UI Field title: UI Field
label: UI label: UI
order: 200 order: 200
desc: UI fields are purely presentational and allow developers to customize the admin panel to a very fine degree, including adding actions and other functions. desc: UI fields are purely presentational and allow developers to customize the Admin Panel to a very fine degree, including adding actions and other functions.
keywords: custom field, react component, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: custom field, react component, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---

View File

@@ -22,7 +22,7 @@ keywords: upload, images media, fields, config, configuration, documentation, Co
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/upload.png" srcLight="https://payloadcms.com/images/docs/fields/upload.png"
srcDark="https://payloadcms.com/images/docs/fields/upload-dark.png" srcDark="https://payloadcms.com/images/docs/fields/upload-dark.png"
alt="Shows an upload field in the Payload admin panel" alt="Shows an upload field in the Payload Admin Panel"
caption="Admin Panel screenshot of an Upload field" caption="Admin Panel screenshot of an Upload field"
/> />

View File

@@ -10,9 +10,9 @@ Payload is based around a small and intuitive set of concepts. Before starting t
## Config ## Config
<Banner type="info">The Payload config is where you configure everything that Payload does.</Banner> <Banner type="info">The Payload Config is where you configure everything that Payload does.</Banner>
By default, the Payload config lives in the root folder of your code and is named `payload.config.ts`, but you can customize its name and where you store it. You can write full functions and even full React components right into your config. By default, the Payload Config lives in the root folder of your code and is named `payload.config.ts`, but you can customize its name and where you store it. You can write full functions and even full React components right into your config.
## Collections ## Collections
@@ -138,7 +138,7 @@ You can use any GraphQL client with Payload's GraphQL endpoint. Here are a few p
If you don't use GraphQL, you can delete those files! But if you do, you'll find that GraphQL is a first-class API in Payload. Either way, the overhead of GraphQL is completely constrained to these endpoints, and will not slow down / affect Payload outside of those endpoints themselves. If you don't use GraphQL, you can delete those files! But if you do, you'll find that GraphQL is a first-class API in Payload. Either way, the overhead of GraphQL is completely constrained to these endpoints, and will not slow down / affect Payload outside of those endpoints themselves.
For more docs on GraphQL, [click here](/docs/beta/graphql/overview). For more docs on GraphQL, [click here](/docs/beta/graphql/overview).
## Depth ## Depth
@@ -269,14 +269,14 @@ Payload is abstracted into a set of dedicated packages, and it's a good idea to
<Banner type="success"> <Banner type="success">
<strong>Note:</strong> <strong>Note:</strong>
<br/> <br/>
Version numbers of all official Payload packages are kept in sync - and you should always make sure that you use matching versions for all official Payload packages. Version numbers of all official Payload packages are kept in sync - and you should always make sure that you use matching versions for all official Payload packages.
</Banner> </Banner>
`payload` `payload`
The `payload` package is where core business logic for Payload lives. You can think of Payload as an ORM with superpowers - it contains the logic for all Payload "operations" like `find`, `create`, `update`, and `delete`. It executes access control, hooks, validation, and more. The `payload` package is where core business logic for Payload lives. You can think of Payload as an ORM with superpowers - it contains the logic for all Payload "operations" like `find`, `create`, `update`, and `delete`. It executes access control, hooks, validation, and more.
Payload itself is extremely compact, and can be used in any Node environment. As long as you have `payload` installed and you have access to your Payload config, you can query and mutate your database directly without going through an unnecessary HTTP layer. Payload itself is extremely compact, and can be used in any Node environment. As long as you have `payload` installed and you have access to your Payload Config, you can query and mutate your database directly without going through an unnecessary HTTP layer.
Payload also contains all TypeScript definitions, which can be imported from `payload` directly. Payload also contains all TypeScript definitions, which can be imported from `payload` directly.
@@ -288,7 +288,7 @@ import { CollectionConfig, Field, GlobalConfig, Config } from 'payload'
`@payloadcms/next` `@payloadcms/next`
Whereas Payload itself is responsible for direct database access, and control over Payload business logic, the `@payloadcms/next` package is responsible for the admin panel and the entire HTTP layer (REST, GraphQL) that Payload exposes. Whereas Payload itself is responsible for direct database access, and control over Payload business logic, the `@payloadcms/next` package is responsible for the Admin Panel and the entire HTTP layer (REST, GraphQL) that Payload exposes.
`@payloadcms/graphql` `@payloadcms/graphql`
@@ -296,7 +296,7 @@ All of Payload's GraphQL functionality is abstracted into a separate package. Pa
`@payloadcms/ui` `@payloadcms/ui`
This is the UI library that Payload's admin panel uses. All components are exported from this package and can be re-used as you build extensions to the Payload admin UI, or want to use Payload components in your own React apps. Some exports are server components and some are client components. This is the UI library that Payload's Admin Panel uses. All components are exported from this package and can be re-used as you build extensions to the Payload admin UI, or want to use Payload components in your own React apps. Some exports are server components and some are client components.
`@payloadcms/db-postgres`, `@payloadcms/db-mongodb` `@payloadcms/db-postgres`, `@payloadcms/db-mongodb`

View File

@@ -56,7 +56,7 @@ You can copy the Payload `/app` folder files from the Payload blank template on
https://github.com/payloadcms/payload/tree/beta/templates/blank-3.0/src/app/(payload) https://github.com/payloadcms/payload/tree/beta/templates/blank-3.0/src/app/(payload)
``` ```
Notice how the Payload files are all kept within the `(payload)` [Route Group](https://nextjs.org/docs/app/building-your-application/routing/route-groups)? That's so that the Payload admin UI can have its own separate [Root Layout](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) which will allow it to not interfere whatsoever with an existing Next.js app if you have one. Notice how the Payload files are all kept within the `(payload)` [Route Group](https://nextjs.org/docs/app/building-your-application/routing/route-groups)? That's so that the Payload admin UI can have its own separate [Root Layout](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) which will allow it to not interfere whatsoever with an existing Next.js app if you have one.
<Banner type="warning"> <Banner type="warning">
You may need to copy all of your existing frontend files, including your existing root layout, into its own newly created route group. You may need to copy all of your existing frontend files, including your existing root layout, into its own newly created route group.
@@ -114,11 +114,11 @@ You can do this in one of two ways:
In either case, all `require`s and `export`s in your `next.config` file will need to be converted to `import` / `export` if they are not set up that way already. In either case, all `require`s and `export`s in your `next.config` file will need to be converted to `import` / `export` if they are not set up that way already.
#### 4 - create a Payload config and add it to your TypeScript config #### 4 - create a Payload Config and add it to your TypeScript config
Finally, you need to create a barebones Payload config. Finally, you need to create a barebones Payload Config.
Generally the Payload config is located at the root of your repository, or next to your `/app` folder, and is named `payload.config.ts`. Here's what Payload needs at a bare minimum: Generally the Payload Config is located at the root of your repository, or next to your `/app` folder, and is named `payload.config.ts`. Here's what Payload needs at a bare minimum:
```ts ```ts
import sharp from 'sharp' import sharp from 'sharp'
@@ -133,18 +133,18 @@ export default buildConfig({
// Define and configure your collections in this array // Define and configure your collections in this array
collections: [], collections: [],
// Your Payload secret - should be a complex and secure string, unguessable // Your Payload secret - should be a complex and secure string, unguessable
secret: process.env.PAYLOAD_SECRET || '', secret: process.env.PAYLOAD_SECRET || '',
// Whichever database adapter you're using should go here // Whichever database adapter you're using should go here
// Mongoose is shown as an example, but you can also use Postgres // Mongoose is shown as an example, but you can also use Postgres
db: mongooseAdapter({ db: mongooseAdapter({
url: process.env.DATABASE_URI || '', url: process.env.DATABASE_URI || '',
}), }),
// If you want to resize images, crop, set focal point, etc. // If you want to resize images, crop, set focal point, etc.
// make sure to install it and pass it to the config. // make sure to install it and pass it to the config.
// This is optional - if you don't need to do these things, // This is optional - if you don't need to do these things,
// you don't need it! // you don't need it!
sharp, sharp,
}) })

View File

@@ -11,9 +11,9 @@ keywords: documentation, getting started, guide, Content Management System, cms,
title="Payload Introduction - Closing the Gap Between Headless CMS and Application Frameworks" title="Payload Introduction - Closing the Gap Between Headless CMS and Application Frameworks"
/> />
**Payload is the Next.js fullstack framework.** Write a Payload config and instantly get: **Payload is the Next.js fullstack framework.** Write a Payload Config and instantly get:
- A full admin panel using React server / client components, matching the shape of your data and completely extensible with your own React components - A full Admin Panel using React server / client components, matching the shape of your data and completely extensible with your own React components
- Automatic database schema, including direct DB access and ownership, with migrations, transactions, proper indexing, and more - Automatic database schema, including direct DB access and ownership, with migrations, transactions, proper indexing, and more
- Instant REST, GraphQL, and straight-to-DB Node APIs - Instant REST, GraphQL, and straight-to-DB Node APIs
- Authentication which can be used in your own apps - Authentication which can be used in your own apps
@@ -34,11 +34,11 @@ It's fully open source with an MIT license and you can self-host anywhere that y
Even in spite of how much you get out of the box, you still have full control over every aspect of your app - be it database, admin UI, or anything else. Every part of Payload has been designed to be extensible and customizable with modern TypeScript / React. And you'll fully understand the code that you write. Even in spite of how much you get out of the box, you still have full control over every aspect of your app - be it database, admin UI, or anything else. Every part of Payload has been designed to be extensible and customizable with modern TypeScript / React. And you'll fully understand the code that you write.
In Payload, there are no "click ops" - as in clicking around in an admin panel to define your schema. In Payload, everything is done the right way—code-first and version controlled like a proper backend. But once developers define how Payload should work, non-technical users can independently make use of its admin panel to manage whatever they need to without having to know code whatsoever. In Payload, there are no "click ops" - as in clicking around in an Admin Panel to define your schema. In Payload, everything is done the right way—code-first and version controlled like a proper backend. But once developers define how Payload should work, non-technical users can independently make use of its Admin Panel to manage whatever they need to without having to know code whatsoever.
## Use cases ## Use cases
Payload started as a headless Content Management System (CMS), but since, we've seen our community leverage Payload in ways far outside of simply managing pages and blog posts. It's grown into a full-stack TypeScript app framework. Payload started as a headless Content Management System (CMS), but since, we've seen our community leverage Payload in ways far outside of simply managing pages and blog posts. It's grown into a full-stack TypeScript app framework.
Large enterprises use Payload to power significant internal tools, retailers power their entire storefronts without the need for headless Shopify, and massive amounts of digital assets are stored + managed within Payload. Of course, websites large and small still use Payload for content management as well. Large enterprises use Payload to power significant internal tools, retailers power their entire storefronts without the need for headless Shopify, and massive amounts of digital assets are stored + managed within Payload. Of course, websites large and small still use Payload for content management as well.
@@ -48,7 +48,7 @@ The biggest barrier in large web projects cited by marketers is engineering. On
Payload has restored a little love back into the dev / marketer equation with features like Live Preview, redirects, form builders, visual editing, static A/B testing, and more. But even with all this focus on marketing efficiency, we aren't compromising on the developer experience. That way engineers and marketers alike can be proud of the products they build. Payload has restored a little love back into the dev / marketer equation with features like Live Preview, redirects, form builders, visual editing, static A/B testing, and more. But even with all this focus on marketing efficiency, we aren't compromising on the developer experience. That way engineers and marketers alike can be proud of the products they build.
If you're building a website and your frontend is on Next.js, then Payload is a no-brainer. If you're building a website and your frontend is on Next.js, then Payload is a no-brainer.
<Banner type="success"> <Banner type="success">
Instead of going out and signing up for a SaaS vendor that makes it so you have to manage two completely separate concerns, with little to no native connection back and forth, just install Payload in your existing Next.js repo and instantly get a full CMS. Instead of going out and signing up for a SaaS vendor that makes it so you have to manage two completely separate concerns, with little to no native connection back and forth, just install Payload in your existing Next.js repo and instantly get a full CMS.
@@ -71,7 +71,7 @@ When a large organization starts up a new software initiative, there's a lot of
- Implement a migrations workflow for the database as it changes over time - Implement a migrations workflow for the database as it changes over time
- Integrate with other third party solutions by crafting a system of webhooks or similar - Integrate with other third party solutions by crafting a system of webhooks or similar
And then there's the admin panel. Most enterprise tools require an admin UI, and building one from scratch can be the most time-consuming aspect of any new enterprise tool. There are off-the-shelf packages for app frameworks like Rails, but often the customization is so involved that using Material UI or similar from scratch might be better. And then there's the [Admin Panel](../admin/overview). Most enterprise tools require an admin UI, and building one from scratch can be the most time-consuming aspect of any new enterprise tool. There are off-the-shelf packages for app frameworks like Rails, but often the customization is so involved that using Material UI or similar from scratch might be better.
Then there are no-code admin builders that could be used. However, wiring up access control and the connection to the data layer, with proper version control, makes this a challenging task as well. Then there are no-code admin builders that could be used. However, wiring up access control and the connection to the data layer, with proper version control, makes this a challenging task as well.
@@ -85,7 +85,7 @@ npx create-payload-app@latest -t blank
### Headless commerce ### Headless commerce
Companies who prioritize UX generally run into frontend constraints with traditional commerce vendors. These companies will then opt for frontend frameworks like Next.js which allow them to fine-tune their user experience as much as possible—promoting conversions, personalizing experiences, and optimizing for SEO. Companies who prioritize UX generally run into frontend constraints with traditional commerce vendors. These companies will then opt for frontend frameworks like Next.js which allow them to fine-tune their user experience as much as possible—promoting conversions, personalizing experiences, and optimizing for SEO.
But the challenge with using something like Next.js for headless commerce is that in order for non-technical users to manage the storefront, you instantly need to pair a headless commerce product with a headless CMS. Then, your editors need to bounce back and forth between different admin UIs for different functionality. The code required to seamlessly glue them together on the frontend becomes overly complex. But the challenge with using something like Next.js for headless commerce is that in order for non-technical users to manage the storefront, you instantly need to pair a headless commerce product with a headless CMS. Then, your editors need to bounce back and forth between different admin UIs for different functionality. The code required to seamlessly glue them together on the frontend becomes overly complex.
@@ -121,7 +121,7 @@ Payload flattens CMS and DAM into a single tool that makes no compromises on eit
- If you can manage your project fully with code, and don't need an admin UI - If you can manage your project fully with code, and don't need an admin UI
- If you are building a website that fits within the limits a tool like Webflow or Framer - If you are building a website that fits within the limits a tool like Webflow or Framer
- If you already have a full database and just need to visualize the data somehow - If you already have a full database and just need to visualize the data somehow
- If you are confident that you won't need code / data ownership at any point in the future - If you are confident that you won't need code / data ownership at any point in the future
Ready to get started? First, let's review some high-level concepts that are used in Payload. Ready to get started? First, let's review some high-level concepts that are used in Payload.

View File

@@ -2,13 +2,13 @@
title: Adding your own Queries and Mutations title: Adding your own Queries and Mutations
label: Custom Queries and Mutations label: Custom Queries and Mutations
order: 20 order: 20
desc: Payload allows you to add your own GraphQL queries and mutations, simply set up GraphQL in your main Payload config by following these instructions. desc: Payload allows you to add your own GraphQL queries and mutations, simply set up GraphQL in your main Payload Config by following these instructions.
keywords: graphql, resolvers, mutations, custom, queries, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: graphql, resolvers, mutations, custom, queries, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
You can add your own GraphQL queries and mutations to Payload, making use of all the types that Payload has defined for you. You can add your own GraphQL queries and mutations to Payload, making use of all the types that Payload has defined for you.
To do so, add your queries and mutations to the main Payload config as follows: To do so, add your queries and mutations to the main Payload Config as follows:
| Config Path | Description | | Config Path | Description |
| ------------------- | --------------------------------------------------------------------------- | | ------------------- | --------------------------------------------------------------------------- |

View File

@@ -8,13 +8,13 @@ keywords: graphql, resolvers, mutations, config, configuration, documentation, C
In addition to its REST and Local APIs, Payload ships with a fully featured and extensible GraphQL API. In addition to its REST and Local APIs, Payload ships with a fully featured and extensible GraphQL API.
By default, the GraphQL API is exposed via `/api/graphql`, but you can customize this URL via specifying your `routes` within the main Payload config. By default, the GraphQL API is exposed via `/api/graphql`, but you can customize this URL via specifying your `routes` within the main Payload Config.
The labels you provide for your Collections and Globals are used to name the GraphQL types that are created to correspond to your config. Special characters and spaces are removed. The labels you provide for your Collections and Globals are used to name the GraphQL types that are created to correspond to your config. Special characters and spaces are removed.
## GraphQL Options ## GraphQL Options
At the top of your Payload config you can define all the options to manage GraphQL. At the top of your Payload Config you can define all the options to manage GraphQL.
| Option | Description | | Option | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
@@ -93,7 +93,7 @@ const Header: GlobalConfig = {
## Preferences ## Preferences
User [preferences](/docs/admin/overview#preferences) for the admin panel are also available to GraphQL the same way as other collection schemas are generated. To query preferences you must supply an authorization token in the header and only the preferences of that user will be accessible. User [preferences](/docs/admin/overview#preferences) for the [Admin Panel](../admin/overview) are also available to GraphQL the same way as other collection schemas are generated. To query preferences you must supply an authorization token in the header and only the preferences of that user will be accessible.
**Payload will open the following query:** **Payload will open the following query:**
@@ -110,7 +110,7 @@ User [preferences](/docs/admin/overview#preferences) for the admin panel are als
## GraphQL Playground ## GraphQL Playground
GraphQL Playground is enabled by default for development purposes, but disabled in production. You can enable it in production by passing `graphQL.disablePlaygroundInProduction` a `false` setting in the main Payload config. GraphQL Playground is enabled by default for development purposes, but disabled in production. You can enable it in production by passing `graphQL.disablePlaygroundInProduction` a `false` setting in the main Payload Config.
You can even log in using the `login[collection-singular-label-here]` mutation to use the Playground as an authenticated user. You can even log in using the `login[collection-singular-label-here]` mutation to use the Playground as an authenticated user.

View File

@@ -6,7 +6,7 @@ desc: Payload + Vercel Content Link allows yours editors to navigate directly fr
keywords: vercel, vercel content link, content link, visual editing, content source maps, Content Management System, cms, headless, javascript, node, react, nextjs keywords: vercel, vercel content link, content link, visual editing, content source maps, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
[Vercel Content Link](https://vercel.com/docs/workflow-collaboration/edit-mode#content-link) will allow your editors to navigate directly from the content rendered on your front-end to the fields in Payload that control it. This requires no changes to your front-end code and very few changes to your Payload config. [Vercel Content Link](https://vercel.com/docs/workflow-collaboration/edit-mode#content-link) will allow your editors to navigate directly from the content rendered on your front-end to the fields in Payload that control it. This requires no changes to your front-end code and very few changes to your Payload Config.
![Versions](/images/docs/vercel-visual-editing.jpg) ![Versions](/images/docs/vercel-visual-editing.jpg)
@@ -30,7 +30,7 @@ Setting up Payload with Vercel Content Link is easy. First, install the `@payloa
npm i @payloadcms/plugin-csm npm i @payloadcms/plugin-csm
``` ```
Then in the `plugins` array of your Payload config, call the plugin and enable any collections that require Content Source Maps. Then in the `plugins` array of your Payload Config, call the plugin and enable any collections that require Content Source Maps.
```ts ```ts
import { buildConfig } from "payload/config" import { buildConfig } from "payload/config"

View File

@@ -165,17 +165,17 @@ While nodes in the client feature are added by themselves to the nodes array, no
| Option | Description | | Option | Description |
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **`getSubFields`** | If a node includes sub-fields (e.g. block and link nodes), passing the subFields schema here will make payload automatically populate & run hooks for them. | | **`getSubFields`** | If a node includes sub-fields (e.g. block and link nodes), passing the subFields schema here will make Payload automatically populate & run hooks for them. |
| **`getSubFieldsData`** | If a node includes sub-fields, the sub-fields data needs to be returned here, alongside `getSubFields` which returns their schema. | | **`getSubFieldsData`** | If a node includes sub-fields, the sub-fields data needs to be returned here, alongside `getSubFields` which returns their schema. |
| **`graphQLPopulationPromises`** | Allows you to run population logic when a node's data was requested from GraphQL. While `getSubFields` and `getSubFieldsData` automatically handle populating sub-fields (since they run hooks on them), those are only populated in the Rest API. This is because the Rest API hooks do not have access to the 'depth' property provided by GraphQL. In order for them to be populated correctly in GraphQL, the population logic needs to be provided here. | | **`graphQLPopulationPromises`** | Allows you to run population logic when a node's data was requested from GraphQL. While `getSubFields` and `getSubFieldsData` automatically handle populating sub-fields (since they run hooks on them), those are only populated in the Rest API. This is because the Rest API hooks do not have access to the 'depth' property provided by GraphQL. In order for them to be populated correctly in GraphQL, the population logic needs to be provided here. |
| **`node`** | The actual lexical node needs to be provided here. This also supports [lexical node replacements](https://lexical.dev/docs/concepts/node-replacement). | | **`node`** | The actual lexical node needs to be provided here. This also supports [lexical node replacements](https://lexical.dev/docs/concepts/node-replacement). |
| **`validations`** | This allows you to provide node validations, which are run when your document is being validated, alongside other payload fields. You can use it to throw a validation error for a specific node in case its data is incorrect. | | **`validations`** | This allows you to provide node validations, which are run when your document is being validated, alongside other Payload fields. You can use it to throw a validation error for a specific node in case its data is incorrect. |
| **`converters`** | Allows you to define how a node can be serialized into different formats. Currently, only supports HTML. Markdown converters are defined in `markdownTransformers` and not here. | | **`converters`** | Allows you to define how a node can be serialized into different formats. Currently, only supports HTML. Markdown converters are defined in `markdownTransformers` and not here. |
| **`hooks`** | Just like payload fields, you can provide hooks which are run for this specific node. These are called Node Hooks. | | **`hooks`** | Just like Payload fields, you can provide hooks which are run for this specific node. These are called Node Hooks. |
### Feature load order ### Feature load order
Server features can also accept a function as the `feature` property (useful for sanitizing props, as mentioned below). This function will be called when the feature is loaded during the payload sanitization process: Server features can also accept a function as the `feature` property (useful for sanitizing props, as mentioned below). This function will be called when the feature is loaded during the Payload sanitization process:
```ts ```ts
import { createServerFeature } from '@payloadcms/richtext-lexical'; import { createServerFeature } from '@payloadcms/richtext-lexical';
@@ -836,4 +836,4 @@ The reason the client feature does not have the same props available as the serv
## More information ## More information
Have a look at the [features we've already built](https://github.com/payloadcms/payload/tree/beta/packages/richtext-lexical/src/features) - understanding how they work will help you understand how to create your own. There is no difference between the features included by default and the ones you create yourself - since those features are all isolated from the "core", you have access to the same APIs, whether the feature is part of payload or not! Have a look at the [features we've already built](https://github.com/payloadcms/payload/tree/beta/packages/richtext-lexical/src/features) - understanding how they work will help you understand how to create your own. There is no difference between the features included by default and the ones you create yourself - since those features are all isolated from the "core", you have access to the same APIs, whether the feature is part of Payload or not!

View File

@@ -57,8 +57,8 @@ import { consolidateHTMLConverters, convertLexicalToHTML } from '@payloadcms/ric
await convertLexicalToHTML({ await convertLexicalToHTML({
converters: consolidateHTMLConverters({ editorConfig }), converters: consolidateHTMLConverters({ editorConfig }),
data: editorData, data: editorData,
payload, // if you have payload but no req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes) payload, // if you have Payload but no req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes)
req, // if you have req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes). No need to pass in payload if req is passed in. req, // if you have req available, pass it in here to enable server-only functionality (e.g. proper conversion of upload nodes). No need to pass in Payload if req is passed in.
}) })
``` ```
This method employs `convertLexicalToHTML` from `@payloadcms/richtext-lexical`, which converts the serialized editor state into HTML. This method employs `convertLexicalToHTML` from `@payloadcms/richtext-lexical`, which converts the serialized editor state into HTML.
@@ -204,7 +204,7 @@ import { createHeadlessEditor } from '@lexical/headless' // <= make sure this pa
import { getEnabledNodes, sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical' import { getEnabledNodes, sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
const yourEditorConfig // <= your editor config here const yourEditorConfig // <= your editor config here
const payloadConfig // <= your payload config here const payloadConfig // <= your Payload Config here
const headlessEditor = createHeadlessEditor({ const headlessEditor = createHeadlessEditor({
nodes: getEnabledNodes({ nodes: getEnabledNodes({
@@ -337,7 +337,7 @@ Convert markdown content to the Lexical editor format with the following:
import { $convertFromMarkdownString } from '@lexical/markdown' import { $convertFromMarkdownString } from '@lexical/markdown'
import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical' import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & payload config here const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & Payload Config here
const markdown = `# Hello World` const markdown = `# Hello World`
headlessEditor.update( headlessEditor.update(
@@ -365,7 +365,7 @@ import { $convertToMarkdownString } from '@lexical/markdown'
import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical' import { sanitizeServerEditorConfig } from '@payloadcms/richtext-lexical'
import type { SerializedEditorState } from 'lexical' import type { SerializedEditorState } from 'lexical'
const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & payload config here const yourSanitizedEditorConfig = sanitizeServerEditorConfig(yourEditorConfig, payloadConfig) // <= your editor config & Payload Config here
const yourEditorState: SerializedEditorState // <= your current editor state here const yourEditorState: SerializedEditorState // <= your current editor state here
// Import editor state into your headless editor // Import editor state into your headless editor

View File

@@ -17,7 +17,7 @@ Just import the `migrateSlateToLexical` function we provide, pass it the `payloa
IMPORTANT: This will overwrite all slate data. We recommend doing the following first: IMPORTANT: This will overwrite all slate data. We recommend doing the following first:
1. Take a backup of your entire database. If anything goes wrong and you do not have a backup, you are on your own and will not receive any support. 1. Take a backup of your entire database. If anything goes wrong and you do not have a backup, you are on your own and will not receive any support.
2. Make every richText field a lexical editor. This script will only convert lexical richText fields with old Slate data 2. Make every richText field a lexical editor. This script will only convert lexical richText fields with old Slate data
3. Add the SlateToLexicalFeature (as seen below) first, and test it out by loading up the admin panel, to see if the migrator works as expected. You might have to build some custom converters for some fields first in order to convert custom Slate nodes. The SlateToLexicalFeature is where the converters are stored. Only fields with this feature added will be migrated. 3. Add the SlateToLexicalFeature (as seen below) first, and test it out by loading up the Admin Panel, to see if the migrator works as expected. You might have to build some custom converters for some fields first in order to convert custom Slate nodes. The SlateToLexicalFeature is where the converters are stored. Only fields with this feature added will be migrated.
```ts ```ts
import { migrateSlateToLexical } from '@payloadcms/richtext-lexical' import { migrateSlateToLexical } from '@payloadcms/richtext-lexical'
@@ -55,7 +55,7 @@ and done! Now, everytime this lexical editor is initialized, it converts the sla
This is by far the easiest way to migrate from Slate to Lexical, although it does come with a few caveats: This is by far the easiest way to migrate from Slate to Lexical, although it does come with a few caveats:
- There is a performance hit when initializing the lexical editor - There is a performance hit when initializing the lexical editor
- The editor will still output the Slate data in the output JSON, as the on-the-fly converter only runs for the admin panel - The editor will still output the Slate data in the output JSON, as the on-the-fly converter only runs for the Admin Panel
The easy way to solve this: Edit the richText field and save the document! This overrides the slate data with the lexical data, and the next time the document is loaded, the lexical data will be used. This solves both the performance and the output issue for that specific document. This, however, is a slow and gradual migration process, thus you will have to support both API formats. Especially for a large number of documents, we recommend running the migration script, as explained above. The easy way to solve this: Edit the richText field and save the document! This overrides the slate data with the lexical data, and the next time the document is loaded, the lexical data will be used. This solves both the performance and the output issue for that specific document. This, however, is a slow and gradual migration process, thus you will have to support both API formats. Especially for a large number of documents, we recommend running the migration script, as explained above.
@@ -134,7 +134,7 @@ Each lexical node has a `version` property which is saved in the database. Every
The problem is, this migration only happens when you open the editor, modify the richText field (so that the field's `setValue` function is called) and save the document. Until you do that for all documents, some documents will still have the old data. The problem is, this migration only happens when you open the editor, modify the richText field (so that the field's `setValue` function is called) and save the document. Until you do that for all documents, some documents will still have the old data.
To solve this, we export an `upgradeLexicalData` function which goes through every single document in your payload app and re-saves it, if it has a lexical editor. This way, the data is automatically converted to the new format, and that automatic conversion gets applied to every single document in your app. To solve this, we export an `upgradeLexicalData` function which goes through every single document in your Payload app and re-saves it, if it has a lexical editor. This way, the data is automatically converted to the new format, and that automatic conversion gets applied to every single document in your app.
IMPORTANT: Take a backup of your entire database. If anything goes wrong and you do not have a backup, you are on your own and will not receive any support. IMPORTANT: Take a backup of your entire database. If anything goes wrong and you do not have a backup, you are on your own and will not receive any support.

View File

@@ -29,7 +29,7 @@ To use the Lexical editor, first you need to install it:
npm install @payloadcms/richtext-lexical npm install @payloadcms/richtext-lexical
``` ```
Once you have it installed, you can pass it to your top-level Payload config as follows: Once you have it installed, you can pass it to your top-level Payload Config as follows:
```ts ```ts
import { buildConfig } from 'payload' import { buildConfig } from 'payload'

View File

@@ -2,7 +2,7 @@
title: Using Payload outside Next.js title: Using Payload outside Next.js
label: Outside Next.js label: Outside Next.js
order: 20 order: 20
desc: Payload can be used outside of Next.js within standalone scripts or in other frameworks like Remix, Sveltekit, Nuxt, and similar. desc: Payload can be used outside of Next.js within standalone scripts or in other frameworks like Remix, Sveltekit, Nuxt, and similar.
keywords: local api, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express keywords: local api, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
--- ---
@@ -11,16 +11,16 @@ Payload can be used completely outside of Next.js which is helpful in cases like
<Banner> <Banner>
<strong>Note:</strong> <strong>Note:</strong>
<br/> <br/>
Payload and all of its official packages are fully ESM. If you want to use Payload within your own projects, make sure you are writing your scripts in ESM format or dynamically importing the Payload config. Payload and all of its official packages are fully ESM. If you want to use Payload within your own projects, make sure you are writing your scripts in ESM format or dynamically importing the Payload Config.
</Banner> </Banner>
## Importing the Payload config outside of Next.js ## Importing the Payload Config outside of Next.js
Your Payload config likely has imports which need to be handled properly, such as CSS imports and similar. If you were to try and import your config without any Node support for SCSS / CSS files, you'll see errors that arise accordingly. Your Payload Config likely has imports which need to be handled properly, such as CSS imports and similar. If you were to try and import your config without any Node support for SCSS / CSS files, you'll see errors that arise accordingly.
This is especially relevant if you are importing your Payload config outside of a bundler context, such as in standalone Node scripts. This is especially relevant if you are importing your Payload Config outside of a bundler context, such as in standalone Node scripts.
For these cases, you can use Payload's `importConfig` function to handle importing your config safely. It will handle everything you need to be able to load and use your Payload config, without any client-side files present. For these cases, you can use Payload's `importConfig` function to handle importing your config safely. It will handle everything you need to be able to load and use your Payload Config, without any client-side files present.
Here's an example of a seed script that creates a few documents for local development / testing purposes, using Payload's `importConfig` function to safely import Payload, and the `getPayload` function to retrieve an initialized copy of Payload. Here's an example of a seed script that creates a few documents for local development / testing purposes, using Payload's `importConfig` function to safely import Payload, and the `getPayload` function to retrieve an initialized copy of Payload.
@@ -30,7 +30,7 @@ Here's an example of a seed script that creates a few documents for local develo
// you should always use `import { getPayloadHMR } from '@payloadcms/next/utilities'` instead. // you should always use `import { getPayloadHMR } from '@payloadcms/next/utilities'` instead.
import { getPayload } from 'payload' import { getPayload } from 'payload'
// This is a helper function that will make sure we can safely load the Payload config // This is a helper function that will make sure we can safely load the Payload Config
// and all of its client-side files, such as CSS, SCSS, etc. // and all of its client-side files, such as CSS, SCSS, etc.
import { importConfig } from 'payload/node' import { importConfig } from 'payload/node'
@@ -43,7 +43,7 @@ import dotenv from 'dotenv'
const filename = fileURLToPath(import.meta.url) const filename = fileURLToPath(import.meta.url)
const dirname = path.dirname(filename) const dirname = path.dirname(filename)
// If you don't need to load your .env file, // If you don't need to load your .env file,
// then you can skip this part! // then you can skip this part!
dotenv.config({ dotenv.config({
path: path.resolve(dirname, '../.env'), path: path.resolve(dirname, '../.env'),

View File

@@ -55,9 +55,9 @@ import config from '@payload-config'
const payload = await getPayloadHMR({ config }) const payload = await getPayloadHMR({ config })
``` ```
You should import Payload using the first option (`getPayloadHMR`) if you are using Payload inside of Next.js (like route handlers, server components, and similar.) You should import Payload using the first option (`getPayloadHMR`) if you are using Payload inside of Next.js (like route handlers, server components, and similar.)
This way, in Next.js development mode, Payload will work with Hot Module Replacement (HMR), and as you make changes to your Payload config, your usage of Payload will always be in sync with your changes. In production, `getPayloadHMR` simply disables all HMR functionality so you don't need to write your code any differently. We handle optimization for you in production mode. This way, in Next.js development mode, Payload will work with Hot Module Replacement (HMR), and as you make changes to your Payload Config, your usage of Payload will always be in sync with your changes. In production, `getPayloadHMR` simply disables all HMR functionality so you don't need to write your code any differently. We handle optimization for you in production mode.
If you are accessing Payload via function arguments or `req.payload`, HMR is automatically supported if you are using it within Next.js. If you are accessing Payload via function arguments or `req.payload`, HMR is automatically supported if you are using it within Next.js.
@@ -73,7 +73,7 @@ const config = await importConfig('./payload.config.ts')
const payload = await getPayload({ config }) const payload = await getPayload({ config })
``` ```
Both options function in exactly the same way outside of one having HMR support and the other not. However, when you import your Payload config, you need to make sure that you can import it safely. Both options function in exactly the same way outside of one having HMR support and the other not. However, when you import your Payload Config, you need to make sure that you can import it safely.
For more information about using Payload outside of Next.js, [click here](/docs/beta/local-api/outside-nextjs). For more information about using Payload outside of Next.js, [click here](/docs/beta/local-api/outside-nextjs).

View File

@@ -9,11 +9,11 @@ The core logic and principles of Payload remain the same for 3.0. The brunt of t
## To migrate from Payload 2.0 to 3.0: ## To migrate from Payload 2.0 to 3.0:
1. Delete the `admin.bundler` property from your Payload config: 1. Delete the `admin.bundler` property from your Payload Config:
Payload no longer bundles the admin panel. Instead, we rely directly on Next.js for bundling. This also means that the `@payloadcms/bundler-webpack` and `@payloadcms/bundler-vite` packages have been deprecated. You can completely uninstall those from your project by removing them from your `package.json` file and re-running your package managers installation process, i.e. `pnpm i`. Payload no longer bundles the Admin Panel. Instead, we rely directly on Next.js for bundling. This also means that the `@payloadcms/bundler-webpack` and `@payloadcms/bundler-vite` packages have been deprecated. You can completely uninstall those from your project by removing them from your `package.json` file and re-running your package managers installation process, i.e. `pnpm i`.
2. Add the `secret` property to your Payload config. This used to be set in the `payload.init()` function of your `server.ts` file. Move it to `payload.config.ts` instead: 2. Add the `secret` property to your Payload Config. This used to be set in the `payload.init()` function of your `server.ts` file. Move it to `payload.config.ts` instead:
```tsx ```tsx
// payload.config.ts // payload.config.ts
@@ -24,7 +24,7 @@ buildConfig({
}) })
``` ```
3. The `admin.css` and `admin.scss` properties in the Payload config have been removed: 3. The `admin.css` and `admin.scss` properties in the Payload Config have been removed:
Instead for any global styles you can: Instead for any global styles you can:
@@ -414,7 +414,7 @@ export const MyClientComponent = {
} }
``` ```
8. The `custom` property in the Payload config, i.e. collections, globals, blocks, and fields are now ***server only***. 8. The `custom` property in the Payload Config, i.e. collections, globals, blocks, and fields are now ***server only***.
Use `admin.custom` properties will be available in both server and client bundles. Use `admin.custom` properties will be available in both server and client bundles.
@@ -868,7 +868,7 @@ const { i18n, t } = useTranslation()
return <p>{t('general:cancel')}</p> return <p>{t('general:cancel')}</p>
``` ```
- `react-i18n` was removed, the `Trans` component from react-i18n has been replaced with a payload provided solution. You can instead `import { Translation } from "@payloadcms/ui"` - `react-i18n` was removed, the `Trans` component from react-i18n has been replaced with a Payload provided solution. You can instead `import { Translation } from "@payloadcms/ui"`
```tsx ```tsx
// Translation string example // Translation string example
@@ -1017,7 +1017,7 @@ import { addLocalesToRequest } from '@payloadcms/next/utilities'
## Uploads ## Uploads
- `staticDir` must now be an absolute path. Before it would attempt to use the location of the payload config and merge the relative path set for staticDir. - `staticDir` must now be an absolute path. Before it would attempt to use the location of the Payload Config and merge the relative path set for staticDir.
- `staticURL` has been removed. If you were using this format URLs when using an external provider, you can leverage the `generateFileURL` functions in order to do the same. - `staticURL` has been removed. If you were using this format URLs when using an external provider, you can leverage the `generateFileURL` functions in order to do the same.
## Email Adapters ## Email Adapters

View File

@@ -16,7 +16,7 @@ Building your own [Payload Plugin](./overview) is easy, and if you&apos;re alrea
Our plugin template includes everything you need to build a full life-cycle plugin: Our plugin template includes everything you need to build a full life-cycle plugin:
- Example files and functions for extending the payload config - Example files and functions for extending the Payload Config
- A local dev environment to develop the plugin - A local dev environment to develop the plugin
- Test suite with integrated GitHub workflow - Test suite with integrated GitHub workflow
@@ -28,7 +28,7 @@ Here is a brief recap of how to integrate plugins with Payload, to learn more he
### How to install a plugin ### How to install a plugin
To install any plugin, simply add it to your Payload config in the plugins array. To install any plugin, simply add it to your Payload Config in the plugins array.
``` ```
import samplePlugin from 'sample-plugin'; import samplePlugin from 'sample-plugin';
@@ -183,7 +183,7 @@ export const samplePlugin =
} }
``` ```
1. First, you need to receive the existing Payload config along with any plugin options. 1. First, you need to receive the existing Payload Config along with any plugin options.
2. Then set the variable `config` to be equal to a copy of the existing config. 2. Then set the variable `config` to be equal to a copy of the existing config.
3. From here, you can extend the config however you like! 3. From here, you can extend the config however you like!
4. Finally, return the config and you&apos;re all set. 4. Finally, return the config and you&apos;re all set.
@@ -192,7 +192,7 @@ export const samplePlugin =
[Spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) (or the spread operator) is a feature in JavaScript that uses the dot notation **(...)** to spread elements from arrays, strings, or objects into various contexts. [Spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) (or the spread operator) is a feature in JavaScript that uses the dot notation **(...)** to spread elements from arrays, strings, or objects into various contexts.
We are going to use spread syntax to allow us to add data to existing arrays without losing the existing data. It is crucial to spread the existing data correctly, else this can cause adverse behavior and conflicts with Payload config and other plugins. We are going to use spread syntax to allow us to add data to existing arrays without losing the existing data. It is crucial to spread the existing data correctly, else this can cause adverse behavior and conflicts with Payload Config and other plugins.
Let&apos;s say you want to build a plugin that adds a new collection: Let&apos;s say you want to build a plugin that adds a new collection:
@@ -204,7 +204,7 @@ config.collections = [
] ]
``` ```
First, you need to spread the `config.collections` to ensure that we don&apos;t lose the existing collections. Then you can add any additional collections, just as you would in a regular payload config. First, you need to spread the `config.collections` to ensure that we don&apos;t lose the existing collections. Then you can add any additional collections, just as you would in a regular Payload Config.
This same logic is applied to other properties like admin, globals, hooks: This same logic is applied to other properties like admin, globals, hooks:
@@ -270,7 +270,7 @@ The best way to share and allow others to use your plugin once it is complete is
### Add payload-plugin topic tag ### Add payload-plugin topic tag
Apply the tag **payload-plugin** to your GitHub repository. This will boost the visibility of your plugin and ensure it gets listed with [existing payload plugins](https://github.com/topics/payload-plugin). Apply the tag **payload-plugin** to your GitHub repository. This will boost the visibility of your plugin and ensure it gets listed with [existing Payload plugins](https://github.com/topics/payload-plugin).
### Use Semantic Versioning (SemVer) ### Use Semantic Versioning (SemVer)

View File

@@ -2,15 +2,15 @@
title: Form Builder Plugin title: Form Builder Plugin
label: Form Builder label: Form Builder
order: 20 order: 20
desc: Easily build and manage forms from the admin panel. Send dynamic, personalized emails and even accept and process payments. desc: Easily build and manage forms from the Admin Panel. Send dynamic, personalized emails and even accept and process payments.
keywords: plugins, plugin, form, forms, form builder keywords: plugins, plugin, form, forms, form builder
--- ---
[![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-form-builder)](https://www.npmjs.com/package/@payloadcms/plugin-form-builder) [![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-form-builder)](https://www.npmjs.com/package/@payloadcms/plugin-form-builder)
This plugin allows you to build and manage custom forms directly within the admin panel. Instead of hard-coding a new form into your website or application every time you need one, admins can simply define the schema for each form they need on-the-fly, and your front-end can map over this schema, render its own UI components, and match your brand's design system. This plugin allows you to build and manage custom forms directly within the [Admin Panel](../admin/overview). Instead of hard-coding a new form into your website or application every time you need one, admins can simply define the schema for each form they need on-the-fly, and your front-end can map over this schema, render its own UI components, and match your brand's design system.
All form submissions are stored directly in your database and are managed directly from the admin panel. When forms are submitted, you can display a custom on-screen confirmation message to the user or redirect them to a dedicated confirmation page. You can even send dynamic, personalized emails derived from the form's data. For example, you may want to send a confirmation email to the user who submitted the form, and also send a notification email to your team. All form submissions are stored directly in your database and are managed directly from the Admin Panel. When forms are submitted, you can display a custom on-screen confirmation message to the user or redirect them to a dedicated confirmation page. You can even send dynamic, personalized emails derived from the form's data. For example, you may want to send a confirmation email to the user who submitted the form, and also send a notification email to your team.
Forms can be as simple or complex as you need, from a basic contact form, to a multi-step lead generation engine, or even a donation form that processes payment. You may not need to reach for third-party services like HubSpot or Mailchimp for this, but instead use your own first-party tooling, built directly into your own application. Forms can be as simple or complex as you need, from a basic contact form, to a multi-step lead generation engine, or even a donation form that processes payment. You may not need to reach for third-party services like HubSpot or Mailchimp for this, but instead use your own first-party tooling, built directly into your own application.
@@ -25,7 +25,7 @@ Forms can be as simple or complex as you need, from a basic contact form, to a m
## Core Features ## Core Features
- Build completely dynamic forms directly from the admin panel for a variety of use cases - Build completely dynamic forms directly from the Admin Panel for a variety of use cases
- Render forms on your front-end using your own UI components and match your brand's design system - Render forms on your front-end using your own UI components and match your brand's design system
- Send dynamic, personalized emails upon form submission to multiple recipients, derived from the form's data - Send dynamic, personalized emails upon form submission to multiple recipients, derived from the form's data
- Display a custom confirmation message or automatically redirect upon form submission - Display a custom confirmation message or automatically redirect upon form submission
@@ -41,7 +41,7 @@ pnpm add @payloadcms/plugin-form-builder
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options): In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
```ts ```ts
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'

View File

@@ -53,7 +53,7 @@ or [PNPM](https://pnpm.io):
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin
with [options](#options): with [options](#options):
```ts ```ts
@@ -224,7 +224,7 @@ const examplePageConfig: CollectionConfig = {
## Localization ## Localization
This plugin supports localization by default. If the `localization` property is set in your Payload config, This plugin supports localization by default. If the `localization` property is set in your Payload Config,
the `breadcrumbs` field is automatically localized. For more details on how localization works in Payload, see the `breadcrumbs` field is automatically localized. For more details on how localization works in Payload, see
the [Localization](https://payloadcms.com/docs/localization/overview) docs. the [Localization](https://payloadcms.com/docs/localization/overview) docs.

View File

@@ -23,7 +23,7 @@ Writing plugins is no more complex than writing regular JavaScript. If you know
- Automatically sync data from a specific collection to HubSpot or a similar CRM when data is added or changes - Automatically sync data from a specific collection to HubSpot or a similar CRM when data is added or changes
- Add password-protection functionality to certain documents - Add password-protection functionality to certain documents
- Add a full e-commerce backend to any Payload app - Add a full e-commerce backend to any Payload app
- Add custom reporting views to Payload's admin panel - Add custom reporting views to Payload's Admin Panel
- Encrypt specific collections' data - Encrypt specific collections' data
- Add a full form builder implementation - Add a full form builder implementation
- Integrate all `upload`-enabled collections with a third-party file host like S3 or Cloudinary - Integrate all `upload`-enabled collections with a third-party file host like S3 or Cloudinary

View File

@@ -8,7 +8,7 @@ keywords: plugins, redirects, redirect, plugin, payload, cms, seo, indexing, sea
[![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-redirects)](https://www.npmjs.com/package/@payloadcms/plugin-redirects) [![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-redirects)](https://www.npmjs.com/package/@payloadcms/plugin-redirects)
This plugin allows you to easily manage redirects for your application from within your admin panel. It does so by adding a `redirects` collection to your config that allows you specify a redirect from one URL to another. Your front-end application can use this data to automatically redirect users to the correct page using proper HTTP status codes. This is useful for SEO, indexing, and search engine ranking when re-platforming or when changing your URL structure. This plugin allows you to easily manage redirects for your application from within your [Admin Panel](../admin/overview). It does so by adding a `redirects` collection to your config that allows you specify a redirect from one URL to another. Your front-end application can use this data to automatically redirect users to the correct page using proper HTTP status codes. This is useful for SEO, indexing, and search engine ranking when re-platforming or when changing your URL structure.
For example, if you have a page at `/about` and you want to change it to `/about-us`, you can create a redirect from the old page to the new one, then you can use this data to write HTTP redirects into your front-end application. This will ensure that users are redirected to the correct page without penalty because search engines are notified of the change at the request level. This is a very lightweight plugin that will allow you to integrate managed redirects for any front-end framework. For example, if you have a page at `/about` and you want to change it to `/about-us`, you can create a redirect from the old page to the new one, then you can use this data to write HTTP redirects into your front-end application. This will ensure that users are redirected to the correct page without penalty because search engines are notified of the change at the request level. This is a very lightweight plugin that will allow you to integrate managed redirects for any front-end framework.
@@ -37,7 +37,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options): In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
```ts ```ts
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'

View File

@@ -44,7 +44,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options): In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
```js ```js
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'

View File

@@ -44,7 +44,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin and pass in your Sentry DSN as an option. In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin and pass in your Sentry DSN as an option.
```ts ```ts
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'

View File

@@ -8,9 +8,9 @@ keywords: plugins, seo, meta, search, engine, ranking, google
[![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-seo)](https://www.npmjs.com/package/@payloadcms/plugin-seo) [![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-seo)](https://www.npmjs.com/package/@payloadcms/plugin-seo)
This plugin allows you to easily manage SEO metadata for your application from within your admin panel. When enabled on your collections and globals, it adds a new `meta` field group containing `title`, `description`, and `image` by default. Your front-end application can then use this data to render meta tags however your application requires. For example, you would inject a `title` tag into the `<head>` of your page using `meta.title` as its content. This plugin allows you to easily manage SEO metadata for your application from within your [Admin Panel](../admin/overview). When enabled on your [Collections](../configuration/collections) and [Globals](../configuration/globals), it adds a new `meta` field group containing `title`, `description`, and `image` by default. Your front-end application can then use this data to render meta tags however your application requires. For example, you would inject a `title` tag into the `<head>` of your page using `meta.title` as its content.
As users are editing documents within the admin panel, they have the option to "auto-generate" these fields. When clicked, this plugin will execute your own custom functions that re-generate the title, description, and image. This way you can build your own SEO writing assistance directly into your application. For example, you could append your site name onto the page title, or use the document's excerpt field as the description, or even integrate with some third-party API to generate the image using AI. As users are editing documents within the Admin Panel, they have the option to "auto-generate" these fields. When clicked, this plugin will execute your own custom functions that re-generate the title, description, and image. This way you can build your own SEO writing assistance directly into your application. For example, you could append your site name onto the page title, or use the document's excerpt field as the description, or even integrate with some third-party API to generate the image using AI.
To help you visualize what your page might look like in a search engine, a preview is rendered on page just beneath the meta fields. This preview is updated in real-time as you edit your metadata. There are also visual indicators to help you write effective meta, such as a character counter for the title and description fields. You can even inject your own custom fields into the `meta` field group as your application requires, like `og:title` or `json-ld`. If you've ever used something like Yoast SEO, this plugin might feel very familiar. To help you visualize what your page might look like in a search engine, a preview is rendered on page just beneath the meta fields. This preview is updated in real-time as you edit your metadata. There are also visual indicators to help you write effective meta, such as a character counter for the title and description fields. You can even inject your own custom fields into the `meta` field group as your application requires, like `og:title` or `json-ld`. If you've ever used something like Yoast SEO, this plugin might feel very familiar.
@@ -42,7 +42,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options): In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
```ts ```ts
import { buildConfig } from 'payload/config'; import { buildConfig } from 'payload/config';
@@ -205,7 +205,7 @@ seoPlugin({
There is the option to directly import any of the fields from the plugin so that you can include them anywhere as needed. There is the option to directly import any of the fields from the plugin so that you can include them anywhere as needed.
<Banner type="info"> <Banner type="info">
You will still need to configure the plugin in the Payload config in order to configure the generation functions. You will still need to configure the plugin in the Payload Config in order to configure the generation functions.
Since these fields are imported and used directly, they don't have access to the plugin config so they may need additional arguments to work the same way. Since these fields are imported and used directly, they don't have access to the plugin config so they may need additional arguments to work the same way.
</Banner> </Banner>

View File

@@ -44,7 +44,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
## Basic Usage ## Basic Usage
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options): In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
```ts ```ts
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'
@@ -254,7 +254,7 @@ const config = buildConfig({
stripeResourceTypeSingular: 'customer', stripeResourceTypeSingular: 'customer',
fields: [ fields: [
{ {
fieldPath: 'name', // this is a field on your own Payload config fieldPath: 'name', // this is a field on your own Payload Config
stripeProperty: 'name', // use dot notation, if applicable stripeProperty: 'name', // use dot notation, if applicable
}, },
], ],

View File

@@ -16,7 +16,7 @@ Set the max number of failed login attempts before a user account is locked out
## Max Depth ## Max Depth
Querying a collection and automatically including related documents via `depth` incurs a performance cost. Also, it's possible that your configs may have circular relationships, meaning scenarios where an infinite amount of relationships might populate back and forth until your server times out and crashes. You can prevent any potential of depth-related issues by setting a `maxDepth` property on your Payload config.. The maximum allowed depth should be as small as possible without interrupting dev experience, and it defaults to `10`. Querying a collection and automatically including related documents via `depth` incurs a performance cost. Also, it's possible that your configs may have circular relationships, meaning scenarios where an infinite amount of relationships might populate back and forth until your server times out and crashes. You can prevent any potential of depth-related issues by setting a `maxDepth` property on your Payload Config.. The maximum allowed depth should be as small as possible without interrupting dev experience, and it defaults to `10`.
## Cross-Site Request Forgery (CSRF) ## Cross-Site Request Forgery (CSRF)
@@ -24,15 +24,15 @@ CSRF prevention will verify the authenticity of each request to your API to prev
## Cross Origin Resource Sharing (CORS) ## Cross Origin Resource Sharing (CORS)
To securely allow headless operation you will need to configure the allowed origins for requests to be able to use the Payload API. You can see how to set CORS as well as other payload configuration settings [here](/docs/configuration/overview) To securely allow headless operation you will need to configure the allowed origins for requests to be able to use the Payload API. You can see how to set CORS as well as other Payload configuration settings [here](/docs/configuration/overview)
## Limiting GraphQL Complexity ## Limiting GraphQL Complexity
Because GraphQL gives the power of query writing outside a server's control, someone with bad intentions might write a maliciously complex query and bog down your server. To prevent resource-intensive GraphQL requests, Payload provides a way specify complexity limits which are based on a complexity score that is calculated for each request. Because GraphQL gives the power of query writing outside a server's control, someone with bad intentions might write a maliciously complex query and bog down your server. To prevent resource-intensive GraphQL requests, Payload provides a way specify complexity limits which are based on a complexity score that is calculated for each request.
Any GraphQL request that is calculated to be too expensive is rejected. On the Payload config, in `graphQL` you can set the `maxComplexity` value as an integer. For reference, the default complexity value for each added field is 1, and all `relationship` and `upload` fields are assigned a value of 10. Any GraphQL request that is calculated to be too expensive is rejected. On the Payload Config, in `graphQL` you can set the `maxComplexity` value as an integer. For reference, the default complexity value for each added field is 1, and all `relationship` and `upload` fields are assigned a value of 10.
If you do not need GraphQL it is advised that you disable it altogether with the Payload config by setting `graphQL.disable: true`. Should you wish to enable GraphQL again, you can remove this property or set it `false`, any time. By turning it off, Payload will bypass creating schemas from your collections and will not register the route. If you do not need GraphQL it is advised that you disable it altogether with the Payload Config by setting `graphQL.disable: true`. Should you wish to enable GraphQL again, you can remove this property or set it `false`, any time. By turning it off, Payload will bypass creating schemas from your collections and will not register the route.
## Malicious File Uploads ## Malicious File Uploads

View File

@@ -570,7 +570,7 @@ In addition to the dynamically generated endpoints above Payload also has REST e
## Custom Endpoints ## Custom Endpoints
Additional REST API endpoints can be added to your application by providing an array of `endpoints` in various places within a Payload config. Custom endpoints are useful for adding additional middleware on existing routes or for building custom functionality into Payload apps and plugins. Endpoints can be added at the top of the Payload config, `collections`, and `globals` and accessed respective of the api and slugs you have configured. Additional REST API endpoints can be added to your application by providing an array of `endpoints` in various places within a Payload Config. Custom endpoints are useful for adding additional middleware on existing routes or for building custom functionality into Payload apps and plugins. Endpoints can be added at the top of the Payload Config, `collections`, and `globals` and accessed respective of the api and slugs you have configured.
Each endpoint object needs to have: Each endpoint object needs to have:
@@ -579,7 +579,7 @@ Each endpoint object needs to have:
| **`path`** | A string for the endpoint route after the collection or globals slug | | **`path`** | A string for the endpoint route after the collection or globals slug |
| **`method`** | The lowercase HTTP verb to use: 'get', 'head', 'post', 'put', 'delete', 'connect' or 'options' | | **`method`** | The lowercase HTTP verb to use: 'get', 'head', 'post', 'put', 'delete', 'connect' or 'options' |
| **`handler`** | A function or array of functions to be called with **req**, **res** and **next** arguments. [Next.js](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) | | **`handler`** | A function or array of functions to be called with **req**, **res** and **next** arguments. [Next.js](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) |
| **`root`** | When `true`, defines the endpoint on the root Next.js app, bypassing Payload handlers and the `routes.api` subpath. Note: this only applies to top-level endpoints of your Payload config, endpoints defined on `collections` or `globals` cannot be root. | | **`root`** | When `true`, defines the endpoint on the root Next.js app, bypassing Payload handlers and the `routes.api` subpath. Note: this only applies to top-level endpoints of your Payload Config, endpoints defined on `collections` or `globals` cannot be root. |
| **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`custom`** | Extension point for adding custom data (e.g. for plugins) |
Example: Example:

View File

@@ -16,7 +16,7 @@ To use the Slate editor, first you need to install it:
npm install --save @payloadcms/richtext-slate npm install --save @payloadcms/richtext-slate
``` ```
After installation, you can pass it to your top-level Payload config: After installation, you can pass it to your top-level Payload Config:
```ts ```ts
import { buildConfig } from 'payload/config' import { buildConfig } from 'payload/config'
@@ -63,7 +63,7 @@ export const Pages: CollectionConfig = {
**`elements`** **`elements`**
The `elements` property is used to specify which built-in or custom [SlateJS elements](https://docs.slatejs.org/concepts/02-nodes#element) should be made available to the field within the admin panel. The `elements` property is used to specify which built-in or custom [SlateJS elements](https://docs.slatejs.org/concepts/02-nodes#element) should be made available to the field within the Admin Panel.
The default `elements` available in Payload are: The default `elements` available in Payload are:

View File

@@ -10,7 +10,7 @@ keywords: admin, components, custom, customize, documentation, Content Managemen
### "Unauthorized, you must be logged in to make this request" when attempting to log in ### "Unauthorized, you must be logged in to make this request" when attempting to log in
This means that your auth cookie is not being set or accepted correctly upon logging in. To resolve heck the following settings in your Payload config: This means that your auth cookie is not being set or accepted correctly upon logging in. To resolve heck the following settings in your Payload Config:
- CORS - If you are using the '\*', try to explicitly only allow certain domains instead including the one you have specified. - CORS - If you are using the '\*', try to explicitly only allow certain domains instead including the one you have specified.
- CSRF - Do you have this set? if so, make sure your domain is whitelisted within the csrf domains. If not, probably not the issue, but probably can't hurt to whitelist it anyway. - CSRF - Do you have this set? if so, make sure your domain is whitelisted within the csrf domains. If not, probably not the issue, but probably can't hurt to whitelist it anyway.

View File

@@ -6,11 +6,11 @@ desc: Generate your own TypeScript interfaces based on your collections and glob
keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, nextjs keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
--- ---
While building your own custom functionality into Payload, like plugins, hooks, access control functions, custom views, GraphQL queries / mutations, or anything else, you may benefit from generating your own TypeScript types dynamically from your Payload config itself. While building your own custom functionality into Payload, like plugins, hooks, access control functions, custom views, GraphQL queries / mutations, or anything else, you may benefit from generating your own TypeScript types dynamically from your Payload Config itself.
## Types generation script ## Types generation script
Run the following command in a Payload project to generate types based on your Payload config: Run the following command in a Payload project to generate types based on your Payload Config:
``` ```
payload generate:types payload generate:types
@@ -46,7 +46,7 @@ declare module 'payload' {
## Custom output file path ## Custom output file path
You can specify where you want your types to be generated by adding a property to your Payload config: You can specify where you want your types to be generated by adding a property to your Payload Config:
```ts ```ts
// payload.config.ts // payload.config.ts
@@ -59,7 +59,7 @@ You can specify where you want your types to be generated by adding a property t
} }
``` ```
The above example places your types next to your Payload config itself as the file `generated-types.ts`. The above example places your types next to your Payload Config itself as the file `generated-types.ts`.
## Custom generated types ## Custom generated types
@@ -100,7 +100,7 @@ This function takes the existing JSON schema as an argument and returns the modi
## Example Usage ## Example Usage
For example, let's look at the following simple Payload config: For example, let's look at the following simple Payload Config:
```ts ```ts
import type { Config } from 'payload' import type { Config } from 'payload'
@@ -211,7 +211,7 @@ export interface Collection1 {
## Using your types ## Using your types
Now that your types have been generated, payloads local API will now be typed. It is common for users to want to use this in their frontend code, we recommend generating them with payload and then copying the file over to your frontend codebase. This is the simplest way to get your types into your frontend codebase. Now that your types have been generated, payloads local API will now be typed. It is common for users to want to use this in their frontend code, we recommend generating them with Payload and then copying the file over to your frontend codebase. This is the simplest way to get your types into your frontend codebase.
### Adding an NPM script ### Adding an NPM script

View File

@@ -14,7 +14,7 @@ keywords: uploads, images, media, overview, documentation, Content Management Sy
<LightDarkImage <LightDarkImage
srcLight="https://payloadcms.com/images/docs/upload-admin.jpg" srcLight="https://payloadcms.com/images/docs/upload-admin.jpg"
srcDark="https://payloadcms.com/images/docs/upload-admin.jpg" srcDark="https://payloadcms.com/images/docs/upload-admin.jpg"
alt="Shows an Upload enabled collection in the Payload admin panel" alt="Shows an Upload enabled collection in the Payload Admin Panel"
caption="Admin Panel screenshot depicting a Media Collection with Upload enabled" caption="Admin Panel screenshot depicting a Media Collection with Upload enabled"
/> />
@@ -108,7 +108,7 @@ _An asterisk denotes that an option is required._
### Payload-wide Upload Options ### Payload-wide Upload Options
Upload options are specifiable on a Collection by Collection basis, you can also control app wide options by passing your base Payload config an `upload` property containing an object supportive of all `Busboy` configuration options. [Click here](https://github.com/mscdex/busboy#api) for more documentation about what you can control. Upload options are specifiable on a Collection by Collection basis, you can also control app wide options by passing your base Payload Config an `upload` property containing an object supportive of all `Busboy` configuration options. [Click here](https://github.com/mscdex/busboy#api) for more documentation about what you can control.
A common example of what you might want to customize within Payload-wide Upload options would be to increase the allowed `fileSize` of uploads sent to Payload: A common example of what you might want to customize within Payload-wide Upload options would be to increase the allowed `fileSize` of uploads sent to Payload: