feat: Add runtime skip property to conditionally skip codegen

[mihaerzen]

Description

When using this plugin in watch mode alongside a running Vite dev server, codegen is triggered on every filesystem change. This works well in normal development, but causes issues during Git operations such as rebasing.

During a rebase, many intermediate file changes occur rapidly. The plugin reacts to these transient states and runs codegen, which can generate invalid artifacts or interfere with the rebase process (e.g., modifying files mid-rebase).

Problem

There is currently no way to programmatically control whether codegen should run at a given moment. This makes it difficult to prevent codegen from executing during non-stable repository states (like rebases, merges, or other bulk operations).

Proposed Solution

Introduce an optional configuration callback, e.g.:

graphqlCodegen({
  skip: boolean | () => boolean | () => Promise<boolean>
})

This property would be evaluated before triggering codegen. If it returns false, codegen is skipped for that cycle.

Example Use Case

Skip codegen during a Git rebase:

import fs from "fs";
import path from "path";

function isGitBusy() {
  const gitDir = path.resolve(process.cwd(), ".git");

  return [
    "rebase-merge",
    "rebase-apply",
    "MERGE_HEAD",
  ].some((p) => fs.existsSync(path.join(gitDir, p)));
}

graphqlCodegen({
  skip: () => !isGitBusy(),
});

Alternative Use Cases

• Temporarily disabling codegen via environment variables
• Skipping execution when certain files are in flux
• Integrating with custom dev workflows or tooling

Benefits

• Prevents codegen from running on unstable filesystem states
• Avoids interference with Git operations like rebase/merge
• Gives users fine-grained control over when codegen executes
• Maintains backwards compatibility (fully optional feature)

Notes

I went ahead and created PR with this functionality as it's not that complicated. ✌️

[danielwaltz]

Makes sense! At first I wondered if it would make more sense to programmatically add the plugin instead, like this:

export default defineConfig({
  plugins: [
    ...(isRebasing ? [] : [codegen()]),
  ],
})

But I see that you don't want to have to restart Vite or reload configuration, and if a function is passed it will be checked without restarting.

My only concern (or really wonder) is if this check could happen before generateWithOverride is even called in each case. Not sure if it's that bad of a perf impact to still do all the file checks in the watcher even though it will be skipped at the generate step anyway.

Let me know! If there's good reason I'm not seeing for how it is now, I'm ok with just shipping as-is!

Thanks for the contribution. ❤️

[mihaerzen]

That’s a fair concern.

Right now the check happens right before generateWithOverride, so we still go through the watcher cycle and dependency checks, but skip the actual codegen work.

My thinking was:

• the expensive part is generate itself
• the watcher + file matching is relatively cheap and already happening
• placing the check there keeps the change minimal and avoids threading skip logic deeper into the plugin lifecycle

Also, one reason I leaned toward this placement is flexibility as it allows skipping based on what actually triggered the run. For example, you might want to skip codegen only for certain file changes or patterns, which isn’t as straightforward if the check happens before the watcher logic resolves what changed.

That said, I agree there’s a potentially cleaner model where we short-circuit earlier and avoid even reaching that stage when skip is true in simple cases.

Happy to move the check earlier or combine both approaches (early guard + final check) if you think that’s a better balance.

Do you have a specific point in mind where you'd want the guard applied (e.g. right at the watcher event handler), or just “before any codegen-related work”? I can adjust accordingly.

[mihaerzen]

Hey @danielwaltz any updates here? Let me know if there is anything more I should do ✌️

[danielwaltz]

Sorry for delay!

I think you make a good point that the parts leading up to generating files are pretty quick anyway. It solves your need, can solve other's needs, and code is solid. Let's ship it!

Thanks again! ❤️

[github-actions]

🎉 This PR is included in version 3.9.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀