feat(core): allow mock data generators only (#3398)

* feat(mock): add generateHandlers option to suppress MSW handler output

When `generateHandlers: false` is set in mock options, only faker data
generator functions are produced — no MSW request handlers, no aggregated
handler array, and no `msw` dependency in imports. This allows users who
only need mock data factories to avoid the MSW dependency entirely.

* fix(core): handle empty handlerName in writers when generateHandlers is false

Guard handlerName accumulation in target and target-tags writers to avoid
producing junk `()` entries when handlers are disabled. Also update the
split-tags index file to use barrel exports when there is no aggregated
handler function to reference.

* test(mock): add coverage for generateHandlers: false option

Verify that handler and handlerName are empty, mock data function is
still generated, msw imports are excluded, and faker locale imports
work correctly when generateHandlers is disabled.

* docs(mock): document generateHandlers option

Add generateHandlers to the configuration reference table and a new
"Data Generators Only" section to the MSW guide explaining the use case
and output differences.

* fix(core): avoid leading comma when accumulating handlerNames in target-tags

Author: jakiestfu

docs/content/docs/guides/msw.mdx

@@ -245,6 +245,31 @@ const server = setupServer(...handlers);
 export { server };
 ```
 
+## Data Generators Only
+
+If you only need mock data factories without MSW request handlers, set `generateHandlers` to `false`:
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      mock: {
+        type: 'msw',
+        generateHandlers: false,
+      },
+    },
+  },
+});
+```
+
+This generates only the `get<OperationId>ResponseMock` functions (powered by Faker.js) — no MSW handlers, no aggregated handler array, and no `msw` dependency in the output. Your project only needs `@faker-js/faker` as a dependency.
+
+This is useful when you want mock data for:
+- Unit tests with custom assertion libraries
+- Storybook stories
+- Seed scripts
+- Any test setup that doesn't use MSW
+
 ## MSW Best Practices
 
 The generated code follows [MSW best practices](https://mswjs.io/docs/best-practices):

docs/content/docs/reference/configuration/output.mdx

@@ -377,6 +377,7 @@ export default defineConfig({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `type` | `'msw'` | `'msw'` | Mock type |
+| `generateHandlers` | `Boolean` | `true` | Generate MSW request handlers. Set to `false` for data generators only (no `msw` dependency needed). |
 | `delay` | `Number \| Function \| false` | `false` | Response delay in ms |
 | `delayFunctionLazyExecute` | `Boolean` | `false` | Execute delay function at runtime |
 | `useExamples` | `Boolean` | `false` | Use OpenAPI examples |

packages/core/src/types.ts

@@ -424,6 +424,8 @@ export interface GlobalMockOptions {
   // Preferred response content type when multiple success content types exist
   preferredContentType?: string;
   indexMockFiles?: boolean;
+  // When false, only mock data generators are produced (no MSW request handlers or aggregated handler array)
+  generateHandlers?: boolean;
 }
 
 export type OverrideMockOptions = Partial<GlobalMockOptions> & {

packages/core/src/writers/split-tags-mode.ts

@@ -277,14 +277,17 @@ export async function writeSplitTagsMode({
 
   // Write mock index file after Promise.all to ensure deterministic export order.
   if (indexFilePath && mockOption) {
+    const handlersDisabled = mockOption.generateHandlers === false;
     const indexContent = tagEntries
       .map(([tag]) => {
         const localMockPath = upath.joinSafe(
           './',
           tag,
           tag + '.' + getMockFileExtensionByTypeName(mockOption),
         );
-        return `export { get${pascal(tag)}Mock } from '${localMockPath}'\n`;
+        return handlersDisabled
+          ? `export * from '${localMockPath}'\n`
+          : `export { get${pascal(tag)}Mock } from '${localMockPath}'\n`;
       })
       .join('');
     await fs.appendFile(indexFilePath, indexContent);

packages/core/src/writers/target-tags.ts

@@ -47,7 +47,9 @@ function generateTargetTags(
       implementationMock: {
         function: operation.implementationMock.function,
         handler: operation.implementationMock.handler,
-        handlerName: '  ' + operation.implementationMock.handlerName + '()',
+        handlerName: operation.implementationMock.handlerName
+          ? '  ' + operation.implementationMock.handlerName + '()'
+          : '',
       },
     };
 
@@ -66,11 +68,14 @@ function generateTargetTags(
       handler:
         currentOperation.implementationMock.handler +
         operation.implementationMock.handler,
-      handlerName:
-        currentOperation.implementationMock.handlerName +
-        ',\n  ' +
-        operation.implementationMock.handlerName +
-        '()',
+      handlerName: operation.implementationMock.handlerName
+        ? currentOperation.implementationMock.handlerName +
+          (currentOperation.implementationMock.handlerName.length > 0
+            ? ',\n  '
+            : '  ') +
+          operation.implementationMock.handlerName +
+          '()'
+        : currentOperation.implementationMock.handlerName,
     },
     mutators: operation.mutator
       ? [...(currentOperation.mutators ?? []), operation.mutator]

packages/core/src/writers/target.ts

@@ -48,10 +48,12 @@ export function generateTarget(
     target.implementationMock.function += operation.implementationMock.function;
     target.implementationMock.handler += operation.implementationMock.handler;
 
-    const handlerNameSeparator =
-      target.implementationMock.handlerName.length > 0 ? ',\n  ' : '  ';
-    target.implementationMock.handlerName +=
-      handlerNameSeparator + operation.implementationMock.handlerName + '()';
+    if (operation.implementationMock.handlerName) {
+      const handlerNameSeparator =
+        target.implementationMock.handlerName.length > 0 ? ',\n  ' : '  ';
+      target.implementationMock.handlerName +=
+        handlerNameSeparator + operation.implementationMock.handlerName + '()';
+    }
 
     if (operation.mutator) {
       target.mutators.push(operation.mutator);

packages/mock/src/msw/index.test.ts

@@ -6,7 +6,7 @@ import type {
 import { OutputMockType } from '@orval/core';
 import { describe, expect, it } from 'vitest';
 
-import { generateMSW } from './index';
+import { generateMSW, generateMSWImports } from './index';
 
 describe('generateMSW', () => {
   const mockVerbOptions = {
@@ -1228,4 +1228,85 @@ describe('generateMSW', () => {
       expect(petEntries.some((i) => i.alias === '__Pet')).toBe(true);
     });
   });
+
+  describe('generateHandlers: false', () => {
+    it('should return empty handler when generateHandlers is false', () => {
+      const result = generate({
+        mock: { type: OutputMockType.MSW, generateHandlers: false },
+      });
+      expect(result.implementation.handler).toBe('');
+    });
+
+    it('should return empty handlerName when generateHandlers is false', () => {
+      const result = generate({
+        mock: { type: OutputMockType.MSW, generateHandlers: false },
+      });
+      expect(result.implementation.handlerName).toBe('');
+    });
+
+    it('should still generate mock data function when generateHandlers is false', () => {
+      const numberVerbOptions = {
+        ...mockVerbOptions,
+        response: {
+          ...mockVerbOptions.response,
+          definition: { success: 'number' },
+          types: { success: [{ key: '200', value: 'number' }] },
+          contentTypes: ['application/json'],
+        },
+      } as unknown as GeneratorVerbOptions;
+
+      const result = generateMSW(numberVerbOptions, {
+        ...baseOptions,
+        mock: { type: OutputMockType.MSW, generateHandlers: false },
+      });
+      expect(result.implementation.function).toContain(
+        'export const getGetUserResponseMock',
+      );
+      expect(result.implementation.handler).toBe('');
+    });
+
+    it('should not contain msw imports when generateHandlers is false', () => {
+      const result = generateMSWImports({
+        implementation:
+          'export const getUserResponseMock = () => faker.string.alpha()',
+        imports: [],
+        projectName: '',
+        hasSchemaDir: false,
+        isAllowSyntheticDefaultImports: true,
+        options: { type: OutputMockType.MSW, generateHandlers: false },
+      });
+      expect(result).not.toContain("from 'msw'");
+    });
+
+    it('should include faker import when generateHandlers is false', () => {
+      const result = generateMSWImports({
+        implementation:
+          'export const getUserResponseMock = () => faker.string.alpha()',
+        imports: [],
+        projectName: '',
+        hasSchemaDir: false,
+        isAllowSyntheticDefaultImports: true,
+        options: { type: OutputMockType.MSW, generateHandlers: false },
+      });
+      expect(result).toContain("from '@faker-js/faker'");
+    });
+
+    it('should use locale-specific faker import when generateHandlers is false with locale', () => {
+      const result = generateMSWImports({
+        implementation:
+          'export const getUserResponseMock = () => faker.string.alpha()',
+        imports: [],
+        projectName: '',
+        hasSchemaDir: false,
+        isAllowSyntheticDefaultImports: true,
+        options: {
+          type: OutputMockType.MSW,
+          generateHandlers: false,
+          locale: 'fr',
+        },
+      });
+      expect(result).toContain("from '@faker-js/faker/locale/fr'");
+      expect(result).not.toContain("from 'msw'");
+    });
+  });
 });

packages/mock/src/msw/index.ts

@@ -21,9 +21,19 @@ import { getMockDefinition, getMockOptionsDataOverride } from './mocks';
 function getMSWDependencies(
   options?: GlobalMockOptions,
 ): GeneratorDependency[] {
-  const hasDelay = options?.delay !== false;
   const locale = options?.locale;
 
+  const fakerDependency: GeneratorDependency = {
+    exports: [{ name: 'faker', values: true }],
+    dependency: locale ? `@faker-js/faker/locale/${locale}` : '@faker-js/faker',
+  };
+
+  if (options?.generateHandlers === false) {
+    return [fakerDependency];
+  }
+
+  const hasDelay = options?.delay !== false;
+
   const exports = [
     { name: 'http', values: true },
     { name: 'HttpResponse', values: true },
@@ -34,15 +44,7 @@ function getMSWDependencies(
     exports.push({ name: 'delay', values: true });
   }
 
-  return [
-    { exports, dependency: 'msw' },
-    {
-      exports: [{ name: 'faker', values: true }],
-      dependency: locale
-        ? `@faker-js/faker/locale/${locale}`
-        : '@faker-js/faker',
-    },
-  ];
+  return [{ exports, dependency: 'msw' }, fakerDependency];
 }
 
 export const generateMSWImports: GenerateMockImports = ({
@@ -421,11 +423,15 @@ export function generateMSW(
     }
   }
 
+  const handlersDisabled =
+    isObject(generatorOptions.mock) &&
+    generatorOptions.mock.generateHandlers === false;
+
   return {
     implementation: {
       function: mockImplementations.join('\n'),
-      handlerName: handlerName,
-      handler: handlerImplementations.join('\n'),
+      handlerName: handlersDisabled ? '' : handlerName,
+      handler: handlersDisabled ? '' : handlerImplementations.join('\n'),
     },
     imports: imports,
   };

packages/orval/src/client.ts

@@ -127,6 +127,11 @@ export const generateClientHeader: GeneratorClientHeader = ({
   clientImplementation,
 }) => {
   const { header } = getGeneratorClient(outputClient, output);
+  const handlersDisabled =
+    output.mock &&
+    !isFunction(output.mock) &&
+    output.mock.generateHandlers === false;
+
   return {
     implementation: header
       ? header({
@@ -143,7 +148,9 @@ export const generateClientHeader: GeneratorClientHeader = ({
           clientImplementation,
         })
       : '',
-    implementationMock: `export const ${titles.implementationMock} = () => [\n`,
+    implementationMock: handlersDisabled
+      ? ''
+      : `export const ${titles.implementationMock} = () => [\n`,
   };
 };
 
@@ -157,10 +164,15 @@ export const generateClientFooter: GeneratorClientFooter = ({
 }) => {
   const { footer } = getGeneratorClient(outputClient, output);
 
+  const handlersDisabled =
+    output.mock &&
+    !isFunction(output.mock) &&
+    output.mock.generateHandlers === false;
+
   if (!footer) {
     return {
       implementation: '',
-      implementationMock: `\n]\n`,
+      implementationMock: handlersDisabled ? '' : `\n]\n`,
     };
   }
 
@@ -193,7 +205,7 @@ export const generateClientFooter: GeneratorClientFooter = ({
 
   return {
     implementation,
-    implementationMock: `]\n`,
+    implementationMock: handlersDisabled ? '' : `]\n`,
   };
 };