This plugin automates the creation of a Flatfile Space configuration by converting a GraphQL schema into a Flatfile Blueprint. It introspects a given GraphQL source—which can be a live endpoint URL, a static Schema Definition Language (SDL) string, or a GraphQL.js schema object—and generates corresponding Workbooks and Sheets.

The primary purpose is to significantly speed up the setup process for developers who need to import data that conforms to an existing GraphQL API. It maps GraphQL object types to Flatfile Sheets and their fields to Flatfile Fields, automatically handling scalar types, object relationships (as reference fields), and non-null constraints.

Use cases include:

  • Rapidly scaffolding a data importer for a headless CMS or backend service that exposes a GraphQL API
  • Creating a consistent data onboarding experience based on a single source of truth (the GraphQL schema)
  • Migrating data from other systems into an application with a GraphQL-based data model

​
Installation

Install the plugin using npm:

npm install @flatfile/plugin-graphql-schema

​
Configuration & Parameters

The plugin is configured via a setupFactory object passed to the configureSpaceGraphQL function.

​
Main Configuration

ParameterTypeRequiredDescription
workbooksPartialWorkbookConfig[]YesArray of workbook configuration objects. Each object generates one workbook.
spaceobjectNoConfiguration for the Space itself (e.g., metadata, themes).
documentsobject[]NoArray of document configurations to add to the Space.

​
PartialWorkbookConfig

ParameterTypeDefaultDescription
sourcestring | GraphQLSchema | functionRequiredGraphQL schema source - can be a URL, SDL string, GraphQLSchema object, or function returning a GraphQLSchema
sheetsPartialSheetConfig[]undefinedOptional array to filter and customize generated sheets
namestring'GraphQL Workbook'User-friendly name for the workbook

​
PartialSheetConfig

ParameterTypeDefaultDescription
slugstringRequiredSheet slug that must match a GraphQL object type name
namestringcapitalCase of GraphQL object nameUser-friendly name for the sheet

​
Usage Examples

​
Basic Usage

import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceGraphQL } from '@flatfile/plugin-graphql-schema'

const listener = FlatfileListener.create((listener) => {
  listener.on('**', (event) => {
    console.log(`Event: ${event.topic}`)
  })

  listener.use(
    configureSpaceGraphQL({
      workbooks: [
        {
          name: 'SpaceX Launches',
          source: 'https://spacex-production.up.railway.app/',
        },
      ],
    })
  )
})

​
Filtering Sheets

import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceGraphQL } from '@flatfile/plugin-graphql-schema'

const listener = FlatfileListener.create((listener) => {
  listener.use(
    configureSpaceGraphQL({
      workbooks: [
        {
          name: 'SpaceX Capsules',
          source: 'https://spacex-production.up.railway.app/',
          // Only generate a sheet for the 'Capsule' GraphQL object type
          sheets: [{ slug: 'Capsule' }],
        },
      ],
    })
  )
})

​
Advanced Configuration

import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceGraphQL } from '@flatfile/plugin-graphql-schema'

const listener = FlatfileListener.create((listener) => {
  listener.use(
    configureSpaceGraphQL(
      {
        workbooks: [
          {
            name: 'Custom SpaceX Workbook',
            source: 'https://spacex-production.up.railway.app/',
            sheets: [
              {
                name: 'Capsules', // Custom sheet name
                slug: 'Capsule',
                actions: [
                  {
                    operation: 'dedupe',
                    mode: 'background',
                    label: 'Deduplicate Records',
                  },
                ],
              },
            ],
          },
        ],
        space: {
          metadata: {
            theme: {
              root: { primaryColor: 'blue' },
            },
          },
        },
      },
      async (event, workbookIds, tick) => {
        const { spaceId } = event.context
        console.log('Space configured successfully!', { spaceId, workbookIds })
        await tick(100, 'Configuration complete')
      }
    )
  )
})

​
Using Local Schema File

import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceGraphQL } from '@flatfile/plugin-graphql-schema'
import fs from 'fs'
import path from 'path'

const listener = FlatfileListener.create((listener) => {
  // Read a GraphQL schema from a local file
  const schemaSDL = fs.readFileSync(
    path.join(__dirname, 'schema.graphql'),
    'utf8'
  )

  listener.use(
    configureSpaceGraphQL({
      workbooks: [
        {
          name: 'My Local Schema Workbook',
          source: schemaSDL,
        },
      ],
    })
  )
})

​
Troubleshooting

​
Missing Sheets or Fields

Check the console logs for messages about “unsupported” field types or missing reference tables. The plugin logs warnings for non-critical issues.

​
Invalid GraphQL Source

Ensure that any URL provided in the source option points to a valid, publicly accessible GraphQL endpoint that responds to introspection queries.

​
Sheet Filtering Issues

When using the sheets filter, verify that the slug for each sheet configuration exactly matches the name of the corresponding GraphQL object type.

​
Reference Field Problems

If reference fields are not working, confirm that the sheet being referenced is also being generated (i.e., it’s included in your sheets filter or the filter is omitted entirely).

​
Notes

​
Default Behavior

By default, the plugin introspects the entire GraphQL schema from the provided source. It creates one sheet for each GraphQL OBJECT type, excluding standard types like Query, Mutation, Subscription, and internal types (those starting with __).

Field Type Mapping:

  • GraphQL scalar types are mapped to Flatfile field types (Int → number, String → string)
  • GraphQL object types are mapped to Flatfile reference fields
  • If a GraphQL field is NON_NULL, a required constraint is added

​
Supported Field Types

The plugin currently supports GraphQL SCALAR, OBJECT, and NON_NULL types. Other GraphQL types like LIST, UNION, INTERFACE, and ENUM are not explicitly supported and will be skipped during sheet generation.

​
Reference Field Generation

For a reference field to be created correctly, the corresponding GraphQL object type must also be generated as a sheet in the same workbook. The plugin automatically selects the first non-reference field from the referenced sheet to use as the relationship key.

​
Error Handling

The plugin uses console logging to provide feedback. Critical errors, such as failure to fetch or parse the GraphQL schema, will throw an exception, causing the configureSpace job to fail.