[client-preset] feat: add skipIndexFile option to skip index.ts generation (#10946)

Author: eddeee888

.changeset/client-preset-skip-index-file.md

@@ -0,0 +1,5 @@
+---
+'@graphql-codegen/client-preset': minor
+---
+
+Add `skipIndexFile` preset config option to `client-preset` to allow disabling generation of the `index.ts` barrel file that re-exports the other generated files. Defaults to `false` (unchanged behavior); set to `true` to skip generating `index.ts`, for example when your project avoids barrel files for tree-shaking or lint rule reasons.

packages/presets/client/src/index.ts

@@ -98,6 +98,28 @@ export type ClientPresetConfig = {
          */
         hashAlgorithm?: 'sha1' | 'sha256' | (string & {}) | ((operation: string) => string);
       };
+  /**
+   * @description Skip generating the `index.ts` barrel file that re-exports the other generated files.
+   * @default false
+   *
+   * @exampleMarkdown
+   * ```tsx
+   * const config = {
+   *    schema: 'https://graphql.org/graphql/',
+   *    documents: ['src/**\/*.tsx', '!src\/gql/**\/*'],
+   *    generates: {
+   *       './src/gql/': {
+   *          preset: 'client',
+   *          presetConfig: {
+   *            skipIndexFile: true,
+   *          }
+   *        },
+   *    },
+   * };
+   * export default config;
+   * ```
+   */
+  skipIndexFile?: boolean;
 };
 
 const isOutputFolderLike = (baseOutputDir: string) => baseOutputDir.endsWith('/');
@@ -292,7 +314,7 @@ export const preset: Types.OutputPreset<ClientPresetConfig> = {
 
     let indexFileGenerateConfig: Types.GenerateOptions | null = null;
 
-    if (reexports.length) {
+    if (reexports.length && !options.presetConfig?.skipIndexFile) {
       indexFileGenerateConfig = {
         filename: `${options.baseOutputDir}index.ts`,
         pluginMap: {

packages/presets/client/tests/client-preset.presetConfig.skipIndexFile.spec.ts

@@ -0,0 +1,75 @@
+import { executeCodegen } from '@graphql-codegen/cli';
+import { preset } from '../src/index.js';
+
+describe('client-preset - presetConfig.skipIndexFile', () => {
+  const schema = [
+    /* GraphQL */ `
+      type Query {
+        a: String
+        b: String
+        c: String
+      }
+    `,
+  ];
+  const documents = /* GraphQL */ `
+    query A {
+      a
+    }
+  `;
+
+  it('generates index.ts by default', async () => {
+    const { result } = await executeCodegen({
+      schema,
+      documents,
+      generates: {
+        'out1/': {
+          preset,
+        },
+      },
+    });
+
+    expect(result).toHaveLength(4);
+    const indexFile = result.find(file => file.filename === 'out1/index.ts');
+    expect(indexFile.content).toEqual(`export * from "./fragment-masking";
+export * from "./gql";`);
+  });
+
+  it('does not generate index.ts when `skipIndexFile: true`', async () => {
+    const { result } = await executeCodegen({
+      schema,
+      documents,
+      generates: {
+        'out1/': {
+          preset,
+          presetConfig: {
+            skipIndexFile: true,
+          },
+        },
+      },
+    });
+
+    expect(result).toHaveLength(3);
+    const indexFile = result.find(file => file.filename === 'out1/index.ts');
+    expect(indexFile).toBeUndefined();
+  });
+
+  it('generates index.ts when `skipIndexFile: false`', async () => {
+    const { result } = await executeCodegen({
+      schema,
+      documents,
+      generates: {
+        'out1/': {
+          preset,
+          presetConfig: {
+            skipIndexFile: false,
+          },
+        },
+      },
+    });
+
+    expect(result).toHaveLength(4);
+    const indexFile = result.find(file => file.filename === 'out1/index.ts');
+    expect(indexFile.content).toEqual(`export * from "./fragment-masking";
+export * from "./gql";`);
+  });
+});

website/content/plugins/presets/preset-client.mdx

@@ -635,6 +635,45 @@ const client = new createClient({
 })
 ```
 
+## Index File
+
+By default, the `client-preset` generates an `index.ts` file that re-exports the other generated
+files (`gql.ts`, and `fragment-masking.ts` when Fragment Masking is enabled), so you can import
+everything from the output directory itself:
+
+```ts
+import { graphql } from './gql'
+```
+
+Some projects prefer to avoid barrel files, for example because they interfere with tree-shaking or
+because of a lint rule against them. In that case, `index.ts` generation can be disabled with the
+`skipIndexFile` option:
+
+```ts title="codegen.ts" {9-11}
+import { type CodegenConfig } from '@graphql-codegen/cli'
+
+const config: CodegenConfig = {
+  schema: 'schema.graphql',
+  documents: ['src/**/*.tsx', '!src/gql/**/*'],
+  generates: {
+    './src/gql/': {
+      preset: 'client',
+      presetConfig: {
+        skipIndexFile: true
+      }
+    }
+  }
+}
+
+export default config
+```
+
+With `skipIndexFile` enabled, import from the specific generated files instead:
+
+```ts
+import { graphql } from './gql/gql'
+```
+
 ## Reducing Bundle Size
 
 Large scale projects might want to enable code splitting or tree shaking on the `client-preset`