payload 1.15.5 → 2.0.0-beta.0

package/docs/getting-started/concepts.mdx

@@ -1,160 +0,0 @@
----
-title: Payload Concepts
-label: Concepts
-order: 20
-desc: Payload is based around a small and intuitive set of concepts. Key concepts include collections, globals, fields and more.
-keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, express
----
-
-Payload is based around a small and intuitive set of concepts. Before starting to work with Payload, it's a good idea to familiarize yourself with the following:
-
-### Config
-
-<Banner type="info">
-	The Payload config is where you configure everything that Payload does.
-</Banner>
-
-By default, the Payload config lives in the root folder of your code and is named `payload.config.js` (`payload.config.ts` if you're using TypeScript), but you can customize its name and where you store it. You can write full functions and even full React components right into your config.
-
-### Collections
-
-<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.
-
-### 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.
-
-### 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.
-
-### 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).
-
-### Access Control
-
-<Banner type="info">
-  Access Control refers to Payload's system of defining who can do what to your API.
-</Banner>
-
-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).
-
-### Depth
-
-<Banner type="info">
-	"Depth" gives you control over how many levels down related documents should be automatically populated when retrieved.
-</Banner>
-
-You can specify population `depth` via query parameter in the REST API and by an option in the local API. *Depth has no effect in the GraphQL API, because there, depth is based on the shape of your queries.*
-It is also possible to limit the depth for specific `relation` and `upload` fields using the `maxDepth` property in your configuration.
-**For example, let's look at the following Collections:** `departments`, `users`, `posts`
-
-```
-// type: 'relationship' fields are equal to 1 depth level
-
-{
-	slug: 'posts',
-	fields: [
-		{
-			name: 'title',
-			type: 'text',
-		},
-		{
-			name: 'author',
-			label: 'Post Author',
-			type: 'relationship',
-			relationTo: 'users',
-		}
-	]
-}
-
-{
-	slug: 'users',
-	fields: [
-		{
-			name: 'email',
-			type: 'email',
-		},
-		{
-			name: 'department'
-			type: 'relationship',
-			relationTo: 'departments'
-		}
-	]
-}
-
-{
-	slug: 'departments',
-	fields: [
-		{
-			name: 'name'
-			type: 'text',
-		}
-	]
-}
-```
-
-If you were to query the Posts endpoint at, say, `http://localhost:3000/api/posts?depth=1`, you will retrieve Posts with populations one level deep. This depth parameter can be thought of as N, where N is the number of levels you want to populate. To populate one level further, you would simply specify N+1 as the depth. A returned result may look like the following:
-
-```
-// ?depth=1
-
-{
-  id: '5ae8f9bde69e394e717c8832',
-  title: 'This post sucks',
-  author: {
-    id: '5f7dd05cd50d4005f8bcab17',
-    email: 'spiderman@superheroes.gov',
-    department: '5e3ca05cd50d4005f8bdab15'
-  }
-}
-```
-
-Notice how the `user.author` is fully populated, but `user.author.department` is left as a document ID? That's because the User collection counted as the first level of `depth` and got populated—but then prevented any further populations from taking place.
-
-To populate `user.author.department` in it's entirety you could specify `?depth=2` or _higher_.
-
-```
-// ?depth=2
-
-{
-  id: '5ae8f9bde69e394e717c8832',
-  title: 'This post sucks',
-  author: {
-    id: '5f7dd05cd50d4005f8bcab17',
-    email: 'spiderman@superheroes.gov',
-    department: {
-      id: '5e3ca05cd50d4005f8bdab15',
-      name: 'Marvel'
-    }
-  }
-}
-```
-
-<Banner type="warning">
-  <strong>Note:</strong><br/>
-  When access control on collections prevents relationship fields from populating, the API response will contain the relationship id instead of the full document.
-</Banner>

package/docs/getting-started/installation.mdx

@@ -1,159 +0,0 @@
----
-title: Installation
-label: Installation
-order: 30
-desc: To quickly get started with Payload, simply run npx create-payload-app or install from scratch.
-keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, express
----
-
-#### Software Requirements
-
-Payload requires the following software:
-
-- Yarn or NPM
-- Node.js version 14+
-- A MongoDB Database
-
-<Banner type="warning">
-  Before proceeding any further, please ensure that you have the above
-  requirements met.
-</Banner>
-
-## Quickstart with create-payload-app
-
-To quickly scaffold a new Payload app in the fastest way possible, you can use [create-payload-app](https://npmjs.com/package/create-payload-app). To do so, run the following command:
-
-```
-npx create-payload-app
-```
-
-Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside.
-
-## Adding to an existing app
-
-Adding Payload to either a new or existing TypeScript + Express app is super straightforward. To add to an existing app, just run `npm install --save --legacy-peer-deps payload`.
-
-From there, the first step is writing a baseline config. Create a new `payload.config.ts` in your project's `/src` directory (or whatever your root TS dir is). The simplest config contains the following:
-
-```js
-import { buildConfig } from "payload/config";
-
-export default buildConfig({
-  // By default, Payload will boot up normally
-  // and you will be provided with a base `User` collection.
-  // But, here is where you define how you'd like Payload to work!
-});
-```
-
-Write the above code into your newly created config file. This baseline config will automatically provide you with a default `User` collection. For more information about users and authentication, including how to provide your own user config, jump to the [Authentication](/docs/authentication/config) section.
-
-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).
-
-### Server
-
-Now that you've got a baseline Payload config, it's time to initialize Payload. It requires an Express server that you provide, so if you're not familiar with how to set up a baseline Express server, please read up on exactly what Express is and why to use it. Express' own [Documentation](https://expressjs.com/en/starter/hello-world.html) is a good place to start. Otherwise, follow along below for how to build your own Express server to use with Payload.
-
-1. Run `npm install --save --legacy-peer-deps express` if you have not done so already
-1. Create a new `server.ts` file in the root directory of your app
-1. Add the following code to `server.ts`:
-
-```ts
-import express from "express";
-
-const app = express();
-
-app.listen(3000, async () => {
-  console.log(
-    "Express is now listening for incoming connections on port 3000."
-  );
-});
-```
-
-This server doesn't do anything just yet. But, after you have this in place, we can initialize Payload via its asynchronous `init()` method, which accepts a small set of arguments to tell it how to operate.
-
-To initialize Payload, update your `server.ts` file to reflect the following code:
-
-```ts
-import express from "express";
-import payload from "payload";
-
-require("dotenv").config();
-const app = express();
-
-const start = async () => {
-  await payload.init({
-    secret: process.env.PAYLOAD_SECRET,
-    mongoURL: process.env.MONGODB_URI,
-    express: app,
-  });
-
-  app.listen(3000, async () => {
-    console.log(
-      "Express is now listening for incoming connections on port 3000."
-    );
-  });
-};
-
-start();
-```
-
-A quick reminder: in this configuration, we're making use of two environmental variables, `process.env.PAYLOAD_SECRET` and `process.env.MONGODB_URI`. Often, it's smart to store these values in an `.env` file at the root of your directory and set different values for each of your environments (local, stage, prod, etc). The `dotenv` package is very handy and works well alongside of Payload. A typical `.env` file will look like this:
-
-```
-MONGODB_URI=mongodb://127.0.0.1/your-payload-app
-PAYLOAD_SECRET=your-payload-secret
-```
-
-Here is a list of all properties available to pass through `payload.init`:
-
-##### `express`
-
-**Required**. This is your Express app as shown above. Payload will tie into your existing `app` and scope all of its functionalities to sub-routers. By default, Payload will add an `/admin` router and an `/api` router, but you can customize these paths.
-
-##### `secret`
-
-**Required**. This is a secure string that will be used to authenticate with Payload. It can be random but should be at least 14 characters and be very difficult to guess.
-
-Payload uses this secret key to generate secure user tokens (JWT). Behind the scenes, we do not use your secret key to encrypt directly - instead, we first take the secret key and create an encrypted string using the SHA-256 hash function. Then, we reduce the encrypted string to its first 32 characters. This final value is what Payload uses for encryption.
-
-##### `mongoURL`
-
-**Required**. This is a fully qualified MongoDB connection string that points to your MongoDB database. If you don't have MongoDB installed locally, you can [follow these steps for Mac OSX](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-os-x/) and [these steps](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-windows/) for Windows 10. If you want to use a local database and you know you have MongoDB installed locally, a typical connection string will look like this:
-
-`mongodb://127.0.0.1/payload`
-
-In contrast to running MongoDB locally, a popular option is to sign up for a free [MongoDB Atlas account](https://www.mongodb.com/cloud/atlas), which is a fully hosted and cloud-based installation of MongoDB that you don't need to ever worry about.
-
-##### `mongoOptions`
-
-Customize MongoDB connection options. Payload will connect to your MongoDB database using default options which you can override and extend to include all the [options](https://mongoosejs.com/docs/connections.html#options) available to mongoose.
-
-##### `email`
-
-An object used to configure SMTP. [Read more](/docs/email/overview).
-
-##### `local`
-
-A boolean that when set to `true` tells Payload to start in local-only mode which will bypass setting up API routes. When set to `true`, `express` is not required. This is useful when running scripts that need to use Payload's [local-api](/docs/local-api/overview).
-
-##### `loggerOptions`
-
-Specify options for the built-in Pino logger that Payload uses for internal logging. See [Pino Docs](https://getpino.io/#/docs/api?id=options) for more info on what is available.
-
-##### `loggerDestination`
-
-Specify destination stream for the built-in Pino logger that Payload uses for internal logging. See [Pino Docs](https://getpino.io/#/docs/api?id=pino-destination) for more info on what is available.
-
-##### `onInit`
-
-A function that is called immediately following startup that receives the Payload instance as it's only argument.
-
-### Test it out
-
-After you've gotten this far, it's time to boot up Payload. Start your project in your application's folder to get going.
-
-After it starts, you can go to `http://localhost:3000/admin` to create your first Payload user!
-
-### Docker
-
-Looking to deploy Payload with Docker? New projects with `create-payload-app` come with a Dockerfile and docker-compose.yml file ready to go. Examples of these files can be seen in our [Deployment docs](/docs/production/deployment#docker).

package/docs/getting-started/what-is-payload.mdx

@@ -1,62 +0,0 @@
----
-title: What is Payload?
-label: What is Payload?
-order: 10
-desc: Payload is a next-gen headless Content Management System (CMS) and application framework.
-keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, express
----
-
-<YouTube
-  id="In_lFhzmbME"
-  title="Payload Introduction - Closing the Gap Between Headless CMS and Application Frameworks"
-/>
-
-<Banner type="success">
-  Payload is a headless CMS and application framework. It’s meant to provide a
-  massive boost to your development process, but importantly, stay out of your
-  way as your apps get more complex.
-</Banner>
-
-Out of the box, Payload gives you a lot of the things that you often need when developing a new website, web app, or native app:
-
-- A MongoDB database to store your data
-- A way to store, retrieve, and manipulate data of any shape via full REST and GraphQL APIs
-- Authentication—complete with commonly required functionality like registration, email verification, login, & password reset
-- Deep access control to your data, based on document or field-level functions
-- File storage and access control
-- A beautiful admin UI that’s generated specifically to suit your data
-
-## What does "headless" mean?
-
-A headless CMS is a system that sticks to what it's good at—managing content. It concentrates solely on granting administrators an effective way to author and maintain content, but doesn't control how and where that content is used.
-
-In this way, the CMS can ensure that its content editing experience is highly polished and effective while avoiding placing creative constraints on designers or restricting development teams. In contrast, traditional content management systems bind the presentation of your content to the storage of your content and severely limit the creativity, development and usability of the content that they manage.
-
-At this point this concept is [widely](https://en.wikipedia.org/wiki/Headless_content_management_system) [discussed](https://css-tricks.com/what-is-a-headless-cms/) online, and for good reason. The web has become more complicated and with complexity comes the demand for developers to better structure their code. The rise of interface libraries like React and Vue are now the de-facto standard for building modern applications and traditional content management systems are often not designed to make use of them.
-
-### Why Payload?
-
-The team behind Payload has been building websites and apps with existing content management systems and application frameworks for over a decade. We know what works and what doesn't about each of the existing solutions, and to this day have found no silver bullet solution.
-
-**We believe that a CMS should be:**
-
-- Cost-effective and should save time and effort
-- Intuitive for developers and content authors alike
-- Self-hosted however and wherever the application specifies
-- Designed in code but used with no coding experience
-- Blazing fast
-- Secure
-- Fully flexible and extensible
-
-Payload is our silver bullet solution. We've blended the best parts of our experience with other CMS and app frameworks into Payload, and we finally have everything we need when we build new apps and websites:
-
-- A beautiful, dynamic, customizable admin UI
-- Extensible and reusable authentication
-- Content localization
-- Local file storage
-- Extremely flexible access control
-- Field conditional logic
-- Block-based layout building
-- Array field type(s)
-- Security
-- and much more

package/docs/graphql/extending.mdx

@@ -1,156 +0,0 @@
----
-title: Adding your own Queries and Mutations
-label: Custom Queries and Mutations
-order: 20
-desc: Payload allows you to add your own GraphQL queries and mutations, simply set up GraphQL in your main Payload config by following these instructions.
-keywords: graphql, resolvers, mutations, custom, queries, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-You can add your own GraphQL queries and mutations to Payload, making use of all the types that Payload has defined for you.
-
-To do so, add your queries and mutations to the main Payload config as follows:
-
-| Config Path          | Description  |
-| -------------------- | -------------|
-| `graphQL.queries`    | Function that returns an object containing keys to custom GraphQL queries |
-| `graphQL.mutations`  | Function that returns an object containing keys to custom GraphQL mutations |
-
-The above properties each receive a function that is defined with the following arguments:
-
-**`GraphQL`**
-
-This is Payload's GraphQL dependency. You should not install your own copy of GraphQL as a dependency due to underlying restrictions based on how GraphQL works. Instead, you can use the Payload-provided copy via this argument.
-
-**`payload`**
-
-This is a copy of the currently running Payload instance, which provides you with existing GraphQL types for all of your Collections and Globals - among other things.
-
-##### Return value
-
-Both `graphQL.queries` and `graphQL.mutations` functions should return an object with properties equal to your newly written GraphQL queries and mutations.
-
-### Example
-
-`payload.config.js`:
-
-```ts
-import { buildConfig } from 'payload/config';
-import myCustomQueryResolver from './graphQL/resolvers/myCustomQueryResolver';
-
-export default buildConfig({
-  graphQL: {
-    // highlight-start
-    queries: (GraphQL, payload) => {
-      return {
-        MyCustomQuery: {
-          type: new GraphQL.GraphQLObjectType({
-            name: 'MyCustomQuery',
-            fields: {
-              text: {
-                type: GraphQL.GraphQLString,
-              },
-              someNumberField: {
-                type: GraphQL.GraphQLFloat,
-              },
-            },
-          }),
-          args: {
-            argNameHere: {
-              type: new GraphQL.GraphQLNonNull(GraphQLString),
-            }
-          },
-          resolve: myCustomQueryResolver,
-        }
-      }
-    }
-    // highlight-end
-  }
-})
-```
-
-### Resolver function
-
-In your resolver, make sure you set `depth: 0` if you're returning data directly from the local API so that GraphQL can correctly resolve queries to nested values such as relationship data.
-
-Your function will receive four arguments you can make use of:
-
-Example
-
-```ts
-async (obj, args, context, info) => { }
-```
-
-**`obj`** 
-
-The previous object. Not very often used and usually discarded.
-
-**`args`**
-
-The available arguments from your query or mutation will be available to you here, these must be configured via the custom operation first.
-
-**`context`**
-
-An object containing the `req` and `res` objects that will provide you with the `payload`, `user` instances and more, like any other Payload API handler.
-
-**`info`**
-
-Contextual information about the currently running GraphQL operation. You can get schema information from this as well as contextual information about where this resolver function is being run.
-
-### Types
-
-We've exposed a few types and utilities to help you extend the API further. Payload uses the GraphQL.js package for which you can view the full list of available types in the [official documentation](https://graphql.org/graphql-js/type/).
-
-**`GraphQL`**
-
-You can directly import the GraphQL package used by Payload, most useful for typing. For queries, mutations and handlers make sure you use the `GraphQL` and `payload` instances provided via arguments.
-
-**`buildPaginatedListType`**
-
-This is a utility function that allows you to build a new GraphQL type for a paginated result similar to the Payload's generated schema.
-It takes in two arguments, the first for the name of this new schema type and the second for the GraphQL type to be used in the docs parameter.
-
-Example
-
-```ts
-export const getMyPosts = (GraphQL, payload) => {
-  return {
-    args: {},
-    resolve: Resolver,
-    // The name of your new type has to be unique
-    type: buildPaginatedListType('AuthorPosts', payload.collections['posts'].graphQL?.type),
-  }
-}
-```
-
-**`payload.collections.slug.graphQL`**
-
-If you want to extend more of the provided API then the `graphQL` object on your collection slug will contain additional types to help you re-use code for types, mutations and queries.
-
-```ts
-graphQL?: {
-  type: GraphQLObjectType
-  paginatedType: GraphQLObjectType
-  JWT: GraphQLObjectType
-  versionType: GraphQLObjectType
-  whereInputType: GraphQLInputObjectType
-  mutationInputType: GraphQLNonNull<any>
-  updateMutationInputType: GraphQLNonNull<any>
-}
-```
-
-### Best practices
-
-There are a few ways to structure your code, we recommend using a dedicated `graphql` directory so you can keep all of your logic in one place. You have total freedom of how you want to structure this but a common pattern is to group functions by type and with their resolver.
-
-Example
-
-```
-src/graphql
----- queries/
-     index.ts
-    -- myCustomQuery/
-       index.ts
-       resolver.ts
-
----- mutations/
-```

package/docs/graphql/graphql-schema.mdx

@@ -1,92 +0,0 @@
----
-title: GraphQL Schema
-label: GraphQL Schema
-order: 30
-desc: Output your own GraphQL schema based on your collections and globals to a file.
-keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-When working with GraphQL it is useful to have the schema for development of other projects that need to call on your GraphQL endpoint. In Payload the schema is controlled by your collections and globals and is made available to the developer or third parties, it is not necessary for developers using Payload to write schema types manually.
-
-### Schema generatation script
-
-Run the following command in a Payload project to generate your project's GraphQL schema from Payload:
-
-```
-payload generate:graphQLSchema
-```
-
-You can run this command whenever you need to regenerate your GraphQL schema and output it to a file, and then you can use the schema for writing your own GraphQL elsewhere in other projects.
-
-### Custom output file path
-
-```js
-{
-  // the remainder of your config
-	graphQL: {
-		schemaOutputFile: path.resolve(__dirname, './graphql/schema.graphql'),
-	},
-}
-```
-
-### Custom Field Schemas
-
-For `array`, `block`, `group` and named `tab` fields, you can generate top level reusable interfaces. The following group field config:
-
-```ts
-{
-  type: 'group',
-  name: 'meta',
-  interfaceName: 'SharedMeta', <-- here!!
-  fields: [
-    {
-      name: 'title',
-      type: 'text',
-    },
-    {
-      name: 'description',
-      type: 'text',
-    },
-  ],
-}
-```
-
-will generate:
-
-```ts
-// a top level reusable type!!
-type SharedMeta {
-  title: String
-  description: String
-}
-
-// example usage inside collection schema
-type Collection1 {
-  // ...other fields
-  meta: SharedMeta
-}
-```
-
-The above example outputs all your definitions to a file relative from your payload config as `./graphql/schema.graphql`. By default, the file will be output to your current working directory as `schema.graphql`.
-
-#### Adding an NPM script
-
-<Banner type="warning">
-  <strong>Important</strong>
-  <br />
-  Payload needs to be able to find your config to generate your GraphQL schema.
-</Banner>
-
-Payload will automatically try and locate your config, but might not always be able to find it. For example, if you are working in a `/src` directory or similar, you need to tell Payload where to find your config manually by using an environment variable. If this applies to you, you can create an NPM script to make generating your types easier.
-
-To add an NPM script to generate your types and show Payload where to find your config, open your `package.json` and update the `scripts` property to the following:
-
-```json
-{
-  "scripts": {
-    "generate:graphQLSchema": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload generate:graphQLSchema"
-  }
-}
-```
-
-Now you can run `yarn generate:graphQLSchema` to easily generate your schema.