GraphQL Code Generator v3 Roadmap

See original GitHub issue

This page is synced automatically from The Guild’s Notion Notion page URL: https://www.notion.so/GraphQL-Code-Generator-v3-Roadmap-91923bfb2dee48eaa0d6a77666429968

At The Guild, we’ve decided to work as much as possible in public; that’s why we are opening the roadmaps for all of our projects.

The goals for this are:

So you will know what we are working on, what we see as a higher priority, and know what to expect from our projects in the future
So you can share your opinions and thoughts about what we do and influence our decisions
So you can join us and contribute to our efforts!

Before laying down the roadmap of GraphQL Code Generator v3, we would like to thank all of you for being so many who use codegen daily and for contributing to making it such a complete project! 🚀

While some people judge that GraphQL is difficult, GraphQL Code Generator v3 aims to change that perspective by providing a unified configuration along with a smaller and simpler generated code.

By providing a unified package and configuration for all client-side use cases, all existing and future plugin alternatives will be moved to community repos.

Let’s now cover these changes in detail.

A unified configuration and package for all GraphQL clients

Most of the existing client-side plugins (typescript-react-apollo, typescript-react-query, etc) rely on the generation of hooks or SDKs that wrap the underlying GraphQL Client in a type-safe way.

However, the generation of hooks or SDK code brings many downsides:

an unnecessary increase of the final bundle size
misalignment between the generated hooks signature and the underlying GraphQL Client
inconsistencies of configuration options and preset compatibility across packages (ex: near-operation-file compatibility)

To make GraphQL code generation great and simple, the v3 version will introduce two major changes:

a new unique preset for all GraphQL clients, which include better developer experience, smaller bundle size, stronger typings, and easier-to-follow best practices
a TypeScript-first configuration file that will allow configuration autocompletion

Here is how you can already configure codegen for all GraphQL Clients:

import { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'http://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: []
    }
  }
}

export default config

The client preset comes with a simple opinionated configuration and a lightweight types-only generation.

To try the new client preset, please install the following dependencies:

yarn add graphql
yarn add -D typescript
yarn add -D @graphql-codegen/cli
yarn add -D @graphql-codegen/client-preset

First, start GraphQL Code Generator in watch mode:

yarn graphql-codegen --watch

Using GraphQL Code Generator will type your GraphQL Query and Mutations as you write them ⚡️

Now, each query or mutation written with the generated graphql() function will be automatically typed!

For example, with Apollo Client (React):

import React from 'react';
import { useQuery } from '@apollo/client';
import { graphql } from './gql/gql';

import Film from './Film';

// here, `allFilmsWithVariablesQueryDocument` is fully typed!
const allFilmsWithVariablesQueryDocument = graphql(/* GraphQL */ `
  query allFilmsWithVariablesQuery($first: Int!) {
    allFilms(first: $first) {
      edges {
        node {
          ...FilmItem
        }
      }
    }
  }
`);

function App() {
	// Most GraphQL Clients know how to deal with typed GraphQL documents,
	//   providing typed data and typed variables
  const { data } = useQuery(allFilmsWithVariablesQueryDocument, { variables: { first: 10 } });
  return (
    <div className="App">
      {data && <ul>{data.allFilms?.edges?.map((e, i) => e?.node && <Film film={e?.node} key={`film-${i}`} />)}</ul>}
    </div>
  );
}

export default App;

Thanks to work made to integrate TypeDocumentNode (the underlying plugin used by preset: client) with most of the popular GraphQL clients, you no longer need hooks or SDK, simple GraphQL documents works!

We believe that the preset: client approach is the way to get the best of TypeScript and GraphQL by:

reducing the size of the generated bundle
only the graphql() function needs to be imported (no type, hooks, document imports)
removing layers between your application and your chosen GraphQL Client
providing stronger typings that will stay aligned with your chosen GraphQL Client
offering you the best component isolation design by leveraging Fragment Masking

Finally, this new preset: client has been properly tested on all popular GraphQL clients across most frameworks:

React
- @apollo/client (since 3.2.0, not when using React Components (<Query>))
- @urql/core (since 1.15.0)
- @urql/preact (since 1.4.0)
- urql (since 1.11.0)
- graphql-request (since 5.0.0)
- react-query (with graphql-request@5.0.0)
- swr (with graphql-request@5.0.0)
- @urql/exchange-graphcache (since 3.1.11)
Svelte
- @urql/svelte (since 1.1.3)
Vue
- @vue/apollo-composable (since 4.0.0-alpha.13)
- villus (since 1.0.0-beta.8)
- @urql/vue (since 1.11.0)
Others
- graphql-js (since 15.2.0)
- graphql-request (since 5.0.0)

You will find demos and code examples for each of them in the examples/front-end/ folder of the codegen repository.

You will also find a complete guide for React and Vue in codegen documentation.

We aim for GraphQL Code Generator 3.0’s client preset to become the official way to generate GraphQL Types for front-end use cases, replacing all existing hook and SDK-based plugins.

For this reason, we encourage you to already give a try at the codegen v3 client preset (@graphql-codegen/client-presec) and provide feedback on this issue.

The v3 stable release will be shipped once sufficient feedback is posted.

Finally, while the GraphQL Code Generator 3.0 milestone aims to provide a unified front-end experience through the preset: client, the 3.x versions aim to fully rewrite the core packages of codegen.

Some core parts of codegen are more than 6 years old and need to be rewritten (optimized, simplified, and more).

We plan to incorporate the pending issues related to the core packages in this gradual 3.x milestones.

Introduction of the “community plugins”

Historically, all plugins were pushed to the https://github.com/dotansimha/graphql-code-generator repository, making it hard for us to review all contributions in a reasonable timeframe and to enforce consistency across all the options introduced in the different packages.

We believe that the best way to keep codegen extensible and improve the contribution experience at scale is to introduce the concept of community plugins.

A community plugin offers a feature-set that diverges from the preset: client or a plugin created by the community.

Soon, all the existing plugins part of the list below and all the future plugins created by the community will live in their dedicated repository:

@graphql-codegen/typescript-react-apollo
@graphql-codegen/typescript-graphql-request
@graphql-codegen/typescript-apollo-angular
@graphql-codegen/typescript-apollo-client-helpers
@graphql-codegen/typescript-react-query
@graphql-codegen/typescript-urql
@graphql-codegen/named-operations-object
@graphql-codegen/urql-introspection
@graphql-codegen/flow-resolvers
@graphql-codegen/typescript-vue-apollo
@graphql-codegen/typescript-rtk-query
@graphql-codegen/flow-operations
@graphql-codegen/typescript-msw
@graphql-codegen/typescript-mongodb
@graphql-codegen/typescript-type-graphql
@graphql-codegen/jsdoc
@graphql-codegen/typescript-vue-urql
@graphql-codegen/kotlin
@graphql-codegen/typescript-vue-apollo-smart-ops
@graphql-codegen/java
@graphql-codegen/c-sharp-operations
@graphql-codegen/hasura-allow-list
@graphql-codegen/typescript-stencil-apollo
@graphql-codegen/relay-operation-optimizer
@graphql-codegen/typescript-oclif
@graphql-codegen/java-resolvers
@graphql-codegen/java-apollo-android

All the above plugins will be eligible for repository ownership transfer based on relevant past contributions.

Of course, such a change will come with help from our side:

We will create a new “Create a plugin” guide that will provide complete information and guidelines (ex: publishing, codegen APIs, adding your plugin to the codegen hub)
Since each community plugin will live in its own repository, we will provide a proper Github repository template with building and publishing CI tools configured.

What about server-side plugins?

The 3.x milestones include some work on server-side plugins such as typescript-resolvers (ex: improving Federation support).

Milestones

Below are the details of the aforementioned plans for the 3.0 and 3.x milestones.

`3.0`

client preset
- Integrate with most of the GraphQL clients
  - graphql-request https://github.com/prisma-labs/graphql-request/pull/350/files
  - https://github.com/dotansimha/graphql-code-generator/issues/8061
  - Improve TypeScript support in libraries that already support TypedDocumentNode (variables should be required if there are required variables in the operation declaration and optional if there are none)
    - URQL
    - Apollo Client
  - React Query (works with graphql-request)
  - SWR (works with graphql-request)
  - Add support for AWS AppSync client
- Fix pending issues on gql-tag-operation-preset
  - https://github.com/dotansimha/graphql-code-generator/issues/8206
- canary release: https://github.com/dotansimha/graphql-code-generator/pull/8248
  - TypeScript config support
  - documents preset preconfiguration
  - opinionated plugins configuration
  - deprecate gql-tag-operations-preset in favor of the client-preset
- examples: https://github.com/dotansimha/graphql-code-generator/pull/8184
- https://github.com/dotansimha/graphql-code-generator/issues/8413
- Update documentation for front-end/GraphQL clients parts
  - Update graphql-request docs on their repo
    - https://github.com/prisma-labs/graphql-request/pull/392
  - Update Apollo Client docs
    - https://github.com/apollographql/apollo-client/pull/10173
  - Update URQL docs
    - https://github.com/FormidableLabs/urql/pull/2729
  - Update apollo-angular docs
    - → not enough time
  - Update SWR GraphQL documentation with a link to codegen doc
    - https://github.com/vercel/swr-site/pull/359
- official release 🚢
- better TypeScript/VSCode integration
  - Potential solution: https://github.com/dotansimha/graphql-code-generator/discussions/8345#discussioncomment-4028928
- create a Github template repository
- new documentation for creating a plugin
  - + updated contributing guidelines
- move all community plugins to a dedicated repository
  - move the related issues + communicate about new contribution guidelines
  - Reach out to potential people who want to support

`3.x`

preset: client improvements

Only generate actually used types
Support operation minification/compilation? (aka embed/re-invent relay-compiler) https://relay-compiler-repl.netlify.app/
- Support (parameterized) Fragment Arguments? https://github.com/graphql/graphql-spec/issues/204
“Client Controlled Nullability” support → https://github.com/dotansimha/graphql-code-generator/pull/8071
Create a TypedDocumentNode string alternative (TypedString) that does not require GraphQL AST on the Client (should be easily configurable within the preset)
https://tortilla-hq.slack.com/archives/CCVDM3NCD/p1659508122835199
https://github.com/dotansimha/graphql-code-generator/issues/7885
Refactor preset: client to not use the old plugins (get rid of actual core packages)

Future of codegen CLI

Better TypeScript config support
- get typed options (config) → WIP 🚧
https://github.com/dotansimha/graphql-code-generator/issues/8200
Allow generating outputs even if there are no documents (so you can still generate the gql function for getting started)
Better configuration
Performance
- https://github.com/dotansimha/graphql-code-generator/issues/5642
- Incremental builds (https://github.com/dotansimha/graphql-code-generator/pull/6142)
Remove graphql dependency
Better monorepo support?
- multi-project, etc.
- shareable configs? → (one codegen file versus many)

Back-end code generation issues

We will go over the following typescript-resolvers and graphql-modules pending plugins issues:

Issue Analytics

State:
Created a year ago
Reactions:52
Comments:55 (2 by maintainers)

Top GitHub Comments

13reactions

charlypolycommented, Aug 31, 2022

@franky47, thank you for sharing it!

We are also exploring options to still support .graphql files, we will keep you updated here.

6reactions

ilijaNLcommented, Sep 9, 2022

If it is going full TypeDocumentNode way (which I like), is it not better to go with a builder pattern approach. The builder can be full type safe and be generated from the introspection query. Additionally you need to generate the builder only initially and on schema change and not when adding new documents. Some open source projects which apply this principle:

In my opinion this provides best of the worlds. Small bundle size, no watchers necessary on frontend and much faster dev cycle. Additionally the builder can be scoped per context (think about hasura roles or public/private introspection results)

Top Results From Across the Web

Clement Demonchy sur LinkedIn : GraphQL Code Generator v3 ...

I am currently leading the GraphQL Code Generator v3 roadmap project, and, in this process, we are looking for feedback from the community...

Dotan Simha (@dotansimha) / Twitter

GraphQL Code Generator v3 Roadmap · Issue #8296 · dotansimha/graphql-code-generator. This page is synced automatically from The Guild's Notion Notion page ...

4. Install and configure GraphQL Code Generator - YouTube

Learn # GraphQL, In One WeekBuild a fullstack eCommerce application with GraphQL Yoga, Prisma, Planetscale, Next.js, Tailwind CSS, ...

GraphQL Code Generator - Saleor Tutorial

GraphQL Code Generator will automatically generate types representing all the commerce notions available in the Saleor API. It connects to a GraphQL endpoint ......

GraphQL | A query language for your API

By using a single evolving version, GraphQL APIs give apps continuous access to new features and encourage cleaner, more maintainable server code.