GraphQL Overview

In addition to its REST and Local APIs, FrogBot ships with a fully featured and extensible GraphQL API. The GraphQL API is served at /api/graphql once you add its route files (see Enable GraphQL). You can customize this URL by specifying routes in your FrogBot config. The labels you provide for your Collections are used to name the GraphQL types that are created to correspond to your config. Special characters and spaces are removed.

GraphQL Clients

You can use any GraphQL client with FrogBot’s GraphQL endpoint. Here are a few popular packages:

graphql-request - a very lightweight GraphQL client
@apollo/client - an industry-standard GraphQL client with lots of nice features

GraphQL Options

At the top of your FrogBot Config you can define all the options to manage GraphQL.

Option	Type	Default	Description
`disable`	`boolean`	`false`	Turns off the GraphQL API entirely.
`disableIntrospectionInProduction`	`boolean`	`true`	Rejects introspection queries when `NODE_ENV` is `production`. Set `false` to allow them.
`disablePlaygroundInProduction`	`boolean`	`true`	Turns off the GraphQL Playground when `NODE_ENV` is `production`. Set `false` to keep it. More
`maxComplexity`	`number`	`1000`	Highest complexity a request can have before it’s rejected. More
`mutations`	`(GraphQL, context) => Record<string, unknown>`	—	Custom mutations added to the schema. Resolvers receive `context.req` as a `FrogBotRequest`. More
`queries`	`(GraphQL, context) => Record<string, unknown>`	—	Custom queries added to the schema. Resolvers receive `context.req` as a `FrogBotRequest`. More
`schemaOutputFile`	`string`	`schema.graphql` in the working directory	File `frogbot-graphql generate:schema` writes to. More
`validationRules`	`(args: ExecutionArgs) => ValidationRule[]`	—	Extra GraphQL validation rules applied to every request. More

Collections

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:

import type { CollectionConfig } from 'frogbot'

export const PublicUser: CollectionConfig = {
  slug: 'public-users',
  auth: true,
  fields: [{ name: 'name', type: 'text' }],
}

FrogBot will automatically open up the following queries:

Query Name	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

GraphQL Playground

Once you add the playground route (see Enable GraphQL), GraphQL Playground is available in development and disabled in production. You can enable it in production by passing graphQL.disablePlaygroundInProduction a false setting in the main FrogBot Config. You can even log in using the login[collection-singular-label-here] mutation to use the Playground as an authenticated user.

To see more regarding how the above queries and mutations are used, visit your GraphQL playground (by default at ${SERVER_URL}/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 FrogBot.

Custom Validation Rules

You can add custom validation rules to your GraphQL API by defining a validationRules function in your FrogBot Config. This function should return an array of Validation Rules that will be applied to all incoming queries and mutations.

import { GraphQL } from '@frogbotai/graphql/types'
import type { FrogBotConfig } from 'frogbot'

const NoProductionIntrospection: GraphQL.ValidationRule = (context) => ({
  Field(node) {
    if (process.env.NODE_ENV === 'production') {
      if (node.name.value === '__schema' || node.name.value === '__type') {
        context.reportError(
          new GraphQL.GraphQLError(
            'GraphQL introspection is not allowed, but the query contained __schema or __type',
            { nodes: [node] },
          ),
        )
      }
    }
  },
})

export const graphQL: FrogBotConfig['graphQL'] = {
  validationRules: () => [NoProductionIntrospection],
}

Pass graphQL to buildConfig in your FrogBot config.

Query complexity limits

FrogBot comes with a built-in query complexity limiter to prevent abusive queries from slowing down your server.

Field complexity

You can define custom complexity for relationship, upload and join type fields. This is useful if you want to assign a higher complexity to a field that is more expensive to resolve. This can help prevent users from running queries that are too complex.

import type { CollectionConfig } from 'frogbot'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    {
      name: 'authors',
      type: 'relationship',
      relationTo: 'users',
      hasMany: true,
      graphQL: {
        complexity: 100,
      },
    },
  ],
}

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

GraphQL Clients

GraphQL Options

Collections

GraphQL Playground

Custom Validation Rules

Query complexity limits

Field complexity

​GraphQL Clients

​GraphQL Options

​Collections

​GraphQL Playground

​Custom Validation Rules

​Query complexity limits

​Field complexity

GraphQL Clients

GraphQL Options

Collections

GraphQL Playground

Custom Validation Rules

Query complexity limits

Field complexity