# @flatfile/plugin-graphql-schema

> A plugin for converting GraphQL to Flatfile blueprint.

Latest version **1.5.3** (published 2025-02-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install @flatfile/plugin-graphql-schema
pnpm add @flatfile/plugin-graphql-schema
yarn add @flatfile/plugin-graphql-schema
bun add @flatfile/plugin-graphql-schema
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.5.3 |
| Published | 2025-02-21 |
| First published | 2024-04-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 18 |
| Dependencies | 4 |
| Unpacked size | 72.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Flatfile, Inc. |
| Maintainers | sarocu, dboskovic, nate.ferrero, jmmander, madmandrit, bangarang, carlbrugger, flatfileinfra, flatderek, bigcountrycrane, flatfilecolin, alnoor, rjhyde, sambarrowclough, meritmalling, mmccooyyy, hjordan1990 |

## Links

- npm: https://www.npmjs.com/package/@flatfile/plugin-graphql-schema
- Repository: https://github.com/FlatFilers/flatfile-plugins
- Homepage: https://github.com/FlatFilers/flatfile-plugins#readme
- Issues: https://github.com/FlatFilers/flatfile-plugins/issues
- npm.io page: https://npm.io/package/@flatfile/plugin-graphql-schema

## Dependencies (4)

- [graphql](https://npm.io/package/graphql.md) ^16.8.1
- [change-case](https://npm.io/package/change-case.md) ^5.4.3
- [cross-fetch](https://npm.io/package/cross-fetch.md) ^4.0.0
- [@flatfile/plugin-space-configure](https://npm.io/package/@flatfile/plugin-space-configure.md) ^0.10.0

## Recent versions

- 1.5.3 (latest) — 2025-02-21
- 1.5.2 — 2025-02-19
- 1.5.1 — 2024-12-19
- 1.5.0 — 2024-11-07
- 1.4.0 — 2024-10-29
- 1.3.1 — 2024-10-03
- 1.3.0 — 2024-09-24
- 1.2.2 — 2024-04-30
- 1.2.1 — 2024-04-26
- 1.2.0 — 2024-04-23
- 1.1.2 — 2024-04-17
- 1.1.1 — 2024-04-17
- 1.1.0 — 2024-04-12

## README

# @flatfile/plugin-graphql-schema

This package automatically converts GraphQL to the Flatfile Blueprint, a powerful DDL (Data Definition Language) created by Flatfile with a focus on validation and data preparation.

## Get Started

```bash
npm install @flatfile/plugin-graphql-schema
```

### Example Sources
Pass a URL to a GraphQL endpoint
```
listener.use(
  configureSpaceGraphQL(
    {
      workbooks: [
        {
          name: 'GraphQL Workbook',
          source: 'https://spacex-production.up.railway.app/',
        },
      ],
    }
  )
)
```

Pass a function that returns a GraphQL schema
```
listener.use(
  configureSpaceGraphQL(
    {
      workbooks: [
        {
          name: 'GraphQL Workbook',
          source: (event: FlatfileEvent) => {
            const characterInterface = new GraphQLInterfaceType({
              name: 'Character',
              fields: { name: { type: GraphQLString } },
            })

            const humanType = new GraphQLObjectType({
              name: 'Human',
              interfaces: [characterInterface],
              fields: { name: { type: GraphQLString } },
            })

            const droidType = new GraphQLObjectType({
              name: 'Droid',
              interfaces: [characterInterface],
              fields: { name: { type: GraphQLString } },
            })

            const schema = new GraphQLSchema({
              query: new GraphQLObjectType({
                name: 'Query',
                fields: {
                  hero: { type: characterInterface },
                },
              }),
              // Since this schema references only the `Character` interface it's
              // necessary to explicitly list the types that implement it if
              // you want them to be included in the final schema.
              types: [humanType, droidType],
            })
            return schema
          },
        },
      ],
    }
  )
)
```

Pass an SDL string
```
listener.use(
  configureSpaceGraphQL(
    {
      workbooks: [
        {
          name: 'GraphQL Workbook',
          source: fs.readFileSync(
            path.join(__dirname, 'sample.graphql'),
            'utf8'
          ),
        },
      ],
    }
  )
)
```

### Example Sheet Filtering
Providing sheets will filter the schema to only generate the sheets for GraphQL objects that match the provided sheet slugs. 
```
listener.user(
  configureSpaceGraphQL(
    {
      workbooks: [
        {
          name: 'GraphQL Workbook',
          source: 'https://spacex-production.up.railway.app/',
          sheets: [{ slug: 'Capsule' }],
        },
      ],
    }
  )
)
```

### Advanced Example
```
listener.use(
  configureSpaceGraphQL(
    {
      workbooks: [
        {
          name: 'GraphQL Workbook',
          source: 'https://spacex-production.up.railway.app/',
          sheets: [
            {
              name: 'Capsules',
              slug: 'Capsule',
              actions: [
                {
                  operation: 'dedupeEmail',
                  mode: 'background',
                  label: 'Dedupe emails',
                  description: 'Remove duplicate emails',
                },
              ],
            }
          ],
        },
      ],
      space: {
        metadata: {
          theme: {
            root: {
              primaryColor: 'black',
            },
            sidebar: {
              logo: 'https://images.ctfassets.net/hjneo4qi4goj/33l3kWmPd9vgl1WH3m9Jsq/13861635730a1b8af383a8be8932f1d6/flatfile-black.svg',
            },
          },
        },
      },
      documents: [
        {
          title: 'Welcome',
          body: `<div>
          <h1 style="margin-bottom: 36px;">Welcome!</h1>
          <h2 style="margin-top: 0px; margin-bottom: 12px;">To get started, follow these steps:</h2>
          <h2 style="margin-bottom: 0px;">1. Step One</h2>
          <p style="margin-top: 0px; margin-bottom: 8px;">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
          <h2 style="margin-bottom: 0px;">2. Step Two</h2>
          <p style="margin-top: 0px; margin-bottom: 8px;">Consectetur libero id faucibus nisl tincidunt eget. Pellentesque elit eget gravida cum sociis natoque penatibus et. Tempor orci eu lobortis elementum nibh.</p>
          </div>`,
        },
      ],
    },
    async (event, workbookIds, tick) => {
      const { spaceId } = event.context
      console.log('Space configured', { spaceId, workbookIds })
      await tick(99, 'Space configured')
    }
  )
)
```

Follow [this guide](https://flatfile.com/docs/plugins/schemas/convert-graphql) to learn how to use the plugin.

---
_Source: https://npm.io/package/@flatfile/plugin-graphql-schema · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._