Grafbase Configuration

You will use the file grafbase/grafbase.config.ts (or grafbase/schema.graphql if using SDL) inside of your project to configure your backend. This file is crucial as it generates everything needed to deploy your GraphQL Edge Gateway.

This file is used to configure the following:

Scaffold a new config you can use the Grafbase CLI inside of a new or existing project:

npx grafbase init

The example below shows how to:

  • Connect an API using OpenAPI
  • Cache all queries
  • Restrict API access to signed in users
  • Connect a custom GraphQL mutation resolver
import { auth, config, connector, g } from '@grafbase/sdk'

const clerk = auth.OpenIDConnect({
  issuer: g.env('ISSUER_URL')

const shopify = connector.GraphQL('Shopify', {
  url: g.env('SHOPIFY_STORE_API_URL'),
  headers: headers => {


const input = g.input('AuthInput', { email:, password: g.string() })

g.mutation('login', {
  args: { input: g.inputRef(input) },
  returns: g.string(),
  resolver: 'login'

export default config({
  schema: g,
  cache: {
    rules: [
        maxAge: 60,
        types: 'Query'
  auth: {
    providers: [clerk],
    rules: rules => {

You can use use environment variables set using the CLI or in your project settings inside of your project's configuration.

import { connector, g } from '@grafbase/sdk'

const contentful = connector.GraphQL('Contentful', {
  url: g.env('CONTENTFUL_API_URL'),
  headers: headers => {
    headers.set('Authorization', `Bearer ${g.env('CONTENTFUL_API_URL')}`)


You should use the Quickstart CLI command to generate a new Grafbase config.

You can manually install @grafbase/sdk using your preferred Node.js package manager if you have an existing project.

npm install @grafbase/sdk

Grafbase also supports configuring your project using the GraphQL Schema Definition Language using custom directives.

You will need to create the file grafbase/schema.graphql instead of grafbase/grafbase.config.ts.

Was this page helpful?