payload 1.15.6 → 2.0.0-beta.1

package/docs/admin/overview.mdx

@@ -1,84 +0,0 @@
----
-title: The Admin Panel
-label: Overview
-order: 10
-desc: Manage your data and customize the Admin Panel by swapping in your own React components. Create, modify or remove views, fields, styles and much more.
-keywords: admin, components, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-Payload dynamically generates a beautiful, fully functional React admin panel to manage your data. It's extremely powerful and can be customized / extended upon easily by swapping in your own React components. You can add additional views, modify how built-in views look / work, swap out Payload branding for your client's, build your own field types and much more.
-
-The Payload Admin panel is built with Webpack, code-split, highly performant (even with 100+ fields), and written fully in TypeScript.
-
-<Banner type="success">
-  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.
-</Banner>
-
-![Payload's Admin panel built in React](https://payloadcms.com/images/docs/admin.jpg)
-
-_Screenshot of the Admin panel while editing a document from an example `AllFields` collection_
-
-## Admin Options
-
-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`.                                                                                                                                                  |
-| `disable`             | If set to `true`, the entire Admin panel will be disabled.                                                                                                                                                                                                   |
-| `indexHTML`           | Optionally replace the entirety of the `index.html` file used by the Admin panel. Reference the [base index.html file](https://github.com/payloadcms/payload/blob/master/src/admin/index.html) to ensure your replacement has the appropriate HTML elements. |
-| `css`                 | Absolute path to a stylesheet that you can use to override / customize the Admin panel styling. [More](/docs/admin/customizing-css).                                                                                                                         |
-| `scss`                | Absolute path to a Sass variables / mixins stylesheet meant to override Payload styles to make for an easy re-skinning of the Admin panel. [More](/docs/admin/customizing-css#overriding-scss-variables).                                                    |
-| `dateFormat`          | Global date format that will be used for all dates in the Admin panel. Any valid [date-fns](https://date-fns.org/) format pattern can be used.                                                                                                               |
-| `avatar`              | Set account profile picture. Options: `gravatar`, `default` or a custom React component.                                                                                                                                                                     |
-| `autoLogin`           | Used to automate admin log-in for dev and demonstration convenience. [More](/docs/authentication/config).                                                                                                                                                    |
-| `components`          | Component overrides that affect the entirety of the Admin panel. [More](/docs/admin/components)                                                                                                                                                              |
-| `webpack`             | Customize the Webpack config that's used to generate the Admin panel. [More](/docs/admin/webpack)                                                                                                                                                            |
-| **`logoutRoute`**     | The route for the `logout` page.                                                                                                                                                                                                                             |
-| **`inactivityRoute`** | The route for the `logout` inactivity page.                                                                                                                                                                                                                  |
-
-### The Admin User Collection
-
-<Banner type="warning">
-  <strong>Important:</strong>
-  <br />
-  The Payload Admin panel can only be used by one Collection that supports
-  [Authentication](/docs/authentication/overview).
-</Banner>
-
-To specify which Collection to use to log in to the Admin panel, pass the `admin` options a `user` key equal to the slug of the Collection that you'd like to use.
-
-`payload.config.js`:
-
-```ts
-import { buildConfig } from "payload/config";
-
-const config = buildConfig({
-  admin: {
-    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.
-
-**Note: you can use whatever Collection you'd like to access the Admin panel as long as the Collection supports Authentication. It doesn't need to be called `users`!**
-
-For example, you may wish to have two Collections that both support `Authentication`:
-
-- `admins` - meant to have a higher level of permissions to manage your data and access the Admin panel
-- `customers` - meant for end users of your app that should not be allowed to log into the Admin panel
-
-This is totally possible. For the above scenario, by specifying `admin: { user: 'admins' }`, your Payload Admin panel will use `admins`. Any users logged in as `customers` will not be able to log in via the Admin panel.
-
-### Light and dark modes
-
-Users in the admin panel have access to choosing between light mode and dark mode for their editing experience. The setting is managed while logged into the admin UI within the user account page and will be stored with the browser. By default, the operating system preference is detected and used.
-
-### Restricting user access
-
-If you would like to restrict which users from a single Collection can access the Admin panel, you can use the `admin` access control function. [Click here](/docs/access-control/overview#admin) to learn more.

package/docs/admin/preferences.mdx

@@ -1,157 +0,0 @@
----
-title: Managing User Preferences
-label: Preferences
-order: 50
-desc: Store the preferences of your users as they interact with the Admin panel.
-keywords: admin, preferences, custom, customize, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-As your users interact with your Admin panel, you might want to store their preferences in a persistent manner, so that when they revisit the Admin panel, they can pick right back up where they left off.
-
-Out of the box, Payload handles the persistence of your users' preferences in a handful of ways, including:
-
-1. Collection `List` view active columns, and their order, that users define
-1. Their last active locale
-1. The "collapsed" state of blocks, on a document level, as users edit or interact with documents
-
-<Banner type="warning">
-	<strong>Important:</strong><br/>
-	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.
-</Banner>
-
-### Use cases
-
-This API is used significantly for internal operations of the Admin panel, as mentioned above. But, if you're building your own React components for use in the Admin panel, you can allow users to set their own preferences in correspondence to their usage of your components. For example:
-
-- If you have built a "color picker", you could "remember" the last used colors that the user has set for easy access next time
-- If you've built a custom `Nav` component, and you've built in an "accordion-style" UI, you might want to store the `collapsed` state of each Nav collapsible item. This way, if an editor returns to the panel, their `Nav` state is persisted automatically
-- You might want to store `recentlyAccessed` documents to give admin editors an easy shortcut back to their recently accessed documents on the `Dashboard` or similar
-- Many other use cases exist. Invent your own! Give your editors an intelligent and persistent editing experience.
-
-### Database
-
-Payload automatically creates an internally used `_preferences` collection that stores user preferences. Each document in the `_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`               | The ID of the `user` that is storing its preference. |
-| `userCollection`     | The `slug` of the collection that the `user` is logged in as. |
-| `value`              | The value of the preference. Can be any data shape that you need. |
-| `createdAt`          | A timestamp of when the preference was created. |
-| `updatedAt`          | A timestamp set to the last time the preference was updated.
-
-### APIs
-
-Preferences are available to both [GraphQL](/docs/graphql/overview#preferences) and [REST](/docs/rest-api/overview#) APIs.
-
-### Adding or reading Preferences in your own components
-
-The Payload admin panel offers a `usePreferences` hook. The hook is only meant for use within the admin panel itself. It provides you with two methods:
-
-##### `getPreference`
-
-This async method provides an easy way to retrieve a user's preferences by `key`. It will return a promise containing the resulting preference value.
-
-**Arguments**
-
-- `key`: the `key` of your preference to retrieve.
-
-##### `setPreference`
-
-Also async, this method provides you with an easy way to set a user preference. It returns `void`.
-
-**Arguments:**
-
-- `key`: the `key` of your preference to set.
-- `value`: the `value` of your preference that you're looking to set.
-
-## Example
-
-Here is an example for how you can utilize `usePreferences` within your custom Admin panel components. Note - this example is not fully useful and is more just a reference for how to utilize the Preferences API. In this case, we are demonstrating how to set and retrieve a user's last used colors history within a `ColorPicker` or similar type component.
-
-```
-import React, { Fragment, useState, useEffect, useCallback } from 'react';
-import { usePreferences } from 'payload/components/preferences';
-
-const lastUsedColorsPreferenceKey = 'last-used-colors';
-
-const CustomComponent = (props) => {
-  const { getPreference, setPreference } = usePreferences();
-
-  // Store the last used colors in local state
-  const [lastUsedColors, setLastUsedColors] = useState([]);
-
-  // Callback to add a color to the last used colors
-  const updateLastUsedColors = useCallback((color) => {
-    // First, check if color already exists in last used colors.
-    // If it already exists, there is no need to update preferences
-    const colorAlreadyExists = lastUsedColors.indexOf(color) > -1;
-
-    if (!colorAlreadyExists) {
-      const newLastUsedColors = [
-        ...lastUsedColors,
-        color,
-      ];
-
-      setLastUsedColors(newLastUsedColors);
-      setPreference(lastUsedColorsPreferenceKey, newLastUsedColors);
-    }
-  }, [lastUsedColors, setPreference]);
-
-  // Retrieve preferences on component mount
-  // This will only be run one time, because the `getPreference` method never changes
-  useEffect(() => {
-    const asyncGetPreference = async () => {
-      const lastUsedColorsFromPreferences = await getPreference(lastUsedColorsPreferenceKey);
-      setLastUsedColors(lastUsedColorsFromPreferences);
-    };
-
-    asyncGetPreference();
-  }, [getPreference]);
-
-  return (
-    <div>
-      <button
-        type="button"
-        onClick={() => updateLastUsedColors('red')}
-      >
-        Use red
-      </button>
-      <button
-        type="button"
-        onClick={() => updateLastUsedColors('blue')}
-      >
-        Use blue
-      </button>
-      <button
-        type="button"
-        onClick={() => updateLastUsedColors('purple')}
-      >
-        Use purple
-      </button>
-      <button
-        type="button"
-        onClick={() => updateLastUsedColors('yellow')}
-      >
-        Use yellow
-      </button>
-      {lastUsedColors && (
-        <Fragment>
-          <h5>Last used colors:</h5>
-          <ul>
-            {lastUsedColors?.map((color) => (
-              <li key={color}>
-                {color}
-              </li>
-            ))}
-          </ul>
-        </Fragment>
-      )}
-    </div>
-  );
-};
-
-export default CustomComponent;
-```

package/docs/admin/webpack.mdx

@@ -1,176 +0,0 @@
----
-title: Webpack
-label: Webpack
-order: 60
-desc: The Payload admin panel uses Webpack 5 and supports many common functionalities such as SCSS and Typescript out of the box to give you more freedom.
-keywords: admin, webpack, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-Payload uses Webpack 5 to build the Admin panel. It comes with support for many common functionalities such as SCSS and Typescript out of the box, but there are many cases where you may need to add support for additional functionalities.
-
-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';
-
-export default buildConfig({
-	admin: {
-		// highlight-start
-		webpack: (config) => {
-			// Do something with the config here
-
-			return config;
-		}
-		// highlight-end
-	}
-});
-```
-
-### Aliasing server-only modules
-
-A common use case for extending the Payload config is to alias server-only modules, thus preventing them from inclusion into the browser JavaScript bundle.
-
-As the Payload config is used in both server **and** client contexts, you may find yourself writing code in your Payload config that may be incompatible with browser environments.
-
-Examples of **non** browser-friendly packages:
-
-- `fs`
-- `stripe`
-- `authorizenet`
-- `nodemailer`
-
-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.
-
-<Banner type="success">
-	<strong>Tip:</strong><br/>
-	To avoid problems with server code making it to your Webpack bundle, you can use the <strong>alias</strong> Webpack feature to tell Webpack to avoid importing the modules you want to restrict to server-only.
-</Banner>
-
-<strong>For example, let's say that you have a Collection called `Subscriptions` which relies on Stripe:</strong>
-
-<br/><br/>
-
-`collections/Subscriptions/index.js`
-```ts
-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,
-		}
-	]
-};
-```
-
-The collection above features a `beforeChange` hook that creates a Stripe subscription whenever a Subscription document is created in Payload.
-
-<strong>That hook might look something like this:</strong>
-
-<br/><br/>
-
-`collections/Subscriptions/hooks/createStripeSubscription.js`
-```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};
-
-		// 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;
-
-    return dataWithStripeID
-	}
-
-	return data;
-}
-
-export default createStripeSubscription;
-```
-
-<Banner type="error">
-	<strong>Warning:</strong><br/>
-	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.
-</Banner>
-
-**As-is, this collection will prevent your Admin panel from bundling or loading correctly, because Stripe relies on some Node-only packages.**
-
-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');
-
-export default buildConfig({
-	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 {};
-```
-
-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.
-
-<Banner type="success">
-	<strong>Tip:</strong><br/>
-	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.
-</Banner>
-
-## Admin environment vars
-
-<Banner type="warning">
-	<strong>Important:</strong><br />
-	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.
-</Banner>
-
-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.
-
-**Payload will automatically supply any present `env` variables that are prefixed with `PAYLOAD_PUBLIC_` directly to the Admin panel.**
-
-For example, if you've got the following environment variable:
-
-`PAYLOAD_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXX`
-
-This key will automatically be made available to the Payload bundle and can be referenced in your Admin component code as `process.env.PAYLOAD_PUBLIC_STRIPE_PUBLISHABLE_KEY`.