docs: more misc improvements (#7115)
This commit is contained in:
Jacob Fletcher
@@ -45,7 +45,7 @@ Function that accepts one argument, containing `{ req, token, user }`, that allo
|
||||
Example:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Customers: CollectionConfig = {
|
||||
slug: 'customers',
|
||||
@@ -117,7 +117,7 @@ Function that accepts one argument, containing `{ req, token, user }`, that allo
|
||||
Example:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Customers: CollectionConfig = {
|
||||
slug: 'customers',
|
||||
|
||||
@@ -39,7 +39,7 @@ Every Payload Collection can opt-in to supporting Authentication by specifying t
|
||||
Simple example collection:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Admins: CollectionConfig = {
|
||||
slug: 'admins',
|
||||
|
||||
@@ -104,7 +104,7 @@ Projects generated from a template will come pre-configured with the official Cl
|
||||
|
||||
```js
|
||||
import { payloadCloud } from '@payloadcms/plugin-cloud'
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
plugins: [payloadCloud()],
|
||||
|
||||
@@ -10,7 +10,7 @@ A Collection is a group of records, called Documents, that share a common schema
|
||||
|
||||
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.
|
||||
All Collections automatically accessible through the [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):
|
||||
|
||||
@@ -25,6 +25,11 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Tip:</strong>
|
||||
If your Collection is only ever meant to contain a single Document, consider using a [Global](./globals) instead.
|
||||
</Banner>
|
||||
|
||||
## Config Options
|
||||
|
||||
It's often best practice to write your Collections in separate files and then import them into the main [Payload Config](../overview).
|
||||
@@ -60,7 +65,7 @@ The following options are available:
|
||||
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
||||
| **`disableDuplicate`** | When true, do not show the "Duplicate" button while editing documents within this Collection and prevent `duplicate` from all APIs. |
|
||||
| **`defaultSort`** | Pass a top-level field to sort by default in the Collection List View. Prefix the name of the field with a minus symbol ("-") to sort in descending order. |
|
||||
| **`dbName`** | Custom table or Collection name depending on the database adapter. Auto-generated from slug if not defined. |
|
||||
| **`dbName`** | Custom table or Collection name depending on the Database Adapter. Auto-generated from slug if not defined. |
|
||||
| **`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. |
|
||||
| **`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. |
|
||||
|
||||
@@ -10,7 +10,7 @@ Globals are in many ways similar to [Collections](../configuration/collections),
|
||||
|
||||
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.
|
||||
All Globals are automatically accessible through the [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):
|
||||
|
||||
@@ -25,6 +25,11 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Tip:</strong>
|
||||
If you have more than one Global that share the same structure, consider using a [Collection](../configuration/collections) instead.
|
||||
</Banner>
|
||||
|
||||
## Config Options
|
||||
|
||||
It's often best practice to write your Globals in separate files and then import them into the main [Payload Config](./overview).
|
||||
@@ -67,7 +72,7 @@ The following options are available:
|
||||
| **`access`** | Provide access control functions to define exactly who should be able to do what with this Global. [More details](../access-control/overview/#globals). |
|
||||
| **`admin`** | The configuration options for the Admin Panel. [More details](#admin-options). |
|
||||
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
||||
| **`dbName`** | Custom table or collection name for this Global depending on the database adapter. Auto-generated from slug if not defined. |
|
||||
| **`dbName`** | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. |
|
||||
| **`description`** | Text or React component to display below the Global header to give editors more information. |
|
||||
| **`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. |
|
||||
@@ -170,7 +175,7 @@ import { GlobalConfig } from 'payload'
|
||||
```
|
||||
|
||||
```ts
|
||||
import { SanitizedGlobalConfig } from 'payload/types'
|
||||
import { SanitizedGlobalConfig } from 'payload'
|
||||
|
||||
// This is the type used after an incoming Global config is fully sanitized.
|
||||
// Generally, this is only used internally by Payload.
|
||||
|
||||
@@ -6,9 +6,22 @@ desc: Manage and customize internationalization support in your CMS editor exper
|
||||
keywords: internationalization, i18n, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
||||
---
|
||||
|
||||
The [Admin Panel](../admin/overview) is translated in over [30 languages and counting](https://github.com/payloadcms/payload/tree/beta/packages/translations). With i18n, editors can navigate the interface and read API error messages in their preferred language. Users can easily select a language from the Account View and have their preference saved for future visits.
|
||||
The [Admin Panel](../admin/overview) is translated in over [30 languages and counting](https://github.com/payloadcms/payload/tree/beta/packages/translations). With I18n, editors can navigate the interface and read API error messages in their preferred language. This is similar to [Localization](./localization), but instead of managing translations for the data itself, you are managing translations for your application's interface.
|
||||
|
||||
By default, Payload comes with preinstalled with English, but you can easily load other languages into your own application. Languages are automatically detected based on the user's browser. If no language was detected, or if the user's language is not yet supported by your application, English will be chosen.
|
||||
By default, Payload comes with preinstalled with English, but you can easily load other languages into your own application. Languages are automatically detected based on the request. If no language was detected, or if the user's language is not yet supported by your application, English will be chosen.
|
||||
|
||||
To configure I18n, use the `i18n` key in your [Payload Config](./overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
// ...
|
||||
i18n: { // highlight-line
|
||||
// ...
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Note:</strong>
|
||||
@@ -19,19 +32,44 @@ By default, Payload comes with preinstalled with English, but you can easily loa
|
||||
|
||||
You can easily customize and override any of the i18n settings that Payload provides by default. Payload will use your custom options and merge them in with its own.
|
||||
|
||||
To add a new language, use the `i18n` key in your [Payload Config](./overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
import { en } from 'payload/i18n/en'
|
||||
import { de } from 'payload/i18n/de'
|
||||
|
||||
export default buildConfig({
|
||||
// ...
|
||||
// highlight-start
|
||||
i18n: {
|
||||
// Payload will support either English or German,
|
||||
// able to be specified in preferences on a user-by-user basis
|
||||
fallbackLanguage: 'en', // default
|
||||
debug: false, // default
|
||||
}
|
||||
// highlight-end
|
||||
})
|
||||
```
|
||||
|
||||
The following options are available:
|
||||
|
||||
| Option | Description |
|
||||
| --------------------- | --------------------------------|
|
||||
| **`fallbackLanguage`** | The language to fall back to if the user's preferred language is not supported. Default is `'en'`. |
|
||||
| **`debug`** | Whether to log debug information to the console. Default is `false`. |
|
||||
| **`translations`** | An object containing the translations. The keys are the language codes and the values are the translations. |
|
||||
| **`supportedLanguages`** | An object containing the supported languages. The keys are the language codes and the values are the translations. |
|
||||
|
||||
## Adding Languages
|
||||
|
||||
You can easily add new languages to your Payload app by providing the translations for the new language. Payload maintains a number of built-in translations that can be imported from `@payloadcms/translations`, but you can also provide your own [Custom Translations](#custom-translations) to support any language.
|
||||
|
||||
To add a new language, use the `i18n.supportedLanguages` key in your [Payload Config](./overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
import { en } from '@payloadcms/translations/languages/en'
|
||||
import { de } from '@payloadcms/translations/languages/de'
|
||||
|
||||
export default buildConfig({
|
||||
// ...
|
||||
// highlight-start
|
||||
i18n: {
|
||||
supportedLanguages: { en, de },
|
||||
},
|
||||
// highlight-end
|
||||
@@ -43,27 +81,18 @@ export default buildConfig({
|
||||
It's best to only support the languages that you need so that the bundled JavaScript is kept to a minimum for your project.
|
||||
</Banner>
|
||||
|
||||
The following options are available:
|
||||
### Custom Translations
|
||||
|
||||
| Option | Description |
|
||||
| --------------------- | --------------------------------|
|
||||
| **`fallbackLanguage`** | The language to fall back to if the user's preferred language is not supported. Default is `'en'`. |
|
||||
| **`debug`** | Whether to log debug information to the console. Default is `false`. |
|
||||
| **`translations`** | An object containing the translations. The keys are the language codes and the values are the translations. |
|
||||
| **`supportedLanguages`** | An object containing the supported languages. The keys are the language codes and the values are the translations. |
|
||||
You can customize Payload's built-in translations either by extending existing languages or by adding new languages entirely. This can be done by injecting new translation strings into existing languages, or by providing an entirely new language keys altogether.
|
||||
|
||||
## Custom Translations
|
||||
|
||||
Here is an example of how you can add custom translations to your project:
|
||||
To add Custom Translations, use the `i18n.translations` key in your [Payload Config](./overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
//...
|
||||
i18n: {
|
||||
fallbackLanguage: 'en', // default
|
||||
debug: false, // default
|
||||
// highlight-start
|
||||
translations: {
|
||||
en: {
|
||||
@@ -83,9 +112,11 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
While Payload's built-in features come translated, you may want to also translate parts of your project's configuration too. This is possible in places like Collections and Globals labels and groups, field labels, descriptions and input placeholder text. The admin UI will display all the correct translations you provide based on the user's language.
|
||||
### Project Translations
|
||||
|
||||
Here is an example of a simple collection supporting both English and Spanish editors:
|
||||
While Payload's built-in features come fully translated, you may also want to translate parts of your own project. This is possible in places like [Collections](./collections) and [Globals](./globals), such as on their labels and groups, field labels, descriptions or input placeholder text.
|
||||
|
||||
To do this, provide the translations wherever applicable, keyed to the language code:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload'
|
||||
@@ -94,38 +125,44 @@ export const Articles: CollectionConfig = {
|
||||
slug: 'articles',
|
||||
labels: {
|
||||
singular: {
|
||||
// highlight-start
|
||||
en: 'Article',
|
||||
es: 'Artículo',
|
||||
// highlight-end
|
||||
},
|
||||
plural: {
|
||||
// highlight-start
|
||||
en: 'Articles',
|
||||
es: 'Artículos',
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
admin: {
|
||||
group: { en: 'Content', es: 'Contenido' },
|
||||
group: {
|
||||
// highlight-start
|
||||
en: 'Content',
|
||||
es: 'Contenido',
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
fields: [
|
||||
{
|
||||
name: 'title',
|
||||
type: 'text',
|
||||
label: {
|
||||
// highlight-start
|
||||
en: 'Title',
|
||||
es: 'Título',
|
||||
// highlight-end
|
||||
},
|
||||
admin: {
|
||||
placeholder: { en: 'Enter title', es: 'Introduce el título' },
|
||||
placeholder: {
|
||||
// highlight-start
|
||||
en: 'Enter title',
|
||||
es: 'Introduce el título'
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'type',
|
||||
type: 'radio',
|
||||
options: [
|
||||
{
|
||||
value: 'news',
|
||||
label: { en: 'News', es: 'Noticias' },
|
||||
}, // etc...
|
||||
],
|
||||
},
|
||||
],
|
||||
}
|
||||
@@ -177,7 +214,7 @@ import type {
|
||||
NestedKeysStripped,
|
||||
TFunction,
|
||||
} from '@payloadcms/translations'
|
||||
import type { Field } from 'payload/types'
|
||||
import type { Field } from 'payload'
|
||||
|
||||
const customTranslations = {
|
||||
en: {
|
||||
|
||||
@@ -6,32 +6,41 @@ desc: Add and maintain as many locales as you need by adding Localization to you
|
||||
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
|
||||
localization support is opt-in by default. To do so, follow the two steps below.
|
||||
Localization is one of the most important features of a modern CMS. It allows you to manage content in multiple languages, then serve it to your users based on their requested language. This is similar to [I18n](./i18n), but instead of managing translations for your application's interface, you are managing translations for the data itself.
|
||||
|
||||
## Enabling in the Payload Config
|
||||
With Localization, you can begin to serve personalized content to your users based on their specific language preferences, such as a multilingual website or multi-site application. There are no limits to the number of locales you can add to your Payload project.
|
||||
|
||||
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.
|
||||
|
||||
**Example Payload Config set up for localization:**
|
||||
To configure Localization, use the `localization` key in your [Payload Config](./overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
collections: [
|
||||
// collections go here
|
||||
],
|
||||
localization: {
|
||||
locales: ['en', 'es', 'de'],
|
||||
defaultLocale: 'en',
|
||||
fallback: true,
|
||||
// ...
|
||||
localization: { // highlight-line
|
||||
// ...
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**Example Payload Config set up for localization with full locales objects:**
|
||||
## Config Options
|
||||
|
||||
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.
|
||||
|
||||
To configure locales, use the `localization.locales` property in your [Payload Config](./overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
// ...
|
||||
localization: {
|
||||
locales: ['en', 'es', 'de'] // highlight-line
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
You can also define locales using [full configuration objects](#locale-object):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
@@ -60,50 +69,26 @@ export default buildConfig({
|
||||
})
|
||||
```
|
||||
|
||||
**Example Payload Config set up for localization with full locales objects (
|
||||
including [internationalization](/docs/configuration/i18n) support):**
|
||||
<Banner type="success">
|
||||
<strong>Tip:</strong>
|
||||
Localization works very well alongside [I18n](/docs/configuration/i18n).
|
||||
</Banner>
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
The following options are available:
|
||||
|
||||
export default buildConfig({
|
||||
collections: [
|
||||
// collections go here
|
||||
],
|
||||
localization: {
|
||||
locales: [
|
||||
{
|
||||
label: {
|
||||
en: 'English', // English label
|
||||
nb: 'Engelsk', // Norwegian label
|
||||
},
|
||||
code: 'en',
|
||||
},
|
||||
{
|
||||
label: {
|
||||
en: 'Norwegian', // English label
|
||||
nb: 'Norsk', // Norwegian label
|
||||
},
|
||||
code: 'nb',
|
||||
},
|
||||
],
|
||||
defaultLocale: 'en',
|
||||
fallback: true,
|
||||
},
|
||||
})
|
||||
```
|
||||
| Option | Description |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **`locales`** | Array of all the languages that you would like to support. [More details](#locales) |
|
||||
| **`defaultLocale`** | Required string that matches one of the locale codes from the array provided. By default, if no locale is specified, documents will be returned in this locale. |
|
||||
| **`fallback`** | Boolean enabling "fallback" locale functionality. If a document is requested in a locale, but a field does not have a localized value corresponding to the requested locale, then if this property is enabled, the document will automatically fall back to the fallback locale value. If this property is not enabled, the value will not be populated. |
|
||||
|
||||
**Here is a brief explanation of each of the options available within the `localization` property:**
|
||||
### Locales
|
||||
|
||||
**`locales`**
|
||||
The locales array is a list of all the languages that you would like to support. This can be strings for each language code, or [full configuration objects](#locale-object) for more advanced options.
|
||||
|
||||
Array-based list of all the languages that you would like to support. This can be an array containing strings for each
|
||||
language code you want your project to store and serve or objects with a `label`, a locale `code`, `rtl` (
|
||||
right-to-left), and `fallbackLocale` property. The locale codes do not need to be in any specific format. It's up to you
|
||||
to define how to represent your locales. Common patterns are to use two-letter ISO 639 language codes or four-letter
|
||||
language and country codes (ISO 3166‑1) such as `en-US`, `en-UK`, `es-MX`, etc.
|
||||
The locale codes do not need to be in any specific format. It's up to you to define how to represent your locales. Common patterns are to use two-letter ISO 639 language codes or four-letter language and country codes (ISO 3166‑1) such as `en-US`, `en-UK`, `es-MX`, etc.
|
||||
|
||||
## Locale Object Properties
|
||||
#### Locale Object
|
||||
|
||||
| Option | Description |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
@@ -114,23 +99,11 @@ language and country codes (ISO 3166‑1) such as `en-US`, `en-UK`, `es-MX`, etc
|
||||
|
||||
_\* An asterisk denotes that a property is required._
|
||||
|
||||
**`defaultLocale`**
|
||||
## Field Localization
|
||||
|
||||
Required string that matches one of the locale codes from the array provided. By default, if no locale is specified,
|
||||
documents will be returned in this locale.
|
||||
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.
|
||||
|
||||
**`fallback`**
|
||||
|
||||
Boolean enabling "fallback" locale functionality. If a document is requested in a locale, but a field does not have a
|
||||
localized value corresponding to the requested locale, then if this property is enabled, the document will automatically
|
||||
fall back to the fallback locale value. If this property is not enabled, the value will not be populated.
|
||||
|
||||
## Field by field localization
|
||||
|
||||
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.
|
||||
|
||||
**Here is an example of how to enable localization for a field:**
|
||||
**Here is an example of how to enable Localization for a field:**
|
||||
|
||||
```js
|
||||
{
|
||||
@@ -142,31 +115,27 @@ to support localization, you need to specify each field that you would like to l
|
||||
}
|
||||
```
|
||||
|
||||
With the above configuration, the `title` field will now be saved in the database as an object of all locales instead of
|
||||
a single string.
|
||||
With the above configuration, the `title` field will now be saved in the database as an object of all locales instead of a single string.
|
||||
|
||||
All field types with a `name` property support the `localized` property—even the more complex field types like `array`s
|
||||
and `block`s.
|
||||
All field types with a `name` property support the `localized` property—even the more complex field types like `array`s and `block`s.
|
||||
|
||||
<Banner>
|
||||
<Banner type="info">
|
||||
<strong>Note:</strong>
|
||||
<br />
|
||||
Enabling localization for field types that support nested fields will automatically create
|
||||
Enabling Localization for field types that support nested fields will automatically create
|
||||
localized "sets" of all fields contained within the field. For example, if you have a page layout
|
||||
using a blocks field type, you have the choice of either localizing the full layout, by enabling
|
||||
localization on the top-level blocks field, or only certain fields within the layout.
|
||||
Localization on the top-level blocks field, or only certain fields within the layout.
|
||||
</Banner>
|
||||
|
||||
<Banner type="warning">
|
||||
<strong>Important:</strong>
|
||||
<br />
|
||||
When converting an existing field to or from `localized: true` the data structure in the document
|
||||
will change for this field and so existing data for this field will be lost. Before changing the
|
||||
localization setting on fields with existing data, you may need to consider a field migration
|
||||
Localization setting on fields with existing data, you may need to consider a field migration
|
||||
strategy.
|
||||
</Banner>
|
||||
|
||||
## Retrieving localized docs
|
||||
## Retrieving Localized Docs
|
||||
|
||||
When retrieving documents, you can specify which locale you'd like to receive as well as which fallback locale should be
|
||||
used.
|
||||
@@ -234,10 +203,9 @@ const posts = await payload.find({
|
||||
})
|
||||
```
|
||||
|
||||
<Banner type="alert">
|
||||
<Banner type="success">
|
||||
<strong>Tip:</strong>
|
||||
<br />
|
||||
The REST and Local APIs can return all localization data in one request by passing 'all' or '*' as
|
||||
The REST and Local APIs can return all Localization data in one request by passing 'all' or '*' as
|
||||
the <strong>locale</strong> parameter. The response will be structured so that field values come
|
||||
back as the full objects keyed for each locale instead of the single, translated value.
|
||||
</Banner>
|
||||
|
||||
@@ -6,7 +6,7 @@ desc: The Payload Config is central to everything that Payload does, from adding
|
||||
keywords: overview, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
||||
---
|
||||
|
||||
Payload is a _config-based_, code-first CMS and application framework. The Payload Config is central to everything that Payload does, allowing for deep configuration of your application through a simple and intuitive API.
|
||||
Payload is a _config-based_, code-first CMS and application framework. The Payload Config is central to everything that Payload does, allowing for deep configuration of your application through a simple and intuitive API. The Payload Config is a fully-typed JavaScript object that can be infinitely extended upon.
|
||||
|
||||
Everything from your [Database](../database/overview) choice, to the appearance of the [Admin Panel](../admin/overview), is fully controlled through the Payload Config. From here you can define [Fields](../fields/overview), add [Localization](./localization), enable [Authentication](../authentication/overview), configure [Access Control](../access-control/overview), and so much more.
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ all changes that you attempt to make within the migration, and the `down` should
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
@@ -127,7 +127,7 @@ npm run payload migrate:fresh
|
||||
|
||||
## When to run migrations
|
||||
|
||||
Depending on which database adapter you use, your migration workflow might differ subtly.
|
||||
Depending on which Database Adapter you use, your migration workflow might differ subtly.
|
||||
|
||||
In relational databases, migrations will be **required** for non-development database environments. But with MongoDB, you might only need to run migrations once in a while (or never even need them).
|
||||
|
||||
|
||||
@@ -6,22 +6,44 @@ keywords: database, mongodb, postgres, documentation, Content Management System,
|
||||
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. Currently, Payload officially supports the following Database Adapters:
|
||||
Payload is database agnostic, meaning you can use any type of database behind Payload's familiar APIs. Payload is designed to interact with your database through a Database Adapter, which is a thin layer that translates Payload's internal data structures into your database's native data structures.
|
||||
|
||||
Currently, Payload officially supports the following Database Adapters:
|
||||
|
||||
- [MongoDB](/docs/database/mongodb) with [Mongoose](https://mongoosejs.com/)
|
||||
- [Postgres](/docs/database/postgres) with [Drizzle](https://drizzle.team/)
|
||||
- Coming soon: SQLite and MySQL using Drizzle.
|
||||
|
||||
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 configure a Database Adapter, use the `db` property in your [Payload Config](../configuration/overview):
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Note:</strong>
|
||||
In the future, we will be adding support for SQLite and MySQL using Drizzle.
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
import { mongooseAdapter } from '@payloadcms/db-mongodb'
|
||||
|
||||
export default buildConfig({
|
||||
// ...
|
||||
// highlight-start
|
||||
db: mongooseAdapter({
|
||||
url: process.env.DATABASE_URI,
|
||||
}),
|
||||
// highlight-end
|
||||
})
|
||||
```
|
||||
|
||||
<Banner type="warning">
|
||||
<strong>Reminder:</strong>
|
||||
The Database Adapter is an external dependency and must be installed in your project separately from Payload. You can find the installation instructions for each Database Adapter in their respective documentation.
|
||||
</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 two main categories of databases to choose from:
|
||||
|
||||
- [Non-Relational Databases](#non-relational-databases)
|
||||
- [Relational Databases](#relational-databases)
|
||||
|
||||
### 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.
|
||||
@@ -43,34 +65,8 @@ You should prefer a relational DB like Postgres if:
|
||||
- You require enforced data consistency at the database level
|
||||
- You have a lot of relationships between collections and require relationships to be enforced
|
||||
|
||||
### Payload Differences
|
||||
## Payload Differences
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
To add a Database Adapter, use the `db` property in your [Payload Config](../configuration/overview):
|
||||
|
||||
```ts
|
||||
import { postgresAdapter } from '@payloadcms/db-postgres'
|
||||
|
||||
export default buildConfig({
|
||||
// Your config goes here
|
||||
collections: [
|
||||
// Collections go here
|
||||
],
|
||||
// Here is where you pass your database adapter
|
||||
// and the adapter will require options specific to itself
|
||||
// highlight-start
|
||||
db: postgresAdapter({
|
||||
pool: {
|
||||
connectionString: process.env.DATABASE_URI,
|
||||
},
|
||||
}),
|
||||
// highlight-end
|
||||
})
|
||||
```
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title: Postgres
|
||||
label: Postgres
|
||||
order: 50
|
||||
desc: Payload supports Postgres through an officially supported Drizzle database adapter.
|
||||
desc: Payload supports Postgres through an officially supported Drizzle Database Adapter.
|
||||
keywords: Postgres, documentation, typescript, Content Management System, cms, headless, javascript, node, react, nextjs
|
||||
---
|
||||
|
||||
|
||||
@@ -49,7 +49,7 @@ Simple Mail Transfer Protocol (SMTP) options can be passed in using the `transpo
|
||||
**Example email options using SMTP:**
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
|
||||
|
||||
export default buildConfig({
|
||||
@@ -72,7 +72,7 @@ export default buildConfig({
|
||||
**Example email options using nodemailer.createTransport:**
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
|
||||
import nodemailer from 'nodemailer'
|
||||
|
||||
@@ -99,7 +99,7 @@ You also have the ability to bring your own nodemailer transport. This is an exa
|
||||
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
|
||||
import nodemailerSendgrid from 'nodemailer-sendgrid'
|
||||
|
||||
@@ -136,7 +136,7 @@ The Resend adapter requires an API key to be passed in the options. This can be
|
||||
| apiKey | The API key for the Resend service. |
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { resendAdapter } from '@payloadcms/email-resend'
|
||||
|
||||
export default buildConfig({
|
||||
|
||||
@@ -45,7 +45,7 @@ keywords: array, fields, config, configuration, documentation, Content Managemen
|
||||
| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). |
|
||||
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
||||
| **`interfaceName`** | Create a top level, reusable [Typescript interface](/docs/typescript/generating-types#custom-field-interfaces) & [GraphQL type](/docs/graphql/graphql-schema#custom-field-schemas). |
|
||||
| **`dbName`** | Custom table name for the field when using SQL database adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`dbName`** | Custom table name for the field when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`typescriptSchema`** | Override field type generation with providing a JSON schema |
|
||||
|
||||
_\* An asterisk denotes that a property is required._
|
||||
@@ -65,7 +65,7 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -82,7 +82,7 @@ Blocks are defined as separate configs of their own.
|
||||
| **`imageAltText`** | Customize this block's image thumbnail alt text. |
|
||||
| **`interfaceName`** | Create a top level, reusable [Typescript interface](/docs/typescript/generating-types#custom-field-interfaces) & [GraphQL type](/docs/graphql/graphql-schema#custom-field-schemas). |
|
||||
| **`graphQL.singularName`** | Text to use for the GraphQL schema name. Auto-generated from slug if not defined. NOTE: this is set for deprecation, prefer `interfaceName`. |
|
||||
| **`dbName`** | Custom table name for this block type when using SQL database adapter ([Postgres](/docs/database/postgres)). Auto-generated from slug if not defined.
|
||||
| **`dbName`** | Custom table name for this block type when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from slug if not defined.
|
||||
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
||||
|
||||
### Auto-generated data per block
|
||||
@@ -102,7 +102,7 @@ The Admin Panel provides each block with a `blockName` field which optionally al
|
||||
`collections/ExampleCollection.js`
|
||||
|
||||
```ts
|
||||
import { Block, CollectionConfig } from 'payload/types'
|
||||
import { Block, CollectionConfig } from 'payload'
|
||||
|
||||
const QuoteBlock: Block = {
|
||||
slug: 'Quote', // required
|
||||
@@ -145,5 +145,5 @@ export const ExampleCollection: CollectionConfig = {
|
||||
As you build your own Block configs, you might want to store them in separate files but retain typing accordingly. To do so, you can import and use Payload's `Block` type:
|
||||
|
||||
```ts
|
||||
import type { Block } from 'payload/types'
|
||||
import type { Block } from 'payload'
|
||||
```
|
||||
|
||||
@@ -41,7 +41,7 @@ _\* An asterisk denotes that a property is required._
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -59,7 +59,7 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
|
||||
`collections/ExampleCollection.ts
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -42,7 +42,7 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -77,7 +77,7 @@ When only `pickerAppearance` is set, an equivalent format will be rendered in th
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -54,7 +54,7 @@ Set this property to a string that will be used for browser autocomplete.
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -52,7 +52,7 @@ Set this property to `true` to hide this field's gutter within the Admin Panel.
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -57,7 +57,7 @@ In addition to the default [field admin config](/docs/fields/overview#admin-conf
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
@@ -82,7 +82,7 @@ If you only provide a URL to a schema, Payload will fetch the desired schema if
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
@@ -115,7 +115,7 @@ export const ExampleCollection: CollectionConfig = {
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -66,7 +66,7 @@ Set this property to a string that will be used for browser autocomplete.
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -6,10 +6,23 @@ 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
|
||||
---
|
||||
|
||||
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).
|
||||
Fields are the building blocks of Payload. They define the schema of the 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.
|
||||
|
||||
To configure fields, use the `fields` property in your [Collection](../configuration/collections) or [Global](../configuration/globals) config:
|
||||
|
||||
```ts
|
||||
import type { CollectionConfig } from 'payload'
|
||||
|
||||
export const Page: CollectionConfig = {
|
||||
// ...
|
||||
fields: [ // highlight-line
|
||||
// ...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Banner type="success">
|
||||
You can fully customize the appearance and behavior of all fields within the Admin Panel. [More details](../admin/fields).
|
||||
</Banner>
|
||||
|
||||
@@ -56,7 +56,7 @@ _\* An asterisk denotes that a property is required._
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -36,7 +36,7 @@ keywords: radio, fields, config, configuration, documentation, Content Managemen
|
||||
| **`required`** | Require this field to have a value. |
|
||||
| **`admin`** | Admin-specific configuration. See below for [more detail](#admin-config). |
|
||||
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
||||
| **`enumName`** | Custom enum name for this field when using SQL database adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`enumName`** | Custom enum name for this field when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`typescriptSchema`** | Override field type generation with providing a JSON schema |
|
||||
|
||||
_\* An asterisk denotes that a property is required._
|
||||
@@ -63,7 +63,7 @@ The `layout` property allows for the radio group to be styled as a horizonally o
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -143,7 +143,7 @@ called with an argument object with the following properties:
|
||||
## Example
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -33,7 +33,7 @@ _\* An asterisk denotes that a property is required._
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -38,8 +38,8 @@ keywords: select, multi-select, fields, config, configuration, documentation, Co
|
||||
| **`required`** | Require this field to have a value. |
|
||||
| **`admin`** | Admin-specific configuration. See the [default field admin config](/docs/fields/overview#admin-config) for more details. |
|
||||
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
|
||||
| **`enumName`** | Custom enum name for this field when using SQL database adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`dbName`** | Custom table name (if `hasMany` set to `true`) for this field when using SQL database adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`enumName`** | Custom enum name for this field when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`dbName`** | Custom table name (if `hasMany` set to `true`) for this field when using SQL Database Adapter ([Postgres](/docs/database/postgres)). Auto-generated from name if not defined. |
|
||||
| **`typescriptSchema`** | Override field type generation with providing a JSON schema |
|
||||
|
||||
_\* An asterisk denotes that a property is required._
|
||||
@@ -70,7 +70,7 @@ Set to `true` if you'd like this field to be sortable within the Admin UI using
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -46,7 +46,7 @@ _\* An asterisk denotes that a property is required._
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -66,7 +66,7 @@ Override the default text direction of the Admin Panel for this field. Set to `t
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -63,7 +63,7 @@ Override the default text direction of the Admin Panel for this field. Set to `t
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -41,7 +41,7 @@ _\* An asterisk denotes that a property is required._
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -62,7 +62,7 @@ _\* An asterisk denotes that a property is required._
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const ExampleCollection: CollectionConfig = {
|
||||
slug: 'example-collection',
|
||||
|
||||
@@ -10,66 +10,47 @@ Payload is based around a small and intuitive set of concepts. Before starting t
|
||||
|
||||
## Config
|
||||
|
||||
<Banner type="info">The Payload Config is where you configure everything that Payload does.</Banner>
|
||||
The Payload Config is allows for the deep configuration of your application through a simple and intuitive API. The Payload Config is a fully-typed JavaScript object that can be infinitely extended upon. [More details](../configuration/overview).
|
||||
|
||||
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.
|
||||
## Admin Panel
|
||||
|
||||
Payload dynamically generates a beautiful, fully type-safe interface to manage your users and data. The Admin Panel is a React application built using the Next.js App Router. [More details](../admin/overview).
|
||||
|
||||
## Database
|
||||
|
||||
Payload is database agnostic, meaning you can use any type of database behind Payload's familiar APIs through a Database Adapter. [More details](../database/overview).
|
||||
|
||||
## Collections
|
||||
|
||||
<Banner type="info">
|
||||
A Collection represents a type of content that Payload will store and can contain many documents.
|
||||
</Banner>
|
||||
|
||||
Collections define the shape of your data as well as all functionalities attached to that data. They will contain one or many "documents", all corresponding with the same fields and functionalities that you define.
|
||||
|
||||
They can represent anything you can store in a database - for example - pages, posts, users, people, orders, categories, events, customers, transactions, and anything else your app needs.
|
||||
A Collection is a group of records, called Documents, that share a common schema. Each Collection saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define. [More details](../configuration/collections).
|
||||
|
||||
## Globals
|
||||
|
||||
<Banner type="info">
|
||||
A Global is a "one-off" piece of content that is perfect for storing navigational structures,
|
||||
themes, top-level meta data, and more.
|
||||
</Banner>
|
||||
|
||||
Globals are in many ways similar to Collections, but there is only ever **one** instance of a Global, whereas Collections can contain many documents.
|
||||
Globals are in many ways similar to [Collections](../configuration/collections), except they correspond to only a single Document. Each Global saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define. [More details](../configuration/globals).
|
||||
|
||||
## Fields
|
||||
|
||||
<Banner type="info">
|
||||
Fields are the building blocks of Payload. Collections and Globals both use Fields to define the
|
||||
shape of the data that they store.
|
||||
</Banner>
|
||||
|
||||
Payload comes with [many different field types](../fields/overview) that give you a ton of flexibility while designing your API. Each Field type has its own potential properties that allow you to customize how they work.
|
||||
Fields are the building blocks of Payload. They define the schema of the Documents that will be stored in the [Database](../database/overview), as well as automatically generate the corresponding UI within the Admin Panel. [More details](../fields/overview).
|
||||
|
||||
## Hooks
|
||||
|
||||
<Banner type="info">
|
||||
Hooks are where you can "tie in" to existing Payload actions to perform your own additional logic
|
||||
or modify how Payload operates altogether.
|
||||
</Banner>
|
||||
|
||||
Hooks are an extremely powerful concept and are central to extending and customizing your app. Payload provides a wide variety of hooks which you can utilize. For example, imagine if you'd like to send an email every time a document is created in your Orders collection. To do so, you can add an `afterChange` hook function to your Orders collection that receives the Order data and allows you to send an email accordingly.
|
||||
|
||||
There are many more potential reasons to use Hooks. For more, visit the [Hooks documentation](/docs/hooks/overview).
|
||||
Hooks allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. [More details](../hooks/overview).
|
||||
|
||||
## Access Control
|
||||
|
||||
<Banner type="info">
|
||||
Access Control refers to Payload's system of defining who can do what to your API.
|
||||
</Banner>
|
||||
Access Control determines what a user can and cannot do with a Document. [More details](../access-control/overview).
|
||||
|
||||
Access Control is extremely powerful but easy and intuitive to manage. You can easily define your own full-blown RBAC (role-based access control) or any other access control pattern that your scenario requires. No conventions or structure is forced on you whatsoever.
|
||||
|
||||
For more, visit the [Access Control documentation](/docs/access-control/overview).
|
||||
|
||||
## Retrieving Payload data
|
||||
## Retrieving Data
|
||||
|
||||
Everything Payload does (create, read, update, delete, login, logout, etc) is exposed to you via three APIs:
|
||||
|
||||
**1 - Payload's Local API**
|
||||
- [Local API](#local-api) - Extremely fast, direct-to-database access
|
||||
- [REST API](#rest-api) - Standard HTTP endpoints for querying and mutating data
|
||||
- [GraphQL](#graphql) - A full GraphQL API with a GraphQL Playground
|
||||
|
||||
By far one of the most powerful aspects of Payload is the fact that it gives you direct-to-database access to your data. It's _extremely_ fast and does not incur any typical REST API / GraphQL / HTTP overhead - you query your database directly in Node.js / TypeScript.
|
||||
### Local API
|
||||
|
||||
By far one of the most powerful aspects of Payload is the fact that it gives you direct-to-database access to your data through the [Local API](../local-api/overview). It's _extremely_ fast and does not incur any typical REST API / GraphQL / HTTP overhead - you query your database directly in Node.js / TypeScript.
|
||||
|
||||
Everything is strongly typed and it's extremely nice to use. It works anywhere on the server, including custom Next.js route handlers, Payload hooks, Payload access control, and React Server Components.
|
||||
|
||||
@@ -104,11 +85,13 @@ const MyServerComponent: React.FC = () => {
|
||||
}
|
||||
```
|
||||
|
||||
For more docs about the Payload Local API, [click here](/docs/beta/local-api/overview).
|
||||
<Banner type="info">
|
||||
For more information about the Local API, [click here](../local-api/overview).
|
||||
</Banner>
|
||||
|
||||
**2 - The REST API**
|
||||
### REST API
|
||||
|
||||
By default, the Payload REST API will be mounted automatically for you at the `/api` path of your app.
|
||||
By default, the Payload [REST API](../rest-api/overview) will be mounted automatically for you at the `/api` path of your app.
|
||||
|
||||
For example, if you have a collection with the `slug` as `pages`, you'd fetch pages via `http://localhost:3000/api/pages`.
|
||||
|
||||
@@ -121,11 +104,13 @@ const pages = await fetch('http://localhost:3000/api/pages', {
|
||||
}).then((res) => res.json())
|
||||
```
|
||||
|
||||
For a full list of REST API endpoints, including examples, [click here](/docs/beta/rest-api/overview).
|
||||
<Banner type="info">
|
||||
For more information about the REST API, [click here](../rest-api/overview).
|
||||
</Banner>
|
||||
|
||||
**3 - GraphQL**
|
||||
### GraphQL API
|
||||
|
||||
Payload automatically exposes GraphQL queries and mutations for everything it does.
|
||||
Payload automatically exposes GraphQL queries and mutations for everything it does through a dedicated [GraphQL API](../graphql/overview).
|
||||
|
||||
By default, you'll find the GraphQL route handler in your `/app/(payload)/api/graphql` folder, which makes the GraphQL endpoint available by default at `http://localhost:3000/api/graphql`.
|
||||
|
||||
@@ -138,7 +123,9 @@ 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.
|
||||
|
||||
For more docs on GraphQL, [click here](/docs/beta/graphql/overview).
|
||||
<Banner type="info">
|
||||
For more information about the GraphQL API, [click here](../graphql/overview).
|
||||
</Banner>
|
||||
|
||||
## Depth
|
||||
|
||||
@@ -262,9 +249,13 @@ In this case, the field would not be populated, as the current depth (2) has exc
|
||||
will contain the relationship id instead of the full document.
|
||||
</Banner>
|
||||
|
||||
## Package organization
|
||||
## Plugins
|
||||
|
||||
Payload is abstracted into a set of dedicated packages, and it's a good idea to familiarize yourself with what each one is responsible for.
|
||||
Plugins allow for developers to easily inject custom—sometimes complex—functionality into Payload apps from a very small touch-point. [More details](../plugins/overview).
|
||||
|
||||
## Package Structure
|
||||
|
||||
Payload is abstracted into a set of dedicated packages to keep the core `payload` package as lightweight as possible. This allows you to only install the parts of Payload based on your unique project requirements.
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Note:</strong>
|
||||
@@ -300,7 +291,7 @@ This is the UI library that Payload's Admin Panel uses. All components are expor
|
||||
|
||||
`@payloadcms/db-postgres`, `@payloadcms/db-mongodb`
|
||||
|
||||
You can choose which database adapter you'd like to use for your project, and no matter which you choose, the entire data layer for Payload is contained within these packages. You can only use one at a time for any given project.
|
||||
You can choose which Database Adapter you'd like to use for your project, and no matter which you choose, the entire data layer for Payload is contained within these packages. You can only use one at a time for any given project.
|
||||
|
||||
`@payloadcms/richtext-lexical`, `@payloadcms/richtext-slate`
|
||||
|
||||
|
||||
@@ -15,6 +15,7 @@ Payload requires the following software:
|
||||
- Any [compatible database](/docs/database/overview) (MongoDB or Postgres)
|
||||
|
||||
<Banner type="warning">
|
||||
<strong>Important:</strong>
|
||||
Before proceeding any further, please ensure that you have the above requirements met.
|
||||
</Banner>
|
||||
|
||||
@@ -26,7 +27,7 @@ To quickly scaffold a new Payload app in the fastest way possible, you can use [
|
||||
npx create-payload-app@beta
|
||||
```
|
||||
|
||||
Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside.
|
||||
Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside. You can then start [configuring your application](../configuration/overview).
|
||||
|
||||
## Adding to an existing app
|
||||
|
||||
@@ -34,21 +35,43 @@ Adding Payload to an existing Next.js app is super straightforward. You can eith
|
||||
|
||||
If you don't have a Next.js app already, but you still want to start a project from a blank Next.js app, you can create a new Next.js app using `npx create-next-app` - and then just follow the steps below to install Payload.
|
||||
|
||||
#### 1 - install the relevant packages
|
||||
#### 1. Install the relevant packages
|
||||
|
||||
First, you'll want to add the required Payload packages to your project and can do so by running the command below (swap out `pnpm` for your package manager). Note that if you are using NPM, you might need to install using legacy peer deps (`npm i --legacy-peer-deps`).
|
||||
First, you'll want to add the required Payload packages to your project and can do so by running the command below:
|
||||
|
||||
```
|
||||
```bash
|
||||
pnpm i payload@beta @payloadcms/next@beta @payloadcms/richtext-lexical@beta sharp graphql
|
||||
```
|
||||
|
||||
You'll also need to install the database adapter that you'd like to use. You have the option of Postgres (`@payloadcms/db-postgres`) or MongoDB (`@payloadcms/db-mongodb`).
|
||||
<Banner type="warning">
|
||||
<strong>Note:</strong>
|
||||
Swap out `pnpm` for your package manager. If you are using NPM, you might need to install using legacy peer deps: `npm i --legacy-peer-deps`.
|
||||
</Banner>
|
||||
|
||||
#### 2 - copy Payload files into your Next.js app folder
|
||||
**Install a Database Adapter**
|
||||
|
||||
Payload requires a [Database Adapter](/docs/database/overview) to connect to your database of choice. Payload works with all types of databases, but the most common are MongoDB and Postgres.
|
||||
|
||||
- To install the [MongoDB Adapter](../database/mongodb), run:
|
||||
```bash
|
||||
pnpm i @payloadcms/db-mongodb
|
||||
```
|
||||
|
||||
- To install the [Postgres Adapter](../database/postgres), run:
|
||||
```bash
|
||||
pnpm i @payloadcms/db-postgres
|
||||
```
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Reminder:</strong>
|
||||
New [Database Adapters](/docs/database/overview) are becoming available every day. Check the docs for the most up-to-date list.
|
||||
</Banner>
|
||||
|
||||
#### 2. Copy Payload files into your Next.js app folder
|
||||
|
||||
Payload installs directly in your Next.js `/app` folder, and you'll need to place some files into that folder for Payload to run.
|
||||
|
||||
The files that Payload needs to have in your `/app` folder do not regenerate, and will never change. Once you slot them in, you never have to revisit them. They are not meant to be edited and simply import Payload dependencies from `@payloadcms/next` for the REST / GraphQL API and Payload admin UI.
|
||||
The files that Payload needs to have in your `/app` folder do not regenerate, and will never change. Once you slot them in, you never have to revisit them. They are not meant to be edited and simply import Payload dependencies from `@payloadcms/next` for the REST / GraphQL API and Admin Panel UI.
|
||||
|
||||
You can copy the Payload `/app` folder files from the Payload blank template on GitHub:
|
||||
|
||||
@@ -56,36 +79,27 @@ 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)
|
||||
```
|
||||
|
||||
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">
|
||||
You may need to copy all of your existing frontend files, including your existing root layout, into its own newly created route group.
|
||||
</Banner>
|
||||
|
||||
Once you have the required Payload files in place in your `/app` folder, you should have something like this:
|
||||
|
||||
```
|
||||
/app
|
||||
-- (payload) // This is the Payload route group
|
||||
-- layout.tsx // Payload's root layout
|
||||
-- admin // The Payload admin UI
|
||||
-- api // Payload's REST / GraphQL handlers
|
||||
-- custom.scss // Define custom SCSS for the Payload admin here
|
||||
-- (my-app) // this is where your existing app goes
|
||||
-- layout.tsx // move your existing root layout here
|
||||
-- page.tsx // your existing home page
|
||||
-- ...etc // whatever else you have
|
||||
```plaintext
|
||||
app/
|
||||
├─ (payload)/
|
||||
├── // Payload files
|
||||
├─ (my-app)/
|
||||
├── // Your app files
|
||||
```
|
||||
|
||||
You can name the `(my-app)` folder anything you want. The name does not matter and will just be used to clarify your directory structure for yourself. Common names might be `(frontend)`, `(app)`, or similar. [Check out the Admin documentation](/docs/beta/admin/overview) for more information.
|
||||
<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](https://nextjs.org/docs/app/building-your-application/routing/route-groups), i.e. `(my-app)`.
|
||||
</Banner>
|
||||
|
||||
#### 3 - add the Payload plugin to your Next.js config
|
||||
You can name the `(my-app)` folder anything you want. The name does not matter and will just be used to clarify your directory structure for yourself. Common names might be `(frontend)`, `(app)`, or similar. [More details](../admin/overview).
|
||||
|
||||
Payload has a plugin that it uses to ensure Next.js compatibility with some of the packages Payload relies on, like `mongodb` or `drizzle-kit`.
|
||||
#### 3. Add the Payload Plugin to your Next.js config
|
||||
|
||||
You need to import the `withPayload` plugin in your `next.config.js` file and wrap your config with it.
|
||||
Payload has a Next.js plugin that it uses to ensure compatibility with some of the packages Payload relies on, like `mongodb` or `drizzle-kit`.
|
||||
|
||||
Here's an example of what your Next.js config should look like after you've imported the Payload plugin:
|
||||
To add the Payload Plugin, use `withPayload` in your `next.config.js`:
|
||||
|
||||
```js
|
||||
import { withPayload } from '@payloadcms/next/withPayload'
|
||||
@@ -100,12 +114,15 @@ const nextConfig = {
|
||||
|
||||
// Make sure you wrap your `nextConfig`
|
||||
// with the `withPayload` plugin
|
||||
export default withPayload(nextConfig)
|
||||
export default withPayload(nextConfig) // highlight-line
|
||||
```
|
||||
|
||||
**Important:** Payload is a fully ESM project, and that means the `withPayload` function is an EcmaScript module.
|
||||
<Banner type="warning">
|
||||
<strong>Important:</strong>
|
||||
Payload is a fully ESM project, and that means the `withPayload` function is an ECMAScript module.
|
||||
</Banner>
|
||||
|
||||
To import it, you need to make sure your `next.config` file is set up to use ESM.
|
||||
To import the Payload Plugin, you need to make sure your `next.config` file is set up to use ESM.
|
||||
|
||||
You can do this in one of two ways:
|
||||
|
||||
@@ -114,11 +131,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.
|
||||
|
||||
#### 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 [Payload Config](../configuration/overview). Generally the Payload Config is located at the root of your repository, or next to your `/app` folder, and is named `payload.config.ts`.
|
||||
|
||||
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:
|
||||
Here's what Payload needs at a bare minimum:
|
||||
|
||||
```ts
|
||||
import sharp from 'sharp'
|
||||
@@ -135,13 +152,11 @@ export default buildConfig({
|
||||
|
||||
// Your Payload secret - should be a complex and secure string, unguessable
|
||||
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
|
||||
db: mongooseAdapter({
|
||||
url: process.env.DATABASE_URI || '',
|
||||
}),
|
||||
|
||||
// If you want to resize images, crop, set focal point, etc.
|
||||
// make sure to install it and pass it to the config.
|
||||
// This is optional - if you don't need to do these things,
|
||||
@@ -152,7 +167,7 @@ export default buildConfig({
|
||||
|
||||
Although this is just the bare minimum config, there are _many_ more options that you can control here. To reference the full config and all of its options, [click here](/docs/configuration/overview).
|
||||
|
||||
Once you have your config created, update your `tsconfig` to include a `path` that points to your config:
|
||||
Once you have a Payload Config, update your `tsconfig` to include a `path` that points to it:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -166,7 +181,7 @@ Once you have your config created, update your `tsconfig` to include a `path` th
|
||||
}
|
||||
```
|
||||
|
||||
#### 5 - fire it up!
|
||||
#### 5. Fire it up!
|
||||
|
||||
After you've gotten this far, it's time to boot up Payload. Start your project in your application's folder to get going. By default, the Next.js dev script is `pnpm dev` (or `npm run dev` if using NPM).
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ Payload started as a headless Content Management System (CMS), but since, we've
|
||||
|
||||
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.
|
||||
|
||||
### As a CMS
|
||||
### Headless CMS
|
||||
|
||||
The biggest barrier in large web projects cited by marketers is engineering. On the flip side, engineers say the opposite. This is a big problem that has yet to be solved even though we have countless CMS options.
|
||||
|
||||
@@ -60,7 +60,7 @@ Get started with Payload as a CMS using our official Website template:
|
||||
npx create-payload-app@latest -t website
|
||||
```
|
||||
|
||||
### For enterprise tools
|
||||
### Enterprise Tool
|
||||
|
||||
When a large organization starts up a new software initiative, there's a lot of plumbing to take care of.
|
||||
|
||||
@@ -83,7 +83,7 @@ Generally, the best place to start for a new enterprise tool is with a blank can
|
||||
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.
|
||||
|
||||
@@ -99,7 +99,7 @@ Payload's official Ecommerce template gives you everything you need for a storef
|
||||
npx create-payload-app@latest -t ecommerce
|
||||
```
|
||||
|
||||
### Digital asset management
|
||||
### Digital Asset Management
|
||||
|
||||
Payload's API-first tagging, sorting, and querying engine lends itself perfectly to all types of content that a CMS might ordinarily store, but these strong fundamentals also make it a formidable Digital Asset Management (DAM) tool as well.
|
||||
|
||||
@@ -109,6 +109,10 @@ Payload flattens CMS and DAM into a single tool that makes no compromises on eit
|
||||
|
||||
[Click here](https://payloadcms.com/use-cases/digital-asset-management) for more information on how to get started with Payload as a DAM.
|
||||
|
||||
## Choosing a Framework
|
||||
|
||||
Payload is a great choice for applications of all sizes and types, but it might not be the right choice for every project. Here are some guidelines to help you decide if Payload is the right choice for your project.
|
||||
|
||||
### When Payload might be for you
|
||||
|
||||
- If data ownership and privacy are important to you, and you don't want to allow another proprietary SaaS vendor to host and own your data
|
||||
|
||||
@@ -67,7 +67,7 @@ Instead, use the new `beforeDuplicate` field-level hook which take the usual fie
|
||||
```tsx
|
||||
// ❌ Before
|
||||
// file: collections/Posts.ts
|
||||
import type { CollectionConfig } from 'payload/types'
|
||||
import type { CollectionConfig } from 'payload'
|
||||
|
||||
export const PostsCollection: CollectionConfig = {
|
||||
slug: 'posts',
|
||||
@@ -708,11 +708,11 @@ This was changed for improved semantics. If you were previously importing this t
|
||||
```tsx
|
||||
// ❌ Before
|
||||
|
||||
import type { Fields } from 'payload/types'
|
||||
import type { Fields } from 'payload'
|
||||
|
||||
// ✅ After
|
||||
|
||||
import type { FormState } from 'payload/types'
|
||||
import type { FormState } from 'payload'
|
||||
```
|
||||
|
||||
16. The `useDocumentInfo` hook no longer returns a `SanizitedCollectionConfig` or `SanitizedGlobalConfig`:
|
||||
|
||||
@@ -44,7 +44,7 @@ pnpm add @payloadcms/plugin-form-builder
|
||||
In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { formBuilderPlugin } from '@payloadcms/plugin-form-builder'
|
||||
|
||||
const config = buildConfig({
|
||||
|
||||
@@ -57,7 +57,7 @@ In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/conf
|
||||
with [options](#options):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { nestedDocsPlugin } from '@payloadcms/plugin-nested-docs'
|
||||
|
||||
const config = buildConfig({
|
||||
@@ -177,7 +177,7 @@ You can also extend the built-in `parent` and `breadcrumbs` fields per collectio
|
||||
and `createBreadcrumbField` methods. They will merge your customizations overtop the plugin's base field configurations.
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
import { createParentField } from '@payloadcms/plugin-nested-docs/fields'
|
||||
import { createBreadcrumbsField } from '@payloadcms/plugin-nested-docs/fields'
|
||||
|
||||
|
||||
@@ -6,11 +6,26 @@ desc: Plugins provide a great way to modularize Payload functionalities into eas
|
||||
keywords: plugins, config, configuration, extensions, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
||||
---
|
||||
|
||||
Payload Plugins take full advantage of the modularity of the [Payload Config](../configuration/overview), allowing developers to easily extend Payload's core functionality in a precise and granular way. This pattern allows developers to easily inject custom—sometimes complex—functionality into Payload apps from a very small touch-point.
|
||||
Payload Plugins take full advantage of the modularity of the [Payload Config](../configuration/overview), allowing developers to extend Payload's core functionality in a precise and granular way. This pattern allows developers to easily inject custom—sometimes complex—functionality into Payload apps from a very small touch-point.
|
||||
|
||||
There are many [Official Plugins](#official-plugins) available that solve for some of the most common uses cases, such as the [Form Builder Plugin](./seo) or [SEO Plugin](./seo). There are also [Community Plugins](#community-plugins) available, maintained entirely by contributing members. To extend Payload's functionality in some other way, you can easily [build your own plugin](./build-your-own).
|
||||
|
||||
Writing plugins is no more complex than writing regular JavaScript. If you know the basic concept of [callback functions](https://developer.mozilla.org/en-US/docs/Glossary/Callback_function) or how [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) works, and are up to speed with Payload concepts, then writing a plugin will be a breeze.
|
||||
To configure Plugins, use the `plugins` property in your [Payload Config](../configuration/overview):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
const config = buildConfig({
|
||||
// ...
|
||||
// highlight-start
|
||||
plugins: [
|
||||
// Add Plugins here
|
||||
],
|
||||
// highlight-end
|
||||
})
|
||||
```
|
||||
|
||||
Writing Plugins is no more complex than writing regular JavaScript. If you know the basic concept of [callback functions](https://developer.mozilla.org/en-US/docs/Glossary/Callback_function) or how [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) works, and are up to speed with Payload concepts, then writing a plugin will be a breeze.
|
||||
|
||||
<Banner type="success">
|
||||
Because we rely on a simple config-based structure, Payload Plugins simply take in an
|
||||
@@ -59,32 +74,19 @@ Some plugins have become so widely used that they are adopted as an [Official Pl
|
||||
For maintainers building plugins for others to use, please add the `payload-plugin` topic on [GitHub](https://github.com/topics/payload-plugin) to help others find it.
|
||||
</Banner>
|
||||
|
||||
## Installing Plugins
|
||||
## Example
|
||||
|
||||
The base [Payload Config](../configuration/overview) allows for a `plugins` property which takes an `array` of [Plugin Configs](./build-your-own).
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
// note: these plugins are not real (yet?)
|
||||
import addLastModified from 'payload-add-last-modified'
|
||||
import passwordProtect from 'payload-password-protect'
|
||||
import { buildConfig } from 'payload'
|
||||
import { addLastModified } from './addLastModified.ts'
|
||||
|
||||
const config = buildConfig({
|
||||
// ...
|
||||
// highlight-start
|
||||
plugins: [
|
||||
// Many plugins require options to be passed.
|
||||
// In the following example, we call the function
|
||||
// and pass it options accordingly
|
||||
passwordProtect(['pages']),
|
||||
|
||||
// This plugin takes no options and just
|
||||
// needs to be passed directly
|
||||
addLastModified,
|
||||
|
||||
// ..
|
||||
// To understand how to use the plugins you're interested in,
|
||||
// consult their corresponding documentation
|
||||
],
|
||||
// highlight-end
|
||||
})
|
||||
@@ -97,9 +99,9 @@ const config = buildConfig({
|
||||
Here is an example what the `addLastModified` plugin from above might look like. It adds a `lastModifiedBy` field to all Payload collections. For full details, see [how to build your own plugin](./build-your-own).
|
||||
|
||||
```ts
|
||||
import { Config, Plugin } from 'payload/config'
|
||||
import { Config, Plugin } from 'payload'
|
||||
|
||||
const addLastModified: Plugin = (incomingConfig: Config): Config => {
|
||||
export const addLastModified: Plugin = (incomingConfig: Config): Config => {
|
||||
// Find all incoming auth-enabled collections
|
||||
// so we can create a lastModifiedBy relationship field
|
||||
// to all auth collections
|
||||
@@ -142,6 +144,9 @@ const addLastModified: Plugin = (incomingConfig: Config): Config => {
|
||||
|
||||
return config
|
||||
}
|
||||
|
||||
export default addLastModified
|
||||
```
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Reminder:</strong>
|
||||
See [how to build your own plugin](./build-your-own) for a more in-depth explication on how create your own Payload Plugin.
|
||||
</Banner>
|
||||
|
||||
@@ -40,7 +40,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
|
||||
In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { redirectsPlugin } from '@payloadcms/plugin-redirects'
|
||||
|
||||
const config = buildConfig({
|
||||
|
||||
@@ -47,7 +47,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
|
||||
In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
|
||||
|
||||
```js
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { searchPlugin } from '@payloadcms/plugin-search'
|
||||
|
||||
const config = buildConfig({
|
||||
|
||||
@@ -47,7 +47,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
|
||||
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
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { sentryPlugin } from '@payloadcms/plugin-sentry'
|
||||
import { Pages, Media } from './collections'
|
||||
|
||||
@@ -96,7 +96,7 @@ To see all options available, visit the [Sentry Docs](https://docs.sentry.io/pla
|
||||
Configure any of these options by passing them to the plugin:
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { sentry } from '@payloadcms/plugin-sentry'
|
||||
import { Pages, Media } from './collections'
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
|
||||
In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config';
|
||||
import { buildConfig } from 'payload';
|
||||
import { seoPlugin } from '@payloadcms/plugin-seo';
|
||||
|
||||
const config = buildConfig({
|
||||
|
||||
@@ -47,7 +47,7 @@ Install the plugin using any JavaScript package manager like [Yarn](https://yarn
|
||||
In the `plugins` array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { stripePlugin } from '@payloadcms/plugin-stripe'
|
||||
|
||||
const config = buildConfig({
|
||||
@@ -140,7 +140,7 @@ Production:
|
||||
1. Then, handle these events using the `webhooks` portion of this plugin's config:
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import stripePlugin from '@payloadcms/plugin-stripe'
|
||||
|
||||
const config = buildConfig({
|
||||
@@ -239,7 +239,7 @@ This option will setup a basic sync between Payload collections and Stripe resou
|
||||
</Banner>
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import stripePlugin from '@payloadcms/plugin-stripe'
|
||||
|
||||
const config = buildConfig({
|
||||
|
||||
@@ -21,7 +21,7 @@ Payload provides an extremely granular querying language through all APIs. Each
|
||||
For example, say you have a collection as follows:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Post: CollectionConfig = {
|
||||
slug: 'posts',
|
||||
|
||||
@@ -585,7 +585,7 @@ Each endpoint object needs to have:
|
||||
Example:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
// a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
|
||||
export const Orders: CollectionConfig = {
|
||||
|
||||
@@ -19,7 +19,7 @@ npm install --save @payloadcms/richtext-slate
|
||||
After installation, you can pass it to your top-level Payload Config:
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { slateEditor } from '@payloadcms/richtext-slate'
|
||||
|
||||
export default buildConfig({
|
||||
@@ -34,7 +34,7 @@ export default buildConfig({
|
||||
And here's an example for how to install the Slate editor on a field-by-field basis, while customizing its options:
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
import { slateEditor } from '@payloadcms/richtext-slate'
|
||||
|
||||
export const Pages: CollectionConfig = {
|
||||
@@ -167,7 +167,7 @@ Specifying custom `Type`s let you extend your custom elements by adding addition
|
||||
`collections/ExampleCollection.ts`
|
||||
|
||||
```ts
|
||||
import type { CollectionConfig } from 'payload/types'
|
||||
import type { CollectionConfig } from 'payload'
|
||||
|
||||
import { slateEditor } from '@payloadcms/richtext-slate'
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ Every Payload Collection can opt-in to supporting Uploads by specifying the `upl
|
||||
</Banner>
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Media: CollectionConfig = {
|
||||
slug: 'media',
|
||||
@@ -113,7 +113,7 @@ Upload options are specifiable on a Collection by Collection basis, you can also
|
||||
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:
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
collections: [
|
||||
@@ -197,7 +197,7 @@ You can specify how Payload retrieves admin thumbnails for your upload-enabled C
|
||||
1. `adminThumbnail` as a **string**, equal to one of your provided image size names.
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Media: CollectionConfig = {
|
||||
slug: 'media',
|
||||
@@ -226,7 +226,7 @@ export const Media: CollectionConfig = {
|
||||
2. `adminThumbnail` as a **function** that takes the document's data and sends back a full URL to load the thumbnail.
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Media: CollectionConfig = {
|
||||
slug: 'media',
|
||||
@@ -247,7 +247,7 @@ Some example values are: `image/*`, `audio/*`, `video/*`, `image/png`, `applicat
|
||||
**Example mimeTypes usage:**
|
||||
|
||||
```ts
|
||||
import { CollectionConfig } from 'payload/types'
|
||||
import { CollectionConfig } from 'payload'
|
||||
|
||||
export const Media: CollectionConfig = {
|
||||
slug: 'media',
|
||||
|
||||
@@ -286,7 +286,7 @@ export interface GeneratedAdapter {
|
||||
```
|
||||
|
||||
```ts
|
||||
import { buildConfig } from 'payload/config'
|
||||
import { buildConfig } from 'payload'
|
||||
import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'
|
||||
|
||||
export default buildConfig({
|
||||
|
||||
Reference in New Issue
Block a user