tabshift/payload
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: continues docs

Browse Source
This commit is contained in:
James
2020-12-28 13:32:12 -05:00
parent 24788b8282
commit 4fbf8aa0bf
14 changed files with 210 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/Components/overview.mdx → docs/Admin/components.mdx
View File

@@ -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.

13
docs/Admin/config.mdx Normal file
View File

@@ -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

10
docs/Configuration/express.mdx Normal file
View File

@@ -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)

8
docs/Configuration/hooks.mdx Normal file
View File

@@ -0,0 +1,8 @@
---
title: Payload-wide Hooks
label: Hooks
order: 80
---
Talk about hooks here. Currently only afterError.

37
docs/Configuration/introduction.mdx Normal file
View File

@@ -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.
<strong>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.</strong>
<Banner type="warning">
<strong>Important:</strong><br />This file is included in the Payload admin bundle, so make sure you do not embed any sensitive information.
</Banner>
## 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) |

7
docs/Configuration/localization.mdx Normal file
View File

@@ -0,0 +1,7 @@
---
title: Localization
label: Localization
order: 50
---
Talk about Localization here.

7
docs/Configuration/main.mdx
View File

@@ -1,7 +0,0 @@
---
title: The Main Config
label: Main
order: 10
---
Talk about how to write the main config here.

8
docs/Configuration/paths.mdx Normal file
View File

@@ -0,0 +1,8 @@
---
title: Paths
label: Paths
order: 80
---
Talk about Paths that can be defined here. Currently only SCSS.

10
docs/Configuration/webpack.mdx Normal file
View File

@@ -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

14
docs/Email/overview.mdx Normal file
View File

@@ -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)

2
docs/Production/security.mdx
View File

@@ -8,3 +8,5 @@ order: 20
- GraphQL Complexity
- Limits
- Max Depth
- CSRF
- CORS

1
docs/Upload/config.mdx
View File

@@ -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)

74
docs/getting-started/concepts.mdx
View File

@@ -37,3 +37,77 @@ You can define as many Collections as you need. On each Collection, you can spec
</Banner>
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
<Banner type="info">
"Depth" means how many levels down that 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.*
**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`.

35
docs/getting-started/installation.mdx
View File

@@ -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.
<Banner type="warning">
Before proceeding any further, please ensure that you have the above requirements met.
</Banner>
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!