RFC: Sequential Execution & Output Hand-off Between GraphQL Codegen Plugins/Presets

[eddeee888]

Summary

Plugins configured under a single generates entry currently run in parallel and have no way to pass output, AST, or metadata to one another. This RFC lays out the problem, two candidate designs for letting plugins (and presets) hand off state to downstream stages, with a recommendation for which to adopt.

Problem

• Some use cases require extending a plugin's output, or "handing off" transformation/output/metadata from one plugin to the next e.g. a types map, a list of scalars, resolved config, etc.
• Today, all plugins in a plugins: [] array run independently and their string outputs are simply concatenated, there is no data channel between them.
• The current workaround is for plugins/presets to bypass the plugin pipeline entirely and call plugin functions manually, threading extra metadata by hand. For example, the Server Preset has to invoke typescript and typescript-resolvers itself in order to share the type map between them, rather than composing them declaratively.

This workaround only exists inside the Server Preset source code. Ordinary users writing a plain plugins: [] list have no equivalent capability; if two plugins need to share data, the only option is to fork one into a preset.

Goals

• Let plugins/presets consume the output and/or structured metadata produced by a plugin that ran earlier in the same output target.
• Let plugins/presets be expressed as compositions of ordinary plugins instead of writing bespoke orchestration code.
• Let a stage transform input it receives (schema, documents, or a prior stage's output) before passing it on, not just append to it.
• Preserve backward compatibility for existing configs where plugins are independent.

Use Cases

Three concrete cases motivate this RFC. Each reflects the same underlying gap: no way to pass data or transformations between generation steps.

1. Server Preset: types → resolvers

Need: resolver signatures depend on the TypeScript types codegen already generated for the schema (so Resolvers<TContext> is typed against the right shape), not just the raw SDL.

Current approach: the "wrapper". Server Preset manually invokes the typescript and typescript-resolvers plugins' functions, captures the type map it returns, and passes that map directly into subsequent preset core logic. This effectively re-implements a small, private plugin runner inside the preset's own source just to get two plugins to talk to each other. None of this orchestration is reusable.

flowchart TD
    SDL["GraphQL Schema / SDL"] --> Preset

    subgraph Preset["Server Preset (the wrapper)"]
        direction LR
        TS["typescript plugin<br/>generates TS types"]
        TSR["typescript-resolvers plugin<br/>generates resolvers"]
        TS -- "type map<br/>passed manually, in JS" --> TSR
    end

    Preset --> Out["types.generated.ts"]

Loading

Cost: this wrapper is bespoke per preset and invisible to config authors. A user who wants the same types→resolvers hand-off outside this one preset has no path to it short of writing their own preset in JS.

2. Client Preset → Compiler build-time compilation

Need: the Client Preset optimizes graphql(...) tagged-template calls in application source by resolving them to precomputed document references at build time, instead of parsing GraphQL strings at runtime.

Current approach: this compilation runs entirely outside codegen, as a babel or SWC plugin wired into the application's own bundler, a second toolchain integration the user installs and configures separately from codegen.ts.

flowchart LR
    Schema["GraphQL Schema"] --> ClientPreset["Client Preset"]
    ClientPreset --> Output["Codegen output<br/>graphql() calls + types"]
    Output --> Post["Post-processor<br/>(Babel / SWC plugin)"]
    Post --> Dist["Final bundle<br/>/dist"]

Loading

Cost: everything from "Post-processor" onward runs in the application's own build, not codegen's. This has a few friction points for users:

• users who use unsupported bundlers do not get the benefits
• there's no easy way to assert on the final /dist output from within codegen's own test suite, making it flaky and hard to test

Note

The Server Preset has proven that it's possible to use the TypeScript compiler API within codegen to codemod the generated output, the role babel or SWC is playing here.

3. Plugin → Plugin: Other use cases

Need: additional use cases have surfaced where it makes sense to run plugins sequentially:

• Transforming schema in one plugin, before passing it to the next.
• Augmenting the output of an existing plugin e.g. typescript-operations generates client types, but custom directives might need to change those types.

Current approach:

• Transforming schema currently requires a separate codegen run before the main one. This is a heavy setup, and watch mode doesn't work well across two separate runs.
• Augmenting typescript-operations output is very hard at the moment: client-specific use cases leak into the base plugin, such as apolloUnmask.

Options

Option 1: Sequential Stages

Change the config shape so a single output target can declare an ordered list of stages. Stages execute top to bottom, and each entry is a stage, either a plugin stage (runs plugins, produces content/meta), or a preset stage that delegates to an existing named preset. Each stage may transform input such as the schema or documents and pass it on to the next.

Example 1: Basic sequential execution

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

const config: CodegenConfig = {
  generates: {
    './src/generated/types.generated.ts': [
      { plugins: ['typescript'] },
      { plugins: ['typescript-resolvers'] },
    ],
  },
};

export default config;

• Both stages inherit types.generated.ts from the outer key.
• The typescript-resolvers stage runs after the typescript stage, and its content is appended to that same file.

Example 2: output key is a directory, and a plugin stage can say which file it targets

const config: CodegenConfig = {
  generates: {
    './src/generated/': [
      { filename: 'types.generated.ts', plugins: ['typescript', 'typescript-resolvers'] },
      { preset: 'server' }, // preset stage: no filename needed, the preset decides its own
    ],
  },
};

The first stage needs filename because the directory could hold several files. The second stage doesn't, since presets already decide their own output filenames internally.

typescript-resolvers already proves that it can return a meta field alongside content today. This option reuses that existing field rather than inventing a new one, and makes it flow forward to later stages.

Warning

The exact mechanism for how multiple plugins/presets hand off data to each other is still being worked out. If you have thoughts, be sure to comment.

Pros

• "Stages" is declarative, and the chain can be composed from plugins/presets.
• Reuses an existing convention instead of inventing one: some plugins (e.g. typescript-resolvers) already return meta alongside content today.

Cons

• Purely linear: can't express "A and B run in parallel, then C depends on both." This is acceptable if real hand-off needs are usually two stages deep (observed use cases fall into this category), not a wide graph.

Use case coverage

• 1. Server Preset: Yes. Two stages: typescript + typescript-resolvers → core Server Preset logic
• 2. Client Preset → Compiler: Yes. Client Preset → Compiler. First stage to add generated files and meta of where the document docs are, so the Compiler stage can replace the graphql(...) calls.
• 3. Plugin → Plugin: Yes. E.g. typescript-operations returns its generated type names and translated field types via meta; the subsequent plugin reads that meta instead of independently re-deriving names by convention, closing the implicit-agreement gap.

Option 2: Wrapper Pattern

Plugins/presets can already invoke other plugins directly and use their returned metadata, so they can continue to act as wrappers around them.

Pros

• Smallest possible change: no new config syntax, no change to how the execution engine schedules or generates output.
• Proven pattern: the real Server Preset does this today.

Cons

• Doesn't solve the multi-stage use cases like Client Preset → Compiler or Plugin → Plugin.
• Every combination needs its own hand-written wrapper.

Use case coverage

• 1. Server Preset: Yes. This is the current approach.
• 2. Client Preset → Compiler: No, not directly. Folding the compiler step into codegen this way means authoring a new preset that itself calls the Client Preset's buildGeneratesSection, then runs a codemod over the result. A preset wrapping a preset, not something the Client Preset gains for free.
• 3. Plugin → Plugin: Yes, but heavy. Same shape as the Server Preset case: the wrapper calls typescript-operations and captures the type names from its meta — or, for schema transformation, transforms the schema and passes the result into the next plugin. Note that the subsequent plugin can't rely on its own schema argument in that case; it has to know to pull the transformed schema from meta instead, which is a hacky, easy-to-miss contract.

Recommendation

Adopt Option 1, with the explicit { content, meta } hand-off shape:

This ships without changing behavior for any config written today. The new mechanics only exist inside the new array shape; existing single-object generates entries are untouched.

Option 2 isn't going away. It still covers the current Server Preset case perfectly well, but it doesn't extend to the compiler or schema-transformation use cases, so it should be treated as fallback, rather than a substitute for Option 1.

Other Considered Options

• Declarative plugin dependency graph (capabilities-based): let each plugin declare what it provides and requires as metadata alongside its plugin() export (e.g. provides: ['typescript:types'], requires: ['typescript:types']). This is a more complex variant of Option 1, but doesn't solve the use cases any better.
• Creating multiple codegen runs and sequencing them via scripts: works for simple cases but is cumbersome, and watch mode experience would be bad.

[jerelmiller]

Thanks for putting this up! This would be extremely useful for Apollo Client, especially as we adopt more custom features that alter output types in some way.

What interests me the most is being able to augment types on fields without having to copy/paste a bunch of code from typescript-operations in order to sprinkle in the small bit of code needed to achieve the desired result. That plus I'd love ownership over that transform without having to bloat the core typescript-operations plugin with features specific to Apollo Client. Copy/paste gives us ownership, but means we lag behind new features/changes in typescript-operations and that would be frustrating for users.

You mentioned apolloUnmask as a good example of this. Its an Apollo Client specific feature that bloats the core plugin. I'm also experimenting with a variant of the @catch directive that would need to alter types from their raw type to something like { ok: true, value: TFieldType } | { ok: false, errors: GraphQLFormattedError[] } or could even remap non-nullable fields to null. Obviously I would not want to have to reimplement all of typescript-operations just to be able to tweak the type for a handful of fields, nor do I think supporting this in the core plugin makes sense. If other client libraries want a variant of @catch, they shouldn't have to bend to how Apollo Client implements it just to get support in codegen. If we could have an installable plugin owned by Apollo that provides the needed transforms, then I think it helps both of these issues.

As for my thoughts on the options listed. I like option 1, but my concern is that content is handed off as a string correct? If so, I think that would still make what I'm hoping for in this feature difficult because additional transforms would need string manipulation to work correctly. While it can be done with regex, thats easy to get wrong and tends to miss edge cases easily. Ideally we could work with an AST that can be manipulated and printed at the end. We could use something like recast as a one-off to parse the string, manipulate the AST, then print it again, but ideally we could work with an AST to avoid string manipulation.

FWIW, I'm not totally opposed to a wrapper approach. I think some plugins are more "foundational" than others (meaning they provide the base functionality that others can build on top of) and perhaps that constraint is ok. Something I think that might be worth adding to the pro column there is that the base plugin has more control over when in the lifecycle those higher-level plugins are applied. That could be beneficial to provide interceptors for fields/types before the string is written to the content. Of course, figuring out what/where in the lifecycle to allow for these types of things could explode the surface area and that might not be very helpful. Could be, as you said, a good fit for the smallest change for now while working toward a more general solution that option 1 could provide.

At the very least, thanks for putting up this RFC! I think this could really help accelerate some of the things we are doing/wanting to do in Apollo Client and I'm sure other client libraries would benefit as well 🙂

[eddeee888]

Thanks for sharing more details about the Apollo use case @jerelmiller !

As for my thoughts on the options listed. I like option 1, but my concern is that content is handed off as a string correct? If so, I think that would still make what I'm hoping for in this feature difficult because additional transforms would need string manipulation to work correctly. While it can be done with regex, thats easy to get wrong and tends to miss edge cases easily. Ideally we could work with an AST that can be manipulated and printed at the end. We could use something like recast as a one-off to parse the string, manipulate the AST, then print it again, but ideally we could work with an AST to avoid string manipulation.

That's correct, content as a string is the minimum that one plugin would handoff to the next. This is the majority of the use case and is the easiest/fastest to append/print to file.

Since Codegen focuses on GraphQL AST, it doesn't (and also shouldn't) have an opinion on how the TypeScript AST is handled. I could share the 3 ways Server Preset (with wrapper approach) currently uses the hand-off output :

• content as raw string to used to write to file
• content is also parsed into AST with ts-morph (which uses TS compiler API underneath) so it can do type comparison and codemod (e.g. injecting resolver skeleton into files)
• meta contains metadata about content e.g. the resolvers type is printed as Resolvers and not RESOLVERS. Parsing content with AST for this proved challenging. So, as the typescript-resolvers plugin generates types, it also keeps track and passes on the types it's generating, so subsequent consumers can use the output easily.

I'm also experimenting with a variant of the @catch directive

Very early thinking, I feel the wrapper approach could get this quite far for the common one-generated-file setup:

// example config with apollo-operations wrapper-style plugin
const config = {
  generates: {
    'types.generated.ts': {
      plugins: ['apollo-operations']
    }
  }
}

// plugins/apollo-operations/index.ts
import * as operationsPlugin from '@graphql-codegen/typescript-operations';

const plugin = (schema, documents, config) => {
  const {prepend, content, append, meta } = operationsPlugin.plugin(schema, [], {
    extractTypeOnDirective=[‘catch’] // doesn't exist yet, but this is a generic option to use `Foo_Field_xxx` on fields with catch directive and save this into meta
  }),

  // then, we could use it in meta
  const { 
    typename, // Foo_Field_xxx
    originalType  // e.g. string
  } = meta.extractedTypes.filter((extractedType) => extractedType.directives.includes("catch"))
}

  // then, append a line at the end

  return {
    prepend,
    content,
    append: [...append, 'type Foo_Field_xxx = SOMETHINGELSE' ]
  }

FWIW, I'm not totally opposed to a wrapper approach. I think some plugins are more "foundational" than others (meaning they provide the base functionality that others can build on top of) and perhaps that constraint is ok. Something I think that might be worth adding to the pro column there is that the base plugin has more control over when in the lifecycle those higher-level plugins are applied. That could be beneficial to provide interceptors for fields/types before the string is written to the content. Of course, figuring out what/where in the lifecycle to allow for these types of things could explode the surface area and that might not be very helpful. Could be, as you said, a good fit for the smallest change for now while working toward a more general solution that option 1 could provide.

Yes, absolutely agreed! I think wrapper style just moves the orchestration layer to the plugin, and that can give a lot more customisation (at the cost of reusability). Option 2 is a definitely valid, and is working well for Server Preset, so I don't think it'd go away.

[jerelmiller]

Oh I think I might have misunderstood the wrapper approach wrong 😅. In my head, typescript-operations wrapped the Apollo plugin, not the other way around where typescript-operations would provide "hooks" into certain parts of the codegen lifecycle to inject custom logic before printing the type. I think what you're saying above could work, but what I'd like to avoid is having to subclass things to inject logic in the middle of a method to get the output type I'd want (for example, apolloUnmask had to add logic in the middle of buildSelectionSet in order to work. Preferably a separate plugin wouldn't have to create subclasses, copy the logic of that method, then tweak to add that behavior). I think what I'm really getting at is having isolation in a way where typescript-operations doesn't have to know what apollo-operations is doing, and apollo-operations wouldn't have to know intimate details about typescript-operations methods in order to build or change types in some way. In that way, option 1 makes most sense to me since it has that isolation naturally (one plugin does one thing then hands off to another where it can continue to manipulate the output from what the plugin did before it).

Perhaps I'm just thinking about this totally wrong, but regardless, I'm excited to work with you to get something awesome!

[eddeee888]

In my head, typescript-operations wrapped the Apollo plugin, not the other way around where typescript-operations would provide "hooks" into certain parts of the codegen lifecycle to inject custom logic before printing the type
Ah I see! We currently have hooks but the command runs on the generated file, which in theory could be used but is not a great experience:

generates: {
    'types.generated.ts': {
      plugins: ['typescript-operations']
      hooks: {
        beforeOneFileWrite: ['apollo-operations-codemod'] // runs `apollo-operations-codemod types.generated.ts` before written to disk
      }
    }
  }

---

Alternatively, this could be handled adhoc at the plugin config level as a quick win. e.g.

// hopefully this is what you meant?
plugins: ['typescript-operations'],
config: {
  onSomeConditonMet: 'apollo-operations:do-something' // have a special syntax to do run some functions from another plugin
}

However, plugins like may start having hooks like this across its surface which increasing doc requirements and become harder to scale/maintain.

I think what I'm really getting at is having isolation in a way where typescript-operations doesn't have to know what apollo-operations is doing, and apollo-operations wouldn't have to know intimate details about typescript-operations methods in order to build or change types in some way.

I'm thinking the same too 👍
Let me have a review of the options/requirements/braindumps so far and see what's next