184 lines
9.8 KiB
Plaintext
184 lines
9.8 KiB
Plaintext
---
|
|
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, nextjs
|
|
---
|
|
|
|
Payload is based around a small and intuitive set of high-level concepts. Before starting to work with Payload, it's a good idea to familiarize yourself with these concepts in order to establish a common language and understanding when discussing Payload.
|
|
|
|
## Config
|
|
|
|
The Payload Config is central to everything that Payload does. It allows for the deep configuration of your application through a simple and intuitive API. The Payload Config is a fully-typed JavaScript object that can be infinitely extended upon. [More details](../configuration/overview).
|
|
|
|
## Database
|
|
|
|
Payload is database agnostic, meaning you can use any type of database behind Payload's familiar APIs through a Database Adapter. [More details](../database/overview).
|
|
|
|
## Collections
|
|
|
|
A Collection is a group of records, called Documents, that all share a common schema. Each Collection saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define. [More details](../configuration/collections).
|
|
|
|
## Globals
|
|
|
|
Globals are in many ways similar to [Collections](../configuration/collections), except they correspond to only a single Document. Each Global saves to the [Database](../database/overview) based on the [Fields](../fields/overview) that you define. [More details](../configuration/globals).
|
|
|
|
## Fields
|
|
|
|
Fields are the building blocks of Payload. They define the schema of the Documents that will be stored in the [Database](../database/overview), as well as automatically generate the corresponding UI within the Admin Panel. [More details](../fields/overview).
|
|
|
|
## Hooks
|
|
|
|
Hooks allow you to execute your own logic during specific events of the Document lifecycle, such as read or update. [More details](../hooks/overview).
|
|
|
|
## Access Control
|
|
|
|
Access Control determines what a user can and cannot do with any given Document. [More details](../access-control/overview).
|
|
|
|
## Admin Panel
|
|
|
|
Payload dynamically generates a beautiful, fully type-safe interface to manage your users and data. The Admin Panel is a React application built using the Next.js App Router. [More details](../admin/overview).
|
|
|
|
## Plugins
|
|
|
|
Plugins allow for developers to easily inject custom—sometimes complex—functionality into Payload apps from a very small touch-point. [More details](../plugins/overview).
|
|
|
|
## Retrieving Data
|
|
|
|
Everything Payload does (create, read, update, delete, login, logout, etc) is exposed to you via three APIs:
|
|
|
|
- [Local API](#local-api) - Extremely fast, direct-to-database access
|
|
- [REST API](#rest-api) - Standard HTTP endpoints for querying and mutating data
|
|
- [GraphQL](#graphql) - A full GraphQL API with a GraphQL Playground
|
|
|
|
<Banner type="success">
|
|
<strong>Note:</strong>
|
|
All of these APIs share the exact same query language. [More details](../queries/overview).
|
|
</Banner>
|
|
|
|
### Local API
|
|
|
|
By far one of the most powerful aspects of Payload is the fact that it gives you direct-to-database access to your data through the [Local API](../local-api/overview). It's _extremely_ fast and does not incur any typical REST API / GraphQL / HTTP overhead—you query your database directly in Node.js.
|
|
|
|
The Local API is written in TypeScript, and so it is strongly typed and extremely nice to use. It works anywhere on the server, including custom Next.js Routes, Payload Hooks, Payload Access Control, and React Server Components.
|
|
|
|
Here's a quick example of a React Server Component fetching page data with Payload's Local API:
|
|
|
|
```tsx
|
|
import React from 'react'
|
|
import config from '@payload-config'
|
|
import { getPayloadHMR } from '@payloadcms/next'
|
|
|
|
const MyServerComponent: React.FC = () => {
|
|
// If you're working in Next.js, and you want HMR,
|
|
// you should get Payload via the `getPayloadHMR` function.
|
|
const payload = await getPayloadHMR({ config })
|
|
|
|
// If you are writing a standalone script and do not need HMR,
|
|
// you can get Payload via import { getPayload } from 'payload' instead.
|
|
|
|
// The `findResult` here will be fully typed as `PaginatedDocs<Page>`,
|
|
// where you will have the `docs` that are returned as well as
|
|
// information about how many items are returned / are available in total / etc
|
|
const findResult = await payload.find({ collection: 'pages' })
|
|
|
|
return (
|
|
<ul>
|
|
{findResult.docs.map((page) => {
|
|
// Render whatever here!
|
|
// The `page` is fully typed as your Pages collection!
|
|
})}
|
|
</ul>
|
|
)
|
|
}
|
|
```
|
|
|
|
<Banner type="info">
|
|
For more information about the Local API, [click here](../local-api/overview).
|
|
</Banner>
|
|
|
|
### REST API
|
|
|
|
By default, the Payload [REST API](../rest-api/overview) will be mounted automatically for you at the `/api` path of your app.
|
|
|
|
For example, if you have a [Collection](../configuration/collections) called `pages`:
|
|
|
|
```ts
|
|
fetch('https://localhost:3000/api/pages') // highlight-line
|
|
.then((res) => res.json())
|
|
.then((data) => console.log(data))
|
|
```
|
|
|
|
<Banner type="info">
|
|
For more information about the REST API, [click here](../rest-api/overview).
|
|
</Banner>
|
|
|
|
### GraphQL API
|
|
|
|
Payload automatically exposes GraphQL queries and mutations for everything it does through a dedicated [GraphQL API](../graphql/overview).
|
|
|
|
By default, you'll find the GraphQL route handler in your `/app/(payload)/api/graphql` folder, which makes the GraphQL endpoint available by default at `http://localhost:3000/api/graphql`.
|
|
|
|
You'll also find a full GraphQL Playground which can be accessible via `http://localhost:3000/api/graphql-playground`.
|
|
|
|
You can use any GraphQL client with Payload's GraphQL endpoint. Here are a few packages:
|
|
|
|
- [`graphql-request`](https://www.npmjs.com/package/graphql-request) - a very lightweight GraphQL client
|
|
- [`@apollo/client`](https://www.apollographql.com/docs/react/api/core/ApolloClient/) - an industry-standard GraphQL client with lots of nice features
|
|
|
|
If you don't use GraphQL, you can delete those files! But if you do, you'll find that GraphQL is a first-class API in Payload. Either way, the overhead of GraphQL is completely constrained to these endpoints, and will not slow down / affect Payload outside of those endpoints themselves.
|
|
|
|
<Banner type="info">
|
|
For more information about the GraphQL API, [click here](../graphql/overview).
|
|
</Banner>
|
|
|
|
### Depth
|
|
|
|
Documents can be related to other Documents through a concept called "relationships". When you query a Document, you can specify these relationships are populated. [More details](../queries/depth).
|
|
|
|
## Package Structure
|
|
|
|
Payload is abstracted into a set of dedicated packages to keep the core `payload` package as lightweight as possible. This allows you to only install the parts of Payload based on your unique project requirements.
|
|
|
|
<Banner type="warning">
|
|
<strong>Important:</strong>
|
|
Version numbers of all official Payload packages are always published in sync. You should make sure that you always use matching versions for all official Payload packages.
|
|
</Banner>
|
|
|
|
`payload`
|
|
|
|
The `payload` package is where core business logic for Payload lives. You can think of Payload as an ORM with superpowers—it contains the logic for all Payload "operations" like `find`, `create`, `update`, and `delete` and exposes a [Local API](../local-api/overview). It executes [Access Control](../access-control/overview), [Hooks](../hooks/overview), [Validation](../fields/overview#validation), and more.
|
|
|
|
Payload itself is extremely compact, and can be used in any Node environment. As long as you have `payload` installed and you have access to your Payload Config, you can query and mutate your database directly without going through an unnecessary HTTP layer.
|
|
|
|
Payload also contains all TypeScript definitions, which can be imported from `payload` directly.
|
|
|
|
Here's how to import some common Payload types:
|
|
|
|
```ts
|
|
import { Config, CollectionConfig, GlobalConfig, Field } from 'payload'
|
|
```
|
|
|
|
`@payloadcms/next`
|
|
|
|
Whereas Payload itself is responsible for direct database access, and control over Payload business logic, the `@payloadcms/next` package is responsible for the Admin Panel and the entire HTTP layer that Payload exposes, including the [REST API](../rest-api/overview) and [GraphQL API](../graphql/overview).
|
|
|
|
`@payloadcms/graphql`
|
|
|
|
All of Payload's GraphQL functionality is abstracted into a separate package. Payload, its Admin UI, and REST API have absolutely no overlap with GraphQL, and you will incur no performance overhead from GraphQL if you are not using it. However, it's installed within in the `@payloadcms/next` package so you don't have to install it manually. You do, however, need to have GraphQL installed separately in your `package.json` if you are using GraphQL.
|
|
|
|
`@payloadcms/ui`
|
|
|
|
This is the UI library that Payload's Admin Panel uses. All components are exported from this package and can be re-used as you build extensions to the Payload admin UI, or want to use Payload components in your own React apps. Some exports are server components and some are client components.
|
|
|
|
`@payloadcms/db-postgres`, `@payloadcms/db-mongodb`
|
|
|
|
You can choose which Database Adapter you'd like to use for your project, and no matter which you choose, the entire data layer for Payload is contained within these packages. You can only use one at a time for any given project.
|
|
|
|
`@payloadcms/richtext-lexical`, `@payloadcms/richtext-slate`
|
|
|
|
Payload's Rich Text functionality is abstracted into separate packages and if you want to enable Rich Text in your project, you'll need to install one of these packages. We recommend Lexical for all new projects, and this is where Payload will focus its efforts on from this point, but Slate is still supported if you have already built with it.
|
|
|
|
Rich Text is entirely optional and you may not need it for your project.
|