-
#### Notes
+
- It is recommended to add the test credentials (located in `test/credentials.ts`) to your autofill for `localhost:3000/admin` as this will be required on every nodemon restart. The default credentials are `dev@payloadcms.com` as email and `test` as password.
diff --git a/README.md b/README.md
index 892120d67..5bcbf1f36 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,7 @@
## ☁️ Deploy instantly with Payload Cloud.
+
Create a cloud account, connect your GitHub, and [deploy in minutes](https://payloadcms.com/new).
## 🚀 Get started by self-hosting completely free, forever.
@@ -52,7 +53,9 @@ npx create-payload-app
Alternatively, it only takes about five minutes to [create an app from scratch](https://payloadcms.com/docs/getting-started/installation#from-scratch).
## 🖱️ One-click templates
+
### 🛒 [E-Commerce](https://github.com/payloadcms/payload/tree/master/templates/ecommerce)
+
Eliminate the need to combine Shopify and a CMS, and instead do it all with Payload + Stripe. Best of all, you can extend it as much as you need.
[All Official Templates](https://github.com/orgs/payloadcms/repositories?q=topic%3Apayload-template) · [Community Templates](https://github.com/topics/payload-template)
diff --git a/docs/access-control/collections.mdx b/docs/access-control/collections.mdx
index 9b0969de1..2fa681add 100644
--- a/docs/access-control/collections.mdx
+++ b/docs/access-control/collections.mdx
@@ -10,23 +10,24 @@ You can define Collection-level Access Control within each Collection's `access`
## Available Controls
-| Function | Allows/Denies Access |
-| ------------------------ | -------------------- |
-| **[`create`](#create)** | Used in the `create` operation |
-| **[`read`](#read)** | Used in the `find` and `findByID` operations |
-| **[`update`](#update)** | Used in the `update` operation |
-| **[`delete`](#delete)** | Used in the `delete` operation |
+| Function | Allows/Denies Access |
+| ----------------------- | -------------------------------------------- |
+| **[`create`](#create)** | Used in the `create` operation |
+| **[`read`](#read)** | Used in the `find` and `findByID` operations |
+| **[`update`](#update)** | Used in the `update` operation |
+| **[`delete`](#delete)** | Used in the `delete` operation |
#### Auth-enabled Controls
If a Collection supports [`Authentication`](/docs/authentication/overview), the following Access Controls become available:
-| Function | Allows/Denies Access |
-| ----------------------- | -------------------- |
-| **[`admin`](#admin)** | Used to restrict access to the Payload Admin panel |
+| Function | Allows/Denies Access |
+| ----------------------- | -------------------------------------------------------------- |
+| **[`admin`](#admin)** | Used to restrict access to the Payload Admin panel |
| **[`unlock`](#unlock)** | Used to restrict which users can access the `unlock` operation |
**Example Collection config:**
+
```ts
import { CollectionConfig } from 'payload/types';
@@ -50,10 +51,10 @@ Returns a boolean which allows/denies access to the `create` request.
**Available argument properties:**
-| Option | Description |
-| ---------- | ----------- |
+| Option | Description |
+| ---------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`data`** | The data passed to create the document with. |
+| **`data`** | The data passed to create the document with. |
**Example:**
@@ -77,20 +78,20 @@ Read access functions can return a boolean result or optionally return a [query
**Available argument properties:**
-| Option | Description |
-| --------- | ----------- |
+| Option | Description |
+| --------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`id`** | `id` of document requested, if within `findByID` |
+| **`id`** | `id` of document requested, if within `findByID` |
**Example:**
```ts
-import { Access } from 'payload/config';
+import { Access } from 'payload/config'
const canReadPage: Access = ({ req: { user } }) => {
// allow authenticated users
if (user) {
- return true;
+ return true
}
// using a query constraint, guest users can access when a field named 'isPublic' is set to true
return {
@@ -99,7 +100,7 @@ const canReadPage: Access = ({ req: { user } }) => {
equals: true,
},
}
-};
+}
```
### Update
@@ -108,25 +109,25 @@ Update access functions can return a boolean result or optionally return a [quer
**Available argument properties:**
-| Option | Description |
-| ---------- | ----------- |
+| Option | Description |
+| ---------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`id`** | `id` of document requested to update |
-| **`data`** | The data passed to update the document with |
+| **`id`** | `id` of document requested to update |
+| **`data`** | The data passed to update the document with |
**Example:**
```ts
-import { Access } from 'payload/config';
+import { Access } from 'payload/config'
const canUpdateUser: Access = ({ req: { user }, id }) => {
// allow users with a role of 'admin'
- if (user.roles && user.roles.some(role => role === 'admin')) {
- return true;
+ if (user.roles && user.roles.some((role) => role === 'admin')) {
+ return true
}
// allow any other users to update only oneself
- return user.id === id;
-};
+ return user.id === id
+}
```
### Delete
@@ -135,10 +136,10 @@ Similarly to the Update function, returns a boolean or a [query constraint](/doc
**Available argument properties:**
-| Option | Description |
-| --------- | ----------- |
+| Option | Description |
+| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
-| **`id`** | `id` of document requested to delete |
+| **`id`** | `id` of document requested to delete |
**Example:**
@@ -148,7 +149,7 @@ import { Access } from 'payload/config'
const canDeleteCustomer: Access = async ({ req, id }) => {
if (!id) {
// allow the admin UI to show controls to delete since it is indeterminate without the id
- return true;
+ return true
}
// query another collection using the id
const result = await req.payload.find({
@@ -158,10 +159,10 @@ const canDeleteCustomer: Access = async ({ req, id }) => {
where: {
customer: { equals: id },
},
- });
+ })
- return result.totalDocs === 0;
-};
+ return result.totalDocs === 0
+}
```
### Admin
@@ -170,8 +171,8 @@ If the Collection is [used to access the Payload Admin panel](/docs/admin/overvi
**Available argument properties:**
-| Option | Description |
-| --------- | ----------- |
+| Option | Description |
+| --------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
### Unlock
@@ -180,6 +181,6 @@ Determines which users can [unlock](/docs/authentication/operations#unlock) othe
**Available argument properties:**
-| Option | Description |
-| --------- | ----------- |
+| Option | Description |
+| --------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
diff --git a/docs/access-control/fields.mdx b/docs/access-control/fields.mdx
index 513f140e9..68cc782ed 100644
--- a/docs/access-control/fields.mdx
+++ b/docs/access-control/fields.mdx
@@ -10,13 +10,14 @@ Field Access Control is specified with functions inside a field's config. All fi
## Available Controls
-| Function | Purpose |
-| ------------------------ | ------- |
-| **[`create`](#create)** | Allows or denies the ability to set a field's value when creating a new document |
-| **[`read`](#read)** | Allows or denies the ability to read a field's value |
-| **[`update`](#update)** | Allows or denies the ability to update a field's value |
+| Function | Purpose |
+| ----------------------- | -------------------------------------------------------------------------------- |
+| **[`create`](#create)** | Allows or denies the ability to set a field's value when creating a new document |
+| **[`read`](#read)** | Allows or denies the ability to read a field's value |
+| **[`update`](#update)** | Allows or denies the ability to update a field's value |
**Example Collection config:**
+
```ts
import { CollectionConfig } from 'payload/types';
@@ -44,11 +45,11 @@ Returns a boolean which allows or denies the ability to set a field's value when
**Available argument properties:**
-| Option | Description |
-| ----------------- | ----------- |
+| Option | Description |
+| ----------------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`data`** | The full data passed to create the document. |
-| **`siblingData`** | Immediately adjacent field data passed to create the document. |
+| **`data`** | The full data passed to create the document. |
+| **`siblingData`** | Immediately adjacent field data passed to create the document. |
### Read
@@ -56,12 +57,12 @@ Returns a boolean which allows or denies the ability to read a field's value. If
**Available argument properties:**
-| Option | Description |
-| ----------------- | ----------- |
+| Option | Description |
+| ----------------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`id`** | `id` of the document being read |
-| **`doc`** | The full document data. |
-| **`siblingData`** | Immediately adjacent field data of the document being read. |
+| **`id`** | `id` of the document being read |
+| **`doc`** | The full document data. |
+| **`siblingData`** | Immediately adjacent field data of the document being read. |
### Update
@@ -71,10 +72,10 @@ If `false` is returned and you attempt to update the field's value, the operatio
**Available argument properties:**
-| Option | Description |
-| ----------------- | ----------- |
+| Option | Description |
+| ----------------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`id`** | `id` of the document being updated |
-| **`data`** | The full data passed to update the document. |
-| **`siblingData`** | Immediately adjacent field data passed to update the document with. |
-| **`doc`** | The full document data, before the update is applied. |
+| **`id`** | `id` of the document being updated |
+| **`data`** | The full data passed to update the document. |
+| **`siblingData`** | Immediately adjacent field data passed to update the document with. |
+| **`doc`** | The full document data, before the update is applied. |
diff --git a/docs/access-control/globals.mdx b/docs/access-control/globals.mdx
index bdb73b9fa..cd8f8673e 100644
--- a/docs/access-control/globals.mdx
+++ b/docs/access-control/globals.mdx
@@ -8,30 +8,35 @@ keywords: globals, access control, permissions, documentation, Content Managemen
You can define Global-level Access Control within each Global's `access` property. All Access Control functions accept one `args` argument.
-**Available argument properties:
+\*\*Available argument properties:
## Available Controls
-| Function | Allows/Denies Access |
-| ------------------------ | -------------------- |
-| **[`read`](#read)** | Used in the `findOne` Global operation |
-| **[`update`](#update)** | Used in the `update` Global operation |
+| Function | Allows/Denies Access |
+| ----------------------- | -------------------------------------- |
+| **[`read`](#read)** | Used in the `findOne` Global operation |
+| **[`update`](#update)** | Used in the `update` Global operation |
**Example Global config:**
+
```ts
-import { GlobalConfig } from 'payload/types';
+import { GlobalConfig } from 'payload/types'
const Header: GlobalConfig = {
- slug: "header",
+ slug: 'header',
// highlight-start
access: {
- read: ({ req: { user } }) => { /* */ },
- update: ({ req: { user } }) => { /* */ },
+ read: ({ req: { user } }) => {
+ /* */
+ },
+ update: ({ req: { user } }) => {
+ /* */
+ },
},
// highlight-end
-};
+}
-export default Header;
+export default Header
```
### Read
@@ -40,8 +45,8 @@ Returns a boolean result or optionally a [query constraint](/docs/queries/overvi
**Available argument properties:**
-| Option | Description |
-| --------- | ----------- |
+| Option | Description |
+| --------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
### Update
@@ -50,7 +55,7 @@ Returns a boolean result or optionally a [query constraint](/docs/queries/overvi
**Available argument properties:**
-| Option | Description |
-| ---------- | ----------- |
+| Option | Description |
+| ---------- | -------------------------------------------------------------------------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
-| **`data`** | The data passed to update the global with. |
+| **`data`** | The data passed to update the global with. |
diff --git a/docs/access-control/overview.mdx b/docs/access-control/overview.mdx
index 7d5a51106..03d8596a2 100644
--- a/docs/access-control/overview.mdx
+++ b/docs/access-control/overview.mdx
@@ -8,10 +8,7 @@ keywords: overview, access control, permissions, documentation, Content Manageme
Access control within Payload is extremely powerful while remaining easy and intuitive to manage. Declaring who should have access to what documents is no more complex than writing a simple JavaScript function that either returns a `boolean` or a [`query`](/docs/queries/overview) constraint to restrict which documents users can interact with.
-- In the Local API, all Access Control functions are skipped by default, allowing your server to do whatever it needs. But, you can opt back in by setting the option overrideAccess to false. + Note: +
+ In the Local API, all Access Control functions are skipped by default, allowing your server to do + whatever it needs. But, you can opt back in by setting the option + overrideAccess + {' '} + to false.
- Access control functions are utilized in two places. It's important to understand how and when your access control is executed. + Note: +
+ Access control functions are utilized in two places. It's important to understand how and when + your access control is executed.
- When your access control functions are executed via the access operation, the id and data arguments will be undefined, because Payload is executing your functions without referencing a specific document. + Important: +
+ When your access control functions are executed via the access operation, the{' '} + id and data arguments will be undefined, + because Payload is executing your functions without referencing a specific document.
- Custom components will automatically be provided with all props that the default component would accept. + Tip: +
+ Custom components will automatically be provided with all props that the default component would + accept.
- Some text before the default list view component. If you just want to do - that, you can also use the admin.components.list.BeforeList hook + Some text before the default list view component. If you just want to do that, you can also + use the admin.components.list.BeforeList hook
- Don't see a built-in field type that you need? Build it! Using a combination - of custom validation and custom components, you can override the entirety of - how a component functions within the admin panel and effectively create your - own field type. + Don't see a built-in field type that you need? Build it! Using a combination of custom validation + and custom components, you can override the entirety of how a component functions within the admin + panel and effectively create your own field type.
- It's up to you to secure your custom routes. If your route requires a user to - be logged in or to have certain access rights, you should handle that within - your route component yourself. + It's up to you to secure your custom routes. If your route requires a user to be logged in or to + have certain access rights, you should handle that within your route component yourself. #### Example @@ -311,8 +303,8 @@ To see how to pass in your custom views to create custom routes of your own, tak As your admin customizations gets more complex you may want to share state between fields or other components. You can add custom providers to do add your own context to any Payload app for use in other custom components within the admin panel. Within your config add `admin.components.providers`, these can be used to share context or provide other custom functionality. Read the [React context](https://reactjs.org/docs/context.html) docs to learn more.
-
-
- {t("key", { variable: "value" })} -
- {t("namespace2:key", { variable: "value" })} +
- {t('key', { variable: 'value' })} +
- {t('namespace2:key', { variable: 'value' })}
- {i18n.language}
- This hook is optimized to avoid causing rerenders when fields change, and as such, its `fields` property will be out of date. You should only leverage this hook if you need to perform actions against the form in response to your users' actions. Do not rely on its returned "fields" as being up-to-date. They will be removed from this hook's response in an upcoming version. + Warning: +
+ This hook is optimized to avoid causing rerenders when fields change, and as such, its `fields` + property will be out of date. You should only leverage this hook if you need to perform actions + against the form in response to your users' actions. Do not rely on its returned "fields" as being + up-to-date. They will be removed from this hook's response in an upcoming version.
+{' '} -
-{`import { useForm } from "payload/components/forms";
+
+
+{' '}
+
+
+ {`import { useForm } from "payload/components/forms";
export const CustomArrayManager = () => {
const { addFieldRow } = useForm()
@@ -385,7 +392,7 @@ export const CustomArrayManager = () => {
)
}`}
-
+
An example config to go along with the custom component
@@ -456,10 +463,14 @@ export const CustomArrayManager = () => {
]}
/>
-
+{' '}
-
-{`import { useForm } from "payload/components/forms";
+
+
+{' '}
+
+
+ {`import { useForm } from "payload/components/forms";
export const CustomArrayManager = () => {
const { removeFieldRow } = useForm()
@@ -478,7 +489,7 @@ export const CustomArrayManager = () => {
)
}`}
-
+
An example config to go along with the custom component
@@ -557,10 +568,14 @@ export const CustomArrayManager = () => {
]}
/>
-
+{' '}
-
-{`import { useForm } from "payload/components/forms";
+
+
+{' '}
+
+
+ {`import { useForm } from "payload/components/forms";
export const CustomArrayManager = () => {
const { replaceFieldRow } = useForm()
@@ -584,7 +599,7 @@ export const CustomArrayManager = () => {
)
}`}
-
+
An example config to go along with the custom component
@@ -624,40 +639,40 @@ export const CustomArrayManager = () => {
The `useDocumentInfo` hook provides lots of information about the document currently being edited, including the following:
-| Property | Description |
-|---------------------------|--------------------------------------------------------------------------------------------------------------------| |
-| **`collection`** | If the doc is a collection, its collection config will be returned |
-| **`global`** | If the doc is a global, its global config will be returned |
-| **`id`** | If the doc is a collection, its ID will be returned |
-| **`preferencesKey`** | The `preferences` key to use when interacting with document-level user preferences |
-| **`versions`** | Versions of the current doc |
-| **`unpublishedVersions`** | Unpublished versions of the current doc |
-| **`publishedDoc`** | The currently published version of the doc being edited |
-| **`getVersions`** | Method to trigger the retrieval of document versions |
-| **`docPermissions`** | The current documents permissions. Collection document permissions fallback when no id is present (i.e. on create) |
-| **`getDocPermissions`** | Method to trigger the retrieval of document level permissions |
+| Property | Description |
+|---------------------------|--------------------------------------------------------------------------------------------------------------------| |
+| **`collection`** | If the doc is a collection, its collection config will be returned |
+| **`global`** | If the doc is a global, its global config will be returned |
+| **`id`** | If the doc is a collection, its ID will be returned |
+| **`preferencesKey`** | The `preferences` key to use when interacting with document-level user preferences |
+| **`versions`** | Versions of the current doc |
+| **`unpublishedVersions`** | Unpublished versions of the current doc |
+| **`publishedDoc`** | The currently published version of the doc being edited |
+| **`getVersions`** | Method to trigger the retrieval of document versions |
+| **`docPermissions`** | The current documents permissions. Collection document permissions fallback when no id is present (i.e. on create) |
+| **`getDocPermissions`** | Method to trigger the retrieval of document level permissions |
**Example:**
```tsx
-import { useDocumentInfo } from 'payload/components/utilities';
+import { useDocumentInfo } from 'payload/components/utilities'
const LinkFromCategoryToPosts: React.FC = () => {
// highlight-start
- const { id } = useDocumentInfo();
+ const { id } = useDocumentInfo()
// highlight-end
// id will be undefined on the create form
if (!id) {
- return null;
+ return null
}
return (
-
+
View posts
)
-};
+}
```
### useLocale
@@ -665,22 +680,20 @@ const LinkFromCategoryToPosts: React.FC = () => {
In any custom component you can get the selected locale object with the `useLocale` hook. `useLocale`gives you the full locale object, consisting of a `label`, `rtl`(right-to-left) property, and then `code`. Here is a simple example:
```tsx
-import { useLocale } from 'payload/components/utilities';
+import { useLocale } from 'payload/components/utilities'
const Greeting: React.FC = () => {
// highlight-start
- const locale = useLocale();
+ const locale = useLocale()
// highlight-end
const trans = {
en: 'Hello',
es: 'Hola',
- };
+ }
- return (
- { trans[locale.code] }
- );
-};
+ return {trans[locale.code]}
+}
```
### useAuth
@@ -688,7 +701,7 @@ const Greeting: React.FC = () => {
Useful to retrieve info about the currently logged in user as well as methods for interacting with it. It sends back an object with the following properties:
| Property | Description |
-|--------------------------|-----------------------------------------------------------------------------------------|
+| ------------------------ | --------------------------------------------------------------------------------------- |
| **`user`** | The currently logged in user |
| **`logOut`** | A method to log out the currently logged in user |
| **`refreshCookie`** | A method to trigger the silent refreshing of a user's auth token |
@@ -698,18 +711,16 @@ Useful to retrieve info about the currently logged in user as well as methods fo
| **`permissions`** | The permissions of the current user |
```tsx
-import { useAuth } from 'payload/components/utilities';
-import { User } from '../payload-types.ts';
+import { useAuth } from 'payload/components/utilities'
+import { User } from '../payload-types.ts'
const Greeting: React.FC = () => {
// highlight-start
- const { user } = useAuth();
+ const { user } = useAuth()
// highlight-end
- return (
- Hi, {user.email}!
- );
-};
+ return Hi, {user.email}!
+}
```
### useConfig
@@ -717,17 +728,15 @@ const Greeting: React.FC = () => {
Used to easily fetch the full Payload config.
```tsx
-import { useConfig } from 'payload/components/utilities';
+import { useConfig } from 'payload/components/utilities'
const MyComponent: React.FC = () => {
// highlight-start
- const config = useConfig();
+ const config = useConfig()
// highlight-end
- return (
- {config.serverURL}
- );
-};
+ return {config.serverURL}
+}
```
### useEditDepth
@@ -735,16 +744,14 @@ const MyComponent: React.FC = () => {
Sends back how many editing levels "deep" the current component is. Edit depth is relevant while adding new documents / editing documents in modal windows and other cases.
```tsx
-import { useEditDepth } from 'payload/components/utilities';
+import { useEditDepth } from 'payload/components/utilities'
const MyComponent: React.FC = () => {
// highlight-start
- const editDepth = useEditDepth();
+ const editDepth = useEditDepth()
// highlight-end
- return (
- My component is {editDepth} levels deep
- )
+ return My component is {editDepth} levels deep
}
```
diff --git a/docs/admin/overview.mdx b/docs/admin/overview.mdx
index c042974b0..420d9ee74 100644
--- a/docs/admin/overview.mdx
+++ b/docs/admin/overview.mdx
@@ -11,9 +11,9 @@ Payload dynamically generates a beautiful, fully functional React admin panel to
The Payload Admin panel is built with Webpack, code-split, highly performant (even with 100+ fields), and written fully in TypeScript.
- The Admin panel is meant to be simple enough to give you a starting point but
- not bring too much complexity, so that you can easily customize it to suit the
- needs of your application and your editors.
+ The Admin panel is meant to be simple enough to give you a starting point but not bring too much
+ complexity, so that you can easily customize it to suit the needs of your application and your
+ editors.
@@ -25,7 +25,7 @@ _Screenshot of the Admin panel while editing a document from an example `AllFiel
All options for the Admin panel are defined in your base Payload config file.
| Option | Description |
-|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user` | The `slug` of a Collection that you want be used to log in to the Admin dashboard. [More](/docs/admin/overview#the-admin-user-collection) |
| `buildPath` | Specify an absolute path for where to store the built Admin panel bundle used in production. Defaults to `path.resolve(process.cwd(), 'build')`. |
| `meta` | Base meta data to use for the Admin panel. Included properties are `titleSuffix`, `ogImage`, and `favicon`. |
@@ -55,13 +55,13 @@ To specify which Collection to use to log in to the Admin panel, pass the `admin
`payload.config.js`:
```ts
-import { buildConfig } from "payload/config";
+import { buildConfig } from 'payload/config'
const config = buildConfig({
admin: {
- user: "admins", // highlight-line
+ user: 'admins', // highlight-line
},
-});
+})
```
By default, if you have not specified a Collection, Payload will automatically provide you with a `User` Collection which will be used to access the Admin panel. You can customize or override the fields and settings of the default `User` Collection by passing your own collection using `users` as its `slug` to Payload. When this is done, Payload will use your provided `User` Collection instead of its default version.
diff --git a/docs/admin/preferences.mdx b/docs/admin/preferences.mdx
index 4343acde6..b4f8ce491 100644
--- a/docs/admin/preferences.mdx
+++ b/docs/admin/preferences.mdx
@@ -15,8 +15,10 @@ Out of the box, Payload handles the persistence of your users' preferences in a
1. The "collapsed" state of blocks, on a document level, as users edit or interact with documents
- Important:
- All preferences are stored on an individual user basis. Payload automatically recognizes the user that is reading or setting a preference via all provided authentication methods.
+ Important:
+
+ All preferences are stored on an individual user basis. Payload automatically recognizes the user
+ that is reading or setting a preference via all provided authentication methods.
### Use cases
@@ -33,7 +35,7 @@ This API is used significantly for internal operations of the Admin panel, as me
Payload automatically creates an internally used `payload-preferences` collection that stores user preferences. Each document in the `payload-preferences` collection contains the following shape:
| Key | Value |
-|-------------------|-------------------------------------------------------------------|
+| ----------------- | ----------------------------------------------------------------- |
| `id` | A unique ID for each preference stored. |
| `key` | A unique `key` that corresponds to the preference. |
| `user.value` | The ID of the `user` that is storing its preference. |
diff --git a/docs/admin/webpack.mdx b/docs/admin/webpack.mdx
index ddfa1599f..5e87c4f28 100644
--- a/docs/admin/webpack.mdx
+++ b/docs/admin/webpack.mdx
@@ -11,20 +11,21 @@ Payload uses Webpack 5 to build the Admin panel. It comes with support for many
To extend the Webpack config, add the `webpack` key to your base Payload config, and provide a function that accepts the default Webpack config as its only argument:
`payload.config.ts`
+
```ts
-import { buildConfig } from 'payload/config';
+import { buildConfig } from 'payload/config'
export default buildConfig({
- admin: {
- // highlight-start
- webpack: (config) => {
- // Do something with the config here
+ admin: {
+ // highlight-start
+ webpack: (config) => {
+ // Do something with the config here
- return config;
- }
- // highlight-end
- }
-});
+ return config
+ },
+ // highlight-end
+ },
+})
```
### Aliasing server-only modules
@@ -43,73 +44,84 @@ Examples of **non** browser-friendly packages:
You may rely on server-only packages such as the above to perform logic in access control functions, hooks, and other contexts (which is great!) but when you boot up your Payload app and try to view it in the browser, you'll likely run into missing dependency issues or other general incompatibilities.
- Tip:
- To avoid problems with server code making it to your Webpack bundle, you can use the alias Webpack feature to tell Webpack to avoid importing the modules you want to restrict to server-only.
+ Tip:
+
+ To avoid problems with server code making it to your Webpack bundle, you can use the{' '}
+ alias Webpack feature to tell Webpack to avoid importing the modules you want to
+ restrict to server-only.
-For example, let's say that you have a Collection called `Subscriptions` which relies on Stripe:
+
+ For example, let's say that you have a Collection called `Subscriptions` which relies on Stripe:
+
-
+
+
`collections/Subscriptions/index.js`
+
```ts
-import { CollectionConfig } from 'payload/types';
-import createStripeSubscription from './hooks/createStripeSubscription';
+import { CollectionConfig } from 'payload/types'
+import createStripeSubscription from './hooks/createStripeSubscription'
export const Subscription: CollectionConfig = {
- slug: 'subscriptions',
- hooks: {
- beforeChange: [
- createStripeSubscription,
- ]
- },
- fields: [
- {
- name: 'stripeSubscriptionID',
- type: 'text',
- required: true,
- }
- ]
-};
+ slug: 'subscriptions',
+ hooks: {
+ beforeChange: [createStripeSubscription],
+ },
+ fields: [
+ {
+ name: 'stripeSubscriptionID',
+ type: 'text',
+ required: true,
+ },
+ ],
+}
```
The collection above features a `beforeChange` hook that creates a Stripe subscription whenever a Subscription document is created in Payload.
That hook might look something like this:
-
+
+
`collections/Subscriptions/hooks/createStripeSubscription.js`
-```js
-import Stripe from 'stripe';
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
+```js
+import Stripe from 'stripe'
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)
const createStripeSubscription = async ({ data, operation }) => {
- if (operation === 'create') {
- const dataWithStripeID = {...data};
+ if (operation === 'create') {
+ const dataWithStripeID = { ...data }
- // use Stripe to create a Stripe subscription
- const subscription = await stripe.subscriptions.create({
- // Configure the subscription accordingly
- });
+ // use Stripe to create a Stripe subscription
+ const subscription = await stripe.subscriptions.create({
+ // Configure the subscription accordingly
+ })
- // Automatically add the Stripe subscription ID
- // to the data that will be saved to this Subscription doc
- dataWithStripeID.stripeSubscriptionID = subscription.id;
+ // Automatically add the Stripe subscription ID
+ // to the data that will be saved to this Subscription doc
+ dataWithStripeID.stripeSubscriptionID = subscription.id
return dataWithStripeID
- }
+ }
- return data;
+ return data
}
-export default createStripeSubscription;
+export default createStripeSubscription
```
- Warning:
- The above code is NOT production-ready and should not be referenced to create Stripe subscriptions. Although creating a beforeChange hook is a completely valid spot to do things like create subscriptions, the code above is incomplete and insecure, meant for explanation purposes only.
+ Warning:
+
+ The above code is NOT production-ready and should not be referenced to create Stripe
+ subscriptions. Although creating a beforeChange hook is a completely valid spot to do things like
+ create subscriptions, the code above is incomplete and insecure, meant for explanation purposes
+ only.
**As-is, this collection will prevent your Admin panel from bundling or loading correctly, because Stripe relies on some Node-only packages.**
@@ -117,52 +129,61 @@ export default createStripeSubscription;
To remedy this issue you can extend the Payload Webpack config to alias your entire `createStripeSubscription` hook to a separate, empty mock file.
Example in `payload.config.js`:
-```js
-import { buildConfig } from 'payload/config';
-import path from 'path';
-import Subscription from './collections/Subscription';
-const createStripeSubscriptionPath = path.resolve(__dirname, 'collections/Subscription/hooks/createStripeSubscription.js');
-const mockModulePath = path.resolve(__dirname, 'mocks/emptyObject.js');
+```js
+import { buildConfig } from 'payload/config'
+import path from 'path'
+import Subscription from './collections/Subscription'
+
+const createStripeSubscriptionPath = path.resolve(
+ __dirname,
+ 'collections/Subscription/hooks/createStripeSubscription.js',
+)
+const mockModulePath = path.resolve(__dirname, 'mocks/emptyObject.js')
export default buildConfig({
- collections: [
- Subscription
- ],
- admin: {
- webpack: (config) => ({
- ...config,
- resolve: {
- ...config.resolve,
- alias: {
- ...config.resolve.alias,
- [createStripeSubscriptionPath]: mockModulePath,
- }
- }
- })
- }
-});
+ collections: [Subscription],
+ admin: {
+ webpack: (config) => ({
+ ...config,
+ resolve: {
+ ...config.resolve,
+ alias: {
+ ...config.resolve.alias,
+ [createStripeSubscriptionPath]: mockModulePath,
+ },
+ },
+ }),
+ },
+})
```
The above code will alias the file at path `createStripeSubscriptionPath` to a mocked module, which might look like this:
`mocks/emptyObject.js`
+
```js
-export default {};
+export default {}
```
Now, when Webpack sees that you're attempting to import your `createStripeSubscriptionPath` file, it'll disregard that actual file and load your mock file instead. Not only will your Admin panel now bundle successfully, you will have optimized its filesize by removing unnecessary code! And you might have learned something about Webpack, too.
- Tip:
- If changes to your Webpack aliases are not surfacing, they might be [cached](https://webpack.js.org/configuration/cache/) in `node_modules/.cache/webpack`. Try deleting that folder and restarting your server.
+ Tip:
+
+ If changes to your Webpack aliases are not surfacing, they might be
+ [cached](https://webpack.js.org/configuration/cache/) in `node_modules/.cache/webpack`. Try
+ deleting that folder and restarting your server.
## Admin environment vars
- Important:
- Be careful about what variables you provide to your client-side code. Analyze every single one to make sure that you're not accidentally leaking anything that an attacker could exploit. Only keys that are safe to be available to everyone in plain text should be provided to your Admin panel.
+ Important:
+
+ Be careful about what variables you provide to your client-side code. Analyze every single one to
+ make sure that you're not accidentally leaking anything that an attacker could exploit. Only keys
+ that are safe to be available to everyone in plain text should be provided to your Admin panel.
By default, `env` variables are **not** provided to the Admin panel for security and safety reasons. But, Payload provides you with a way to still provide `env` vars to your frontend code.
diff --git a/docs/authentication/config.mdx b/docs/authentication/config.mdx
index 92b6d0a31..5e1f92bc4 100644
--- a/docs/authentication/config.mdx
+++ b/docs/authentication/config.mdx
@@ -41,8 +41,8 @@ Technically, both of these options will work for third-party integrations but th
To enable API keys on a collection, set the `useAPIKey` auth option to `true`. From there, a new interface will appear in the Admin panel for each document within the collection that allows you to generate an API key for each user in the Collection.
- User API keys are encrypted within the database, meaning that if your database
- is compromised, your API keys will not be.
+ User API keys are encrypted within the database, meaning that if your database is compromised,
+ your API keys will not be.
#### Authenticating via API Key
@@ -52,31 +52,31 @@ To authenticate REST or GraphQL API requests using an API key, set the `Authoriz
**For example, using Fetch:**
```ts
-import User from '../collections/User';
+import User from '../collections/User'
-const response = await fetch("http://localhost:3000/api/pages", {
+const response = await fetch('http://localhost:3000/api/pages', {
headers: {
Authorization: `${User.slug} API-Key ${YOUR_API_KEY}`,
},
-});
+})
```
Payload ensures that the same, uniform access control is used across all authentication strategies. This enables you to utilize your existing access control configurations with both API keys and the standard email/password authentication. This consistency can aid in maintaining granular control over your API keys.
-#### API Key *Only* Authentication
+#### API Key _Only_ Authentication
If you want to use API keys as the only authentication method for a collection, you can disable the default local strategy by setting `disableLocalStrategy` to `true` on the collection's `auth` property. This will disable the ability to authenticate with email and password, and will only allow for authentication via API key.
```ts
-import { CollectionConfig } from 'payload/types';
+import { CollectionConfig } from 'payload/types'
export const Customers: CollectionConfig = {
slug: 'customers',
auth: {
useAPIKey: true,
disableLocalStrategy: true,
- }
-};
+ },
+}
```
### Forgot Password
@@ -90,17 +90,16 @@ Function that accepts one argument, containing `{ req, token, user }`, that allo
Tip:
- HTML templating can be used to create custom email templates, inline CSS
- automatically, and more. You can make a reusable function that standardizes
- all email sent from Payload, which makes sending custom emails more DRY.
- Payload doesn't ship with an HTML templating engine, so you are free to choose
- your own.
+ HTML templating can be used to create custom email templates, inline CSS automatically, and more.
+ You can make a reusable function that standardizes all email sent from Payload, which makes
+ sending custom emails more DRY. Payload doesn't ship with an HTML templating engine, so you are
+ free to choose your own.
Example:
```ts
-import { CollectionConfig } from 'payload/types';
+import { CollectionConfig } from 'payload/types'
export const Customers: CollectionConfig = {
slug: 'customers',
@@ -109,7 +108,7 @@ export const Customers: CollectionConfig = {
// highlight-start
generateEmailHTML: ({ req, token, user }) => {
// Use the token provided to allow your user to reset their password
- const resetPasswordURL = `https://yourfrontend.com/reset-password?token=${token}`;
+ const resetPasswordURL = `https://yourfrontend.com/reset-password?token=${token}`
return `
@@ -123,22 +122,21 @@ export const Customers: CollectionConfig = {