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

chore: updated 3.0 graphql docs (#6859)

Browse Source
This commit is contained in:
Jarrod Flesch
2024-06-21 15:45:52 -04:00
committed by GitHub
parent 8f977b9548
commit e036d4efab
7 changed files with 64 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/graphql/extending.mdx
View File

@@ -34,7 +34,7 @@ Both `graphQL.queries` and `graphQL.mutations` functions should return an object
`payload.config.js`:
```ts
import { buildConfig } from 'payload/config'
import { buildConfig } from 'payload'
import myCustomQueryResolver from './graphQL/resolvers/myCustomQueryResolver'
export default buildConfig({
@@ -100,9 +100,24 @@ Contextual information about the currently running GraphQL operation. You can ge
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/).
**`GraphQLJSON`** & **`GraphQLJSONObject`**
```ts
import { GraphQLJSON, GraphQLJSONObject } from '@payloadcms/graphql/types'
```
**`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.
You can directly import the GraphQL package used by Payload, most useful for typing.
```ts
import { GraphQL } from '@payloadcms/graphql/types'
```
<Banner type="warning">
For queries, mutations and handlers make sure you use the `GraphQL` and `payload` instances provided via arguments.
</Banner>
**`buildPaginatedListType`**
@@ -112,6 +127,8 @@ It takes in two arguments, the first for the name of this new schema type and th
Example
```ts
import { buildPaginatedListType } from '@payloadcms/graphql/types'
export const getMyPosts = (GraphQL, payload) => {
return {
args: {},

28
docs/graphql/graphql-schema.mdx
View File

@@ -6,14 +6,20 @@ desc: Output your own GraphQL schema based on your collections and globals to a
keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
---
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.
In Payload the schema is controlled by your collections and globals. All you need to do is run the generate command and the entire schema will be created for you.
## Schema generation script
Run the following command in a Payload project to generate your project's GraphQL schema from Payload:
Install `@payloadcms/graphql` as a dev dependency:
```bash
pnpm add @payloadcms/graphql --save-dev
```
payload generate:graphQLSchema
Run the following command to generate the schema:
```bash
pnpm payload-graphql generate:schema
```
## Custom Field Schemas
@@ -24,7 +30,7 @@ For `array`, `block`, `group` and named `tab` fields, you can generate top level
{
type: 'group',
name: 'meta',
interfaceName: 'SharedMeta', <-- here!!
interfaceName: 'SharedMeta', // highlight-line
fields: [
{
name: 'title',
@@ -41,13 +47,13 @@ For `array`, `block`, `group` and named `tab` fields, you can generate top level
will generate:
```ts
// a top level reusable type!!
// A top level reusable type will be generated
type SharedMeta {
title: String
description: String
}
// example usage inside collection schema
// And will be referenced inside the generated schema
type Collection1 {
// ...other fields
meta: SharedMeta
@@ -64,16 +70,18 @@ The above example outputs all your definitions to a file relative from your payl
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.
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.
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:
If this applies to you, create an NPM script to make generating types easier:
```json
// package.json
{
"scripts": {
"generate:graphQLSchema": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload generate:graphQLSchema"
"generate:graphQLSchema": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload-graphql generate:schema"
}
}
```
Now you can run `yarn generate:graphQLSchema` to easily generate your schema.
Now you can run `pnpm generate:graphQLSchema` to easily generate your schema.

44
docs/graphql/overview.mdx
View File

@@ -29,7 +29,7 @@ At the top of your Payload config you can define all the options to manage Graph
Everything that can be done to a Collection via the REST or Local API can be done with GraphQL (outside of uploading files, which is REST-only). If you have a collection as follows:
```ts
import { CollectionConfig } from 'payload/types';
import type { CollectionConfig } from 'payload'
export const PublicUser: CollectionConfig = {
slug: 'public-users',
@@ -44,32 +44,32 @@ export const PublicUser: CollectionConfig = {
| Query Name | Operation |
| ------------------ | ------------------- |
| **`PublicUser`** | `findByID` |
| **`PublicUsers`** | `find` |
| **`countPublicUsers`** | `count` |
| **`mePublicUser`** | `me` auth operation |
| `PublicUser` | `findByID` |
| `PublicUsers` | `find` |
| `countPublicUsers` | `count` |
| `mePublicUser` | `me` auth operation |
**And the following mutations:**
| Query Name | Operation |
| ------------------------------ | ------------------------------- |
| **`createPublicUser`** | `create` |
| **`updatePublicUser`** | `update` |
| **`deletePublicUser`** | `delete` |
| **`forgotPasswordPublicUser`** | `forgotPassword` auth operation |
| **`resetPasswordPublicUser`** | `resetPassword` auth operation |
| **`unlockPublicUser`** | `unlock` auth operation |
| **`verifyPublicUser`** | `verify` auth operation |
| **`loginPublicUser`** | `login` auth operation |
| **`logoutPublicUser`** | `logout` auth operation |
| **`refreshTokenPublicUser`** | `refresh` auth operation |
| `createPublicUser` | `create` |
| `updatePublicUser` | `update` |
| `deletePublicUser` | `delete` |
| `forgotPasswordPublicUser` | `forgotPassword` auth operation |
| `resetPasswordPublicUser` | `resetPassword` auth operation |
| `unlockPublicUser` | `unlock` auth operation |
| `verifyPublicUser` | `verify` auth operation |
| `loginPublicUser` | `login` auth operation |
| `logoutPublicUser` | `logout` auth operation |
| `refreshTokenPublicUser` | `refresh` auth operation |
## Globals
Globals are also fully supported. For example:
```ts
import { GlobalConfig } from 'payload/types';
import type { GlobalConfig } from 'payload';
const Header: GlobalConfig = {
slug: 'header',
@@ -83,13 +83,13 @@ const Header: GlobalConfig = {
| Query Name | Operation |
| ------------ | --------- |
| **`Header`** | `findOne` |
| `Header` | `findOne` |
**And the following mutation:**
| Query Name | Operation |
| ------------------ | --------- |
| **`updateHeader`** | `update` |
| `updateHeader` | `update` |
## Preferences
@@ -99,14 +99,14 @@ User [preferences](/docs/admin/overview#preferences) for the admin panel are als
| Query Name | Operation |
| ---------------- | --------- |
| **`Preference`** | `findOne` |
| `Preference` | `findOne` |
**And the following mutations:**
| Query Name | Operation |
| ---------------------- | --------- |
| **`updatePreference`** | `update` |
| **`deletePreference`** | `delete` |
| `updatePreference` | `update` |
| `deletePreference` | `delete` |
## GraphQL Playground
@@ -119,7 +119,7 @@ You can even log in using the `login[collection-singular-label-here]` mutation t
<br />
To see more regarding how the above queries and mutations are used, visit your GraphQL playground
(by default at
[http://localhost:3000/api/graphql-playground](http://localhost:3000/api/graphql-playground))
[`${SERVER_URL}/api/graphql-playground`](http://localhost:3000/api/graphql-playground))
while your server is running. There, you can use the "Schema" and "Docs" buttons on the right to
see a ton of detail about how GraphQL operates within Payload.
</Banner>

2
packages/graphql/src/exports/types.ts
View File

@@ -1 +1,3 @@
export { GraphQLJSON, GraphQLJSONObject } from '../packages/graphql-type-json/index.js'
export { buildPaginatedListType } from '../schema/buildPaginatedListType.js'
export { default as GraphQL } from 'graphql'

4
packages/graphql/src/schema/buildPaginatedListType.ts
View File

@@ -1,6 +1,6 @@
import { GraphQLBoolean, GraphQLInt, GraphQLList, GraphQLObjectType } from 'graphql'
const buildPaginatedListType = (name, docType) =>
export const buildPaginatedListType = (name, docType) =>
new GraphQLObjectType({
name,
fields: {
@@ -19,5 +19,3 @@ const buildPaginatedListType = (name, docType) =>
totalPages: { type: GraphQLInt },
},
})
export default buildPaginatedListType

2
packages/graphql/src/schema/initCollections.ts
View File

@@ -37,7 +37,7 @@ import { updateResolver } from '../resolvers/collections/update.js'
import formatName from '../utilities/formatName.js'
import { buildMutationInputType, getCollectionIDType } from './buildMutationInputType.js'
import { buildObjectType } from './buildObjectType.js'
import buildPaginatedListType from './buildPaginatedListType.js'
import { buildPaginatedListType } from './buildPaginatedListType.js'
import { buildPolicyType } from './buildPoliciesType.js'
import buildWhereInputType from './buildWhereInputType.js'

2
packages/graphql/src/schema/initGlobals.ts
View File

@@ -16,7 +16,7 @@ import updateResolver from '../resolvers/globals/update.js'
import formatName from '../utilities/formatName.js'
import { buildMutationInputType } from './buildMutationInputType.js'
import { buildObjectType } from './buildObjectType.js'
import buildPaginatedListType from './buildPaginatedListType.js'
import { buildPaginatedListType } from './buildPaginatedListType.js'
import { buildPolicyType } from './buildPoliciesType.js'
import buildWhereInputType from './buildWhereInputType.js'