Multi-Schema Mode 2024/04/26

In our previous minor devlog we talked about the CLI and our new Turbo Mode. In v1.6.0 and our CLI releases up to it since then, we're further polishing and working on the CLI, but we're also here to introduce Multi-Schema Support!

Upgrading packages

To make sure you get the best experience, don't forget to also upgrade to @0no-co/graphqlsp@^0.12.0.

One more schema, please

When creating gql.tada we knew we'd eventually have to work towards multi-schema support.

Increasingly in codebases, projects now consume a GraphQL API on the back-end while also providing a GraphQL API to the front-end. When you set up gql.tada in a monorepo for your front-end apps with your own GraphQL API, that used to be it - gql.tada could only support one schema at a time and you were unable to consume more GraphQL APIs, even if those were consumed on the back-end.

Today, we're releasing multi-schema support to solve this problem. Instead of loading a single schema into gql.tada, you can now load multiple!

Configuring multiple schemas

We support multiple options to configure gql.tada and @0no-co/graphqlsp. These configuration options are all now considered to be per-schema options, namely:

• schema
• tadaOutputLocation
• tadaTurboLocation
• tadaPersistedLocation

Once you start adding a second GraphQL schema, you can move these options onto a schemas array. You'll need to give each schema its own name property however, so they can be identified in the CLI and in your editor.

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "plugins": [
      {
        "name": "@0no-co/graphqlsp",
        "schemas": [
          {
            "name": "my-api",
            "schema": "./schema.graphql",
            "tadaOutputLocation": "./src/graphql-env.d.ts"
          },
          {
            "name": "my-cloudflare-api",
            "schema": "./cloudflare.graphql",
            "tadaOutputLocation": "./src/cloudflare-env.d.ts"
          }
        ]
      }
    ]
  }
}

We've moved around our reference documentation and have a new "Config Format" page to reflect the configuration changes in this release.

Learn more about the Config Format

Once you've set up multiple schemas, you need to set up gql.tada manually by instantiating initGraphQLTada() to create a graphql function for each schema separately.

Installation

Learn how to set up gql.tada manually

API Reference

Learn more about the initGraphQLTada() function

You will have to set up each schema separately; For our example above, we'd set the following file up twice, once for ./src/graphql-env.d.ts and once for ./src/cloudflare-env.d.ts.

import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './graphql/graphql-env.d.ts';

export const graphql = initGraphQLTada<{
  introspection: introspection;
}>();

export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
export { readFragment } from 'gql.tada';

After setting up multiple graphql functions, each can then be used for their corresponding schema. The CLI and GraphQLSP will give you appropriate type hints and output for the corresponding schema you've set up.

Vue and Svelte

As of right now, we unfortunately can't support Vue and Svelte via the default TypeScript language server, so GraphQLSP can't give you hints, auto-completions, and its other features in .vue and .svelte files.

However, looking over at the Volar project, we realised that this doesn't mean we can't support .vue and .svelte single-file components at all.

In v1.2.0 of the CLI, we added experimental support for .vue and .svelte support. This is exclusive to the CLI. While you'll miss out on auto-completions and type-hints for GraphQL documents, you'll still be able to use gql.tada's typings and the gql.tada CLI to lint your project.

Commands like gql.tada check will now detect .vue and .svelte files, transpile them to TypeScript, and automatically provide line-accurate diagnostics for them.