diff --git a/docs/Components/overview.mdx b/docs/Admin/components.mdx similarity index 58% rename from docs/Components/overview.mdx rename to docs/Admin/components.mdx index d19f0a4723..48a8a9bec5 100644 --- a/docs/Components/overview.mdx +++ b/docs/Admin/components.mdx @@ -1,7 +1,7 @@ --- -title: Custom Components -label: Overview -order: 10 +title: Swap in your own React components +label: Custom Components +order: 20 --- Talk about how to build custom components. Show a list of all components that can be swapped out. diff --git a/docs/Admin/config.mdx b/docs/Admin/config.mdx new file mode 100644 index 0000000000..51b5bdc035 --- /dev/null +++ b/docs/Admin/config.mdx @@ -0,0 +1,13 @@ +--- +title: The Admin Panel +label: Config +order: 10 +--- + +Talk about the React admin panel here. + +- Main config +- Collection-level config +- Global-level config +- Field-level config + diff --git a/docs/Configuration/express.mdx b/docs/Configuration/express.mdx new file mode 100644 index 0000000000..339a025cfa --- /dev/null +++ b/docs/Configuration/express.mdx @@ -0,0 +1,10 @@ +--- +title: Express +label: Express +order: 60 +--- + +Talk about the Express configuration options here. + +- JSON (limit) +- Compression - takes all options as specified [here](http://expressjs.com/en/resources/middleware/compression.html) diff --git a/docs/Configuration/hooks.mdx b/docs/Configuration/hooks.mdx new file mode 100644 index 0000000000..46e9bdf48e --- /dev/null +++ b/docs/Configuration/hooks.mdx @@ -0,0 +1,8 @@ +--- +title: Payload-wide Hooks +label: Hooks +order: 80 +--- + +Talk about hooks here. Currently only afterError. + diff --git a/docs/Configuration/introduction.mdx b/docs/Configuration/introduction.mdx new file mode 100644 index 0000000000..3494a79350 --- /dev/null +++ b/docs/Configuration/introduction.mdx @@ -0,0 +1,37 @@ +--- +title: The Payload Config +label: Introduction +order: 10 +--- + +The Payload config is central to everything that Payload does. It scaffolds the data that Payload stores as well as maintains custom React components, hook logic, custom validations, and much more. The config itself and all of its dependencies are run through Babel, so you can take full advantage newer JavaScript features and even directly import React components containing JSX. + +It's also strongly typed with TypeScript, which means that even if you aren't using TypeScript to build your project, your IDE (such as VSCode) may still provide helpful information like typeahead suggestions. + + + Important:
This file is included in the Payload admin bundle, so make sure you do not embed any sensitive information. + + +## Options + +| Option | Description | +| -------------------- | -------------| +| `collections` | An array of all Collections that Payload will manage. To read more about how to define your collection configs, [click here](/docs/configuration/collections). +| `globals` | An array of all Globals that Payload will manage. For more on Globals and their configs, [click here](/docs/configuration/globals). +| `admin` | Base Payload admin configuration. Specify custom components, control metadata, set the Admin user collection, and [more](/docs/admin/config#global). | +| `localization` | Opt-in and control how Payload handles the translation of your content into multiple locales. [More](/docs/configuration/localization) | +| `graphQL` | Manage GraphQL-specific functionality here. Define your own queries and mutations, manage query complexity limits, and [more](/docs/graphql/config). | +| `cookiePrefix` | A string that will be prefixed to all cookies that Payload sets. | +| `cors` | Either a whitelist array of URLS to allow CORS requests from, or a wildcard string (`'*'`) to accept incoming requests from any domain. | +| `csrf` | A whitelist array of URLs to allow Payload cookies to be accepted from as a form of CSRF protection. [More](/docs/production/security#csrf) | +| `defaultDepth` | If a user does not specify `depth` while requesting a resource, this depth will be used. [More](/docs/getting-started/concepts#depth) | +| `maxDepth` | The maximum allowed depth to be permitted application-wide. This setting helps prevent against malicious queries. Defaults to `10`. | +| `upload` | Base Payload upload configuration. [More](/docs/admin/upload#global). | +| `routes` | Control the routing structure that Payload binds itself to. Specify `admin`, `api`, `graphQL`, and `graphQLPlayground`. | +| `paths` | Specific paths used to override Payload functionality. [More](/docs/configuration/paths) | +| `email` | Base email settings to allow Payload to generate email such as Forgot Password requests and other requirements. [More](/docs/email/overview#config) | +| `express` | Express-specific middleware options such as compression and JSON parsing. [More](/docs/configuration/express). | +| `debug` | Enable to expose more detailed error information. | +| `rateLimit` | Control IP-based rate limiting for all Payload resources. Used to prevent DDoS attacks and [more].(/docs/production/security#rate-limiting). | +| `webpack` | Customize the Webpack config used to generate the Payload Admin panel. Define ENV variables, alias server-only modules, and [more](/docs/configuration/webpack). | +| `hooks` | Tap into Payload-wide hooks. [More](/docs/configuration/hooks) | diff --git a/docs/Configuration/localization.mdx b/docs/Configuration/localization.mdx new file mode 100644 index 0000000000..5945986733 --- /dev/null +++ b/docs/Configuration/localization.mdx @@ -0,0 +1,7 @@ +--- +title: Localization +label: Localization +order: 50 +--- + +Talk about Localization here. diff --git a/docs/Configuration/main.mdx b/docs/Configuration/main.mdx deleted file mode 100644 index 906d3b1121..0000000000 --- a/docs/Configuration/main.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: The Main Config -label: Main -order: 10 ---- - -Talk about how to write the main config here. diff --git a/docs/Configuration/paths.mdx b/docs/Configuration/paths.mdx new file mode 100644 index 0000000000..09dd0134e4 --- /dev/null +++ b/docs/Configuration/paths.mdx @@ -0,0 +1,8 @@ +--- +title: Paths +label: Paths +order: 80 +--- + +Talk about Paths that can be defined here. Currently only SCSS. + diff --git a/docs/Configuration/webpack.mdx b/docs/Configuration/webpack.mdx new file mode 100644 index 0000000000..41e50364bf --- /dev/null +++ b/docs/Configuration/webpack.mdx @@ -0,0 +1,10 @@ +--- +title: Webpack +label: Webpack +order: 70 +--- + +Talk about common uses for extending and customizing the Webpack config. + +- Provide ENV vars to admin bundle via DefinePlugin +- Alias server-only modules to reduce bundle size diff --git a/docs/Email/overview.mdx b/docs/Email/overview.mdx new file mode 100644 index 0000000000..bb1f051002 --- /dev/null +++ b/docs/Email/overview.mdx @@ -0,0 +1,14 @@ +--- +title: Email Functionality +label: Email +order: 10 +--- + +Talk about how the Payload email service works. + +- Transport options +- Payload Config (needs #config anchor) +- Nodemailer +- Auth options +- Mock credentials (how to use) + diff --git a/docs/Production/security.mdx b/docs/Production/security.mdx index b079395f01..c68063bb10 100644 --- a/docs/Production/security.mdx +++ b/docs/Production/security.mdx @@ -8,3 +8,5 @@ order: 20 - GraphQL Complexity - Limits - Max Depth +- CSRF +- CORS diff --git a/docs/Upload/config.mdx b/docs/Upload/config.mdx index ea2020bc92..b9c02f22e3 100644 --- a/docs/Upload/config.mdx +++ b/docs/Upload/config.mdx @@ -8,6 +8,7 @@ Talk about how to configure uploads here. Need to cover: +1. Global upload config #global 1. Can have multiple collections 1. Static directory 1. How to upload (multipart/form-data) diff --git a/docs/getting-started/concepts.mdx b/docs/getting-started/concepts.mdx index 0f0b5b5dca..b4242bcb93 100644 --- a/docs/getting-started/concepts.mdx +++ b/docs/getting-started/concepts.mdx @@ -37,3 +37,77 @@ You can define as many Collections as you need. On each Collection, you can spec Payload comes with [many different types](../fields/overview) of Fields 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. + +### Depth + + + "Depth" means how many levels down that related documents should be automatically populated when retrieved. + + +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.* + +**For example, let's take the following Collections for example:** + +``` +{ + slug: 'posts', + fields: [ + { + name: 'title', + label: 'Title', + type: 'text', + }, + { + name: 'author', + label: 'Post Author', + type: 'relationship', + relationTo: 'users', + } + ] +} + +{ + slug: 'users', + fields: [ + { + name: 'email', + label: 'Email', + type: 'email', + }, + { + name: 'department' + label: 'Department', + type: 'relationship', + relationTo: 'departments' + } + ] +} + +{ + slug: 'departments', + fields: [ + { + name: 'name' + label: '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. A returned result may look like the following: + +``` +{ + title: 'This post sucks', + author: { + id: '5f7dd05cd50d4005f8bcab17', + email: 'spiderman@superheroes.gov', + department: '5e3ca05cd50d4005f8bdab15' + } +} +``` + +Notice how the `author` is fully populated but its `department` is left as a document ID. That's because the User counted as the first level of `depth` and got populated—but then prevented any further populations from taking place. + +To populate both the User and their department, a user can specify `?depth=2`. diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index bcf3489f03..12566654c7 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -4,26 +4,37 @@ label: Installation order: 30 --- -### Requirements +#### Software Requirements Payload requires the following software: - Yarn or NPM - NodeJS version 10+ - A Mongo Database -- Express -Once you are sure that you have all of these dependencies, you can `yarn add payload` or `npm install --save payload` at the root of your project folder. + + Before proceeding any further, please ensure that you have the above requirements met. + -The first step is writing a baseline config. The simplest config contains the following: +## 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 `npx create-payload-app` in the folder where you'd like your project to be created and then follow the prompts. You can choose between scaffolding a TypeScript or JavaScript project. + +## From scratch + +Adding Payload to either a new or existing app is super straightforward. To add to an existing Node + Express app, just run `npm install --save payload`. Or, to start a new project from scratch, run `npm init` and then `npm install --save payload express`. + +From there, the first step is writing a baseline config. Create a new `payload.config.js` in the root of your project. The simplest config contains the following: ``` -export default { +import { buildConfig } from 'payload'; + +export default buildConfig({ serverURL: 'http://localhost:3000', -}; +}); ``` -Create a new `payload.config.js` file in the root of your project and write the above code into it. This file fully supports ES6. +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, 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/main). @@ -31,7 +42,7 @@ Although this is just the bare minimum config, there are *many* more options tha 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 `yarn add express` +1. Run `npm install --save express` if you have not done so already 1. Create a new `server.js` file in the root folder of your app 1. Add the following code to `server.js`: @@ -46,9 +57,9 @@ app.listen(3000, async () => { ``` -This server doesn't do anything just yet. But, after you have this in place, it's time to initialize Payload. Payload is initialized via its `init()` method, which accepts a small set of arguments to tell it how to operate. For a full list of `init` arguments, please consult the [main configuration](/docs/configuration/main#init) docs. +This server doesn't do anything just yet. But, after you have this in place, we can initialize Payload via its `init()` method, which accepts a small set of arguments to tell it how to operate. For a full list of `init` arguments, please consult the [main configuration](/docs/configuration/main#init) docs. -To initialize Payload, update your `server.js` file with the following code: +To initialize Payload, update your `server.js` file to reflect the following code: ``` const express = require('express'); @@ -72,7 +83,7 @@ As you can see above, the required arguments to the `init` function are as follo ##### `secret` -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. Often, it's smart to store this value in an `env` and set different values for each of your environments (ocal, stage, prod, etc). +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. Often, it's smart to store this value in an `env` and set different values for each of your environments (ocal, stage, prod, etc). The `dotenv` package is very handy and works well alongside of Payload. ##### `mongoURL` @@ -88,7 +99,7 @@ This is your Express app as shown above. Payload will tie into your existing `ap ### Test it out -After you've gotten this far, it's time to boot up Payload. At the command line, run `yarn` or `npm install` and then `node server.js` in your application's folder to start up your app and initialize Payload. +After you've gotten this far, it's time to boot up Payload. At the command line, run `npm install` and then `node server.js` in your application's folder to start up your app and initialize Payload. After it starts, you can go to `http://localhost:3000/admin` to create your first Payload user!