Adding your own Queries and Mutations

You can add your own GraphQL queries and mutations to FrogBot, making use of all the types that FrogBot has defined for you. To do so, add your queries and mutations to the main FrogBot Config as follows:

Config Path	Type	Default	Description
`graphQL.queries`	`(GraphQL, context) => Record<string, unknown>`	—	Returns an object of custom queries, keyed by query name.
`graphQL.mutations`	`(GraphQL, context) => Record<string, unknown>`	—	Returns an object of custom mutations, keyed by mutation name.

Both functions receive these arguments:

Argument	Type	Description
`GraphQL`	`typeof GraphQL`	FrogBot’s copy of the `graphql` package. Use it to build types instead of installing your own copy, because GraphQL types from two copies of the package don’t work together.
`context`	`object`	The GraphQL types FrogBot generated for your config, plus your sanitized `config`. See the table below.

context contains:

Property	Type	Description
`collections`	`Record<string, Collection>`	Each collection, keyed by slug. `context.collections.posts.graphQL.type` is the type of a `posts` document.
`config`	`SanitizedConfig`	The sanitized FrogBot config.
`Query`	`{ name: string; fields: Record<string, any> }`	The root query type FrogBot built, including every generated query.
`Mutation`	`{ name: string; fields: Record<string, any> }`	The root mutation type FrogBot built, including every generated mutation.
`types`	`object`	Generated types for named fields: `arrayTypes`, `blockTypes`, `blockInputTypes`, `groupTypes`, `tabTypes`, and the optional `localeInputType` and `fallbackLocaleInputType`.
`globals`	`object`	Always empty, because FrogBot has no globals.

Each returned entry is a GraphQL field config with type, optional args, and resolve. FrogBot attaches req.frogbot before each resolve runs.

Return value

Both graphQL.queries and graphQL.mutations functions should return an object with properties equal to your newly written GraphQL queries and mutations.

Example

import type { FrogBotConfig } from 'frogbot'

export const graphQL: FrogBotConfig['graphQL'] = {
  queries: (GraphQL) => {
    return {
      MyCustomQuery: {
        type: new GraphQL.GraphQLObjectType({
          name: 'MyCustomQuery',
          fields: {
            text: {
              type: GraphQL.GraphQLString,
            },
            someNumberField: {
              type: GraphQL.GraphQLFloat,
            },
          },
        }),
        args: {
          argNameHere: {
            type: new GraphQL.GraphQLNonNull(GraphQL.GraphQLString),
          },
        },
        resolve: (_obj: unknown, args: { argNameHere: string }) => ({
          text: args.argNameHere,
          someNumberField: args.argNameHere.length,
        }),
      },
    }
  },
}

Pass graphQL to buildConfig in your FrogBot config.

Resolver function

In your resolver, make sure you set depth: 0 if you’re returning data directly from the Local API so that GraphQL can correctly resolve queries to nested values such as relationship data. Your function will receive four arguments you can make use of: Example

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

export const resolver = async (
  obj: unknown,
  args: Record<string, unknown>,
  context: { req: FrogBotRequest },
  info: GraphQL.GraphQLResolveInfo,
) => {
  const { totalDocs } = await context.req.frogbot.count({
    collection: 'users',
    overrideAccess: false,
    req: context.req,
  })

  return totalDocs
}

obj The previous object. Not very often used and usually discarded. args The available arguments from your query or mutation will be available to you here, these must be configured via the custom operation first. context An object containing the incoming request as req, the same FrogBotRequest a custom endpoint receives. Use req.frogbot to call the Local API and req.user to read the signed-in user. Pass req to Local API calls so they run in the same request and see the same user. info Contextual information about the currently running GraphQL operation. You can get schema information from this as well as contextual information about where this resolver function is being run.

Types

We’ve exposed a few types and utilities to help you extend the API further. FrogBot uses the GraphQL.js package for which you can view the full list of available types in the official documentation. GraphQLJSON & GraphQLJSONObject

import { GraphQLJSON, GraphQLJSONObject } from '@frogbotai/graphql/types'

GraphQL You can directly import the GraphQL package used by FrogBot, most useful for typing.

import { GraphQL } from '@frogbotai/graphql/types'

For queries, mutations and handlers make sure you use the GraphQL and context values provided via arguments.

buildPaginatedListType This is a utility function that allows you to build a new GraphQL type for a paginated result similar to the FrogBot’s generated schema. It takes in two arguments, the first for the name of this new schema type and the second for the GraphQL type to be used in the docs parameter. Example

import { buildPaginatedListType } from '@frogbotai/graphql/types'
import type { FrogBotConfig, FrogBotRequest } from 'frogbot'

export const graphQL: FrogBotConfig['graphQL'] = {
  queries: (GraphQL, context) => ({
    RecentUsers: {
      args: {},
      resolve: (_obj: unknown, _args: unknown, { req }: { req: FrogBotRequest }) =>
        req.frogbot.find({
          collection: 'users',
          depth: 0,
          limit: 10,
          overrideAccess: false,
          req,
          sort: '-createdAt',
        }),
      type: buildPaginatedListType('RecentUsers', context.collections['users'].graphQL!.type),
    },
  }),
}

The name of your new type has to be unique. context.collections[slug].graphQL If you want to extend more of the provided API then the graphQL object on your collection slug will contain additional types to help you re-use code for types, mutations and queries.

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

export type CollectionGraphQLTypes = {
  type: GraphQL.GraphQLObjectType
  paginatedType: GraphQL.GraphQLObjectType
  JWT: GraphQL.GraphQLObjectType
  versionType: GraphQL.GraphQLObjectType
  whereInputType: GraphQL.GraphQLInputObjectType
  mutationInputType: GraphQL.GraphQLNonNull<GraphQL.GraphQLInputObjectType>
  updateMutationInputType: GraphQL.GraphQLNonNull<GraphQL.GraphQLInputObjectType>
}

Best practices

There are a few ways to structure your code, we recommend using a dedicated graphql directory so you can keep all of your logic in one place. You have total freedom of how you want to structure this but a common pattern is to group functions by type and with their resolver. Example

src/graphql
---- queries/
     index.ts
    -- myCustomQuery/
       index.ts
       resolver.ts

---- mutations/

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Adding your own Queries and Mutations

Return value

Example

Resolver function

Types

Best practices

​Return value

​Example

​Resolver function

​Types

​Best practices

Return value

Example

Resolver function

Types

Best practices