feat: implement msw plugin

[malcolm-kee]

Closes #1486

Summary

Implement msw plugin that generates a msw.gen.ts file with type-safe mock handler factories from OpenAPI specs. Each operation is exported as a named handler creator (<operationId>Mock) with a wildcard base URL, plus a getAllMocks helper to generate handlers for all operations at once. A createMswHandlerFactory function is also exported for custom base URL binding.

Important

Even though many expect fake data generation is part of this plugin, that probably overlaps with faker plugin. The only mock data handled by this plugin at the moment is the example defined in the OpenAPI spec.

API Design

Configuration

export default {
  plugins: [
    {
      name: "msw",
      valueSources: ["example"], // set to [] to disable example embedding
    },
  ],
};

Usage

Individual handler exports (wildcard base URL)

import { HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { getPetByIdMock, updatePetMock, getInventoryMock, getAllMocks } from "./client/msw.gen";

const server = setupServer(
  // Static response — type-checked result, status defaults to dominant success code
  getPetByIdMock({ result: { id: 1, name: "Fido", photoUrls: [] } }),

  // Explicit status code
  getPetByIdMock({ status: 200, result: { id: 1, name: "Fido", photoUrls: [] } }),

  // Custom resolver — params and request body are typed
  updatePetMock(async ({ request, params }) => {
    const body = await request.json();
    return HttpResponse.json({ id: Number(params.petId), ...body }, { status: 200 });
  }),

  // Operations with spec examples — no args needed
  getInventoryMock(),
);

Handler options

MSW handler options can be passed as a second argument:

getPetByIdMock({ result: { id: 1, name: "Fido" } }, { once: true });

Custom base URL (createMswHandlerFactory)

import { createMswHandlerFactory } from "./client/msw.gen";

// Explicit base URL
const createMock = createMswHandlerFactory({
  baseUrl: "http://localhost:3000",
});

// No args — infers base URL from spec's servers field
const createMock2 = createMswHandlerFactory();

const server = setupServer(
  createMock.getPetByIdMock({ result: { id: 1, name: "Fido", photoUrls: [] } }),
);

All handlers (getAllMocks)

import { getAllMocks } from "./client/msw.gen";

// Quick setup — all operations with defaults
setupServer(...getAllMocks());

// Strict mode — missing mocks return 501
setupServer(...getAllMocks({ onMissingMock: "error" }));

// With overrides — keys are handler names (<operationId>Mock)
setupServer(
  ...getAllMocks({
    onMissingMock: "skip",
    overrides: {
      getPetByIdMock: {
        result: { id: 1, name: "Fido", photoUrls: [] },
      },
    },
  }),
);

Design decisions

Why <operationId>Mock naming? — Appending Mock avoids naming collisions with other generated artifacts (types, SDK functions) while keeping the handler clearly associated with its operation.

Why both individual exports and createMswHandlerFactory? — Individual exports use a wildcard (*) base URL for zero-config convenience. The factory function allows binding to a specific base URL when needed (e.g. integration tests against a specific server).

Why valueSources instead of example: boolean? — Extensible for future sources (e.g. ['example', 'faker'] when faker plugin is ready).

onMissingMock — Operations that require a response argument (no default example) are either skipped ('skip') or return a 501 ('error'). Overrides always take precedence.

Handler creator signatures

Operation has	Parameter type	Optional?
Response type with status codes	{ result, status? } | ToResponseUnion<Responses> | HttpResponseResolver<PathParams, Body>	No*
Response type, void	{ result, status? } | ToResponseUnion<Responses> | HttpResponseResolver<PathParams, Body>	Yes
No response type (no status code)	HttpResponseResolver<PathParams, Body>	Yes

* Optional if the spec defines an example for the dominant response.

Response method selection

Content type	Method
application/json	HttpResponse.json()
text/*	HttpResponse.text()
binary/octet-stream	new HttpResponse()
void / no content	new HttpResponse(null)

When multiple 2xx responses exist, the dominant one is chosen by priority: json > text > binary > void.

Known limitations

• Response type generic is omitted from HttpResponseResolver to avoid MSW's DefaultBodyType constraint issues with union/void response types
• Query parameters are not typed in resolvers (MSW doesn't support typed query params natively)
• Only 2xx responses are considered for the dominant response

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[pullfrog]

Error

agent completed without reporting progress

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ Triggered by Pullfrog ｜ pullfrog.com ｜ 𝕏}

[vercel]

@malcolm-kee is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: e4a9553

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hey-api/openapi-ts	Patch
@hey-api/shared	Patch
@hey-api/openapi-python	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codecov]

Codecov Report

❌ Patch coverage is 18.44262% with 398 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.37%. Comparing base (ebf6878) to head (e4a9553).

Files with missing lines	Patch %	Lines
examples/openapi-ts-fetch/src/client/msw.gen.ts	29.83%	112 Missing and 55 partials ⚠️
...kages/openapi-ts/src/plugins/msw/shared/handler.ts	1.58%	54 Missing and 8 partials ⚠️
.../src/plugins/msw/shared/computeDominantResponse.ts	8.92%	33 Missing and 18 partials ⚠️
packages/openapi-ts/src/plugins/msw/v2/plugin.ts	2.00%	48 Missing and 1 partial ⚠️
packages/openapi-ts/src/plugins/msw/shared/sort.ts	0.00%	14 Missing and 3 partials ⚠️
...ages/openapi-ts/src/plugins/msw/shared/response.ts	0.00%	13 Missing and 1 partial ⚠️
packages/shared/src/utils/url.ts	0.00%	5 Missing and 9 partials ⚠️
...ackages/openapi-ts/src/plugins/msw/shared/types.ts	0.00%	10 Missing ⚠️
packages/openapi-ts/src/plugins/msw/config.ts	28.57%	3 Missing and 2 partials ⚠️
packages/openapi-ts/src/plugins/msw/shared/path.ts	0.00%	4 Missing and 1 partial ⚠️
... and 3 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3570      +/-   ##
==========================================
- Coverage   40.04%   39.37%   -0.67%     
==========================================
  Files         520      543      +23     
  Lines       19243    20379    +1136     
  Branches     5720     6140     +420     
==========================================
+ Hits         7705     8024     +319     
- Misses       9342     9957     +615     
- Partials     2196     2398     +202     

Flag	Coverage Δ
unittests	39.37% <18.44%> (-0.67%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mrlubos]

@malcolm-kee Before I go into it, two questions:

1. How much AI was used to create this pull request?
2. How much are you willing to improve it? i.e. Is this the final version?

[malcolm-kee]

@mrlubos I come up with the API design and AI was doing most of the implementations while I watch.

Not final. I'm happy to iterate on this, just want some progress on this plugin.

[malcolm-kee]

The diff is big is mostly because of the tests and snapshots.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3570

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3570

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3570

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3570

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3570

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3570

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3570

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3570

commit: e4a9553

[malcolm-kee]

I did some refactoring/enhancements:

• remove duplications of type definition and function param definition. It's only defined at type level and the implementation param is auto-inferred from that.
• extract example from schema as default value.

[malcolm-kee]

@mrlubos I manually validated the code and made some refactoring. It would be great if you can provide some feedbacks, especially on the API.

[malcolm-kee]

More revision:

• Redesign the API - the static parameter becomes { status: number; result: ResultType } instead of just ResultType. This design allows typescript to infer the types better with a stable object type with explicit properties instead of a more generic ResultType. This also make it easier to overwrite the status code without falling back to use the custom resolver approach.
• Forward the handler options to msw, so no lost of capabilities.
• Added resolveToNull helper function to remove duplicate fallbacks

[malcolm-kee]

Added examples options to the plugin.

[malcolm-kee]

Change plugin options from examples: boolean to valueSources: Array<'example'>, so that when fakerjs is ready, we just need to switch the default value to valueSources: ['example', 'faker'].

[malcolm-kee]

Ideas on how to continue enhancing this PR, in case anyone want to take over this, since I might not be free to iterate on this:

Implement ofAll

We can actually implement ofAll helper without waiting for faker plugin, by providing options to customize its behavior:

const createMock = createMswHandlerFactory();

const allMockHandlers = createMock.ofAll({
  onMissingMock: 'skip', // 'skip' | 'error',
  overrides: {
    getPetById({
      status: 200,
      result: { id: 1, name: "Fido", photoUrls: [] },
    })
  }
});

const server = setupServer(...allMockHandlers);

onMissingMock option:

• skip: we will not include the MSW handlers that requires argument in the returned array of requestHandlers. This is possible because we can infer if argument is required for a handler (I differentiate them by providing them different types - HttpHandlerFactory are those require argument while OptionalHttpHandlerFactory are those does not require argument)
• error: we will include the MSW handlers for all, but for those require argument, we will return HttpResponse('[heyapi-msw] The mock of this request is not implemented.', { status: 501 })

overrides option API is similar to the API of single handler, but instead of calling individual helper, user can define all of them at once here.

[mrlubos]

@malcolm-kee good eye – that one is intentional. If we're skipping or throwing an error on missing mocks, there's no need to provide any arguments. More importantly, this is the base experience I want people to have:

const server = setupServer(
  ...createMswHandlers().all(),
);
server.listen();

or with single handler:

const server = setupServer(
  createMswHandlers().one.tuiPublish(),
);
server.listen();

As with the rest of the ecosystem, it should just work™. In the end, the behavior I'm steering towards with this v0 is mock what we can (based on the examples field), and skip everything else. The above examples feel good to me, just need to bring back the onMissingMock behavior from your last comment.

After playing with it more, I agree that fake data is very high on the priority list. A lot of specs simply don't have example fields, which would make the default experience basically do nothing haha. Did you have an interest in working on that feature?

[malcolm-kee]

I agree with the principle of it should just work, but I want to push back a little, as I disagree that making the parameter optional is achieving that.

There are two scenarios when someone add a msw handlers:

• scenario 1: a flow that fetch some data from backend and use it for subsequent processing, e.g. display in UI
• scenario 2: a flow that make some API calls to backend, then doesn't care about its response as long it is returning successful status code

By making the parameter optional in all cases, we're making the life for scenario 2 easier but at the cost of scenario 1. Now that instead of letting the type guide them on which mock handlers can be used safely, they have to wait until the runtime error in the test to let them know if a manual mock data is required.

A middle ground that we can attempt is to apply different logic based on the method - get method should force the parameter as required when fallback is not available, and other methods can be always optional. I didn't do that because I tried to avoid making the logic even more complicated.

Last thing I want to point out is that this is a decision we had to make even with the faker plugin, because user might disable default value from faker with valueSources: [].

[malcolm-kee]

Yeah I'm interested in working on the faker plugin, didn't do anything yet cause I assumed you've started something?

[malcolm-kee]

@mrlubos is the plan to wait for faker plugin before merging this?

[mrlubos]

@malcolm-kee Not necessarily, but it requires several more days to prepare the response modeling part, and I need to work on other things too so I will pick this up again later

[mrlubos]

@malcolm-kee fyi, this is how far I am with it, and 1 of those files are docs

[malcolm-kee]

WIP for faker plugin:

• faker js plugin #3681

[pullfrog]

TL;DR — Adds a new msw code-generation plugin that produces type-safe MSW v2 handler factories from OpenAPI specs. Each operation gets a handler function accepting either a static typed response or a custom HttpResponseResolver, and a createMswHandlers factory provides per-handler access (.pick) and bulk setup (.all()). As a side-effect, base URL resolution logic is extracted from the client-core plugin into a shared getBaseUrl() utility, and a new @hey-api/examples plugin scaffold is introduced as a data-source dependency.

Key changes

• New msw plugin — Complete code-generation plugin that iterates over all IR operations and emits a msw.gen.ts file with per-operation handler functions, exported per-operation response type aliases, a MswHandlerFactories type, and a createMswHandlers() factory.
• Handler generation with dominant response analysis — Each handler picks the "dominant" 2xx response (json > text > binary > void), determines the HttpResponse construction method, and optionally embeds OpenAPI example values as default body fallbacks.
• Exported per-operation response types — Each handler emits a named type alias (e.g. HandleGetPetByIdResponse) typed as { body: T; status?: N }, where T falls back to msw.DefaultBodyType and N falls back to number when no typed response exists.
• createMswHandlers factory pattern — Generated factory returns { pick, all } where pick provides individually wrapped handlers and all(options?) returns a sorted array of all handlers with optional per-operation overrides via a pick option.
• Route specificity sorting — all() orders handlers by depth-first, static-before-dynamic specificity to prevent parameterized routes from shadowing more specific static routes.
• Path sanitization for MSW — Converts OpenAPI {param} templates to MSW :param syntax, with camelCase normalization for non-word characters and literal colon escaping.
• Type-safe baseUrl via ClientOptions — Generated RequestHandlerOptions.baseUrl type references the TypeScript plugin's ClientOptions['baseUrl'] when available, falling back to string otherwise, ensuring handler base URLs match the client's server URL union.
• Extract getBaseUrl() to @hey-api/shared — Base URL resolution logic (string/number/boolean config to resolved URL) is extracted from client-core into a shared utility, fixing a minor issue where OpenAPI 2.0 host-only server URLs were silently dropped.
• New @hey-api/examples plugin scaffold — Introduces the @hey-api/examples plugin (stub handler for now) as a source-tagged dependency that the MSW plugin references via config.source to control example embedding.
• Rename PluginMockNames to PluginSourceNames — The mocker plugin tag is replaced with source and a new handler tag is added, reflecting the broader role of data-source plugins beyond mocking.
• Plugin configuration — Supports baseUrl (default '*'), responseFallback ('error' | 'passthrough'), source (controls example embedding via @hey-api/examples), plus standard plugin options.
• ToResponseUnion mapped type — When an operation has multiple 2xx responses, a ToResponseUnion<T> utility type is emitted to allow callers to pass any { body, status } combination from the full response map, in addition to the dominant response type.
• Safe text response serialization — Text responses now apply a typeof body === 'string' runtime check, falling back to JSON.stringify(body) for non-string values before passing to HttpResponse.text().
• DefaultBodyType fallback for unknown request bodies — When an operation's body schema is unknown, the handler's body type parameter uses msw.DefaultBodyType instead of indexing into the data type, avoiding incorrect type narrowing.
• Rename orpc.yaml specs to rpc.yaml — Test spec files for oRPC scenarios renamed from orpc.yaml to rpc.yaml in both 3.0.x and 3.1.x.
• Comprehensive tests and documentation — Snapshot tests (3 scenarios: default, source-default, source-disabled), runtime integration tests, type-level tests, a new mockers.yaml test spec, and full documentation replacing the previous placeholder page.

_{Summary ｜ 71 files ｜ 30 commits ｜ base: main ← feat/msw-plugin}

MSW handler generation from OpenAPI operations

Before: No MSW integration existed; the docs page was a placeholder linking to issue #1486.
After: Adding 'msw' to the plugins array generates a msw.gen.ts file with fully typed handler factories for every operation.

Each operation produces a function like handleGetPetById(response?, options?) that returns an HttpHandler. The response parameter accepts either a static { body: T, status?: N } object or an HttpResponseResolver<Params, Body> function. When no response is provided, the handler falls back to a 501 error response or passthrough depending on configuration. When config.source includes '@hey-api/examples' (the default), OpenAPI example values are embedded as fallback defaults on the body accessor (via response?.body ?? defaultValue) rather than as parameter defaults.

Each handler also exports a named response type alias — e.g. HandleGetPetByIdResponse — typed as { body: Responses[200]; status?: 200 } when a typed response exists, or { body: DefaultBodyType; status?: number } as a fallback. When an operation's body schema type is unknown, the handler's body generic uses msw.DefaultBodyType to avoid incorrect type narrowing.

How does dominant response selection work?

The plugin examines all 2xx responses for an operation and selects the "dominant" one based on content type priority: json > text > binary > void. This determines: the TypeScript type for the body parameter, the default status code, and the HttpResponse construction method (.json(), .text(), new HttpResponse(), or Response with no body). The body existence check (body !== undefined) gates whether a response is constructed at all — when examples are present, the fallback ensures a response is always returned without needing the 501/passthrough logic.

How are text responses serialized safely?

Text-type responses use HttpResponse.text(), which expects a string argument. Since the body value may not always be a string at runtime, the generated code emits a typeof body === 'string' ? body : JSON.stringify(body) ternary to ensure safe serialization before passing to HttpResponse.text().

shared/handler.ts · shared/computeDominantResponse.ts · shared/response.ts

createMswHandlers factory and route sorting

Before: N/A — no handler aggregation existed.
After: A generated createMswHandlers(config?) function returns { pick, all } for per-handler or bulk handler setup, with handlers sorted by route specificity.

The pick property exposes individually wrapped handler functions bound to shared config (e.g. baseUrl). The all(options?) method returns a ReadonlyArray<HttpHandler> sorted by specificity — deeper routes first, static segments before dynamic ones — preventing MSW from incorrectly matching parameterized routes before more specific static routes. Per-operation overrides can be passed either as a plain value or as a [response, options] tuple, handled by the internal invoke helper which checks Array.isArray(override) to determine which form was used.

Option	Type	Default	Purpose
baseUrl	string | number | boolean	'*'	Base URL for handler path matching
responseFallback	'error' | 'passthrough'	'error'	Behavior when no response is provided
source	MaybeArray<PluginSourceNames>	['@hey-api/examples']	Controls example embedding via source plugins

v2/plugin.ts · shared/sort.ts · types.ts · config.ts

Type-safe baseUrl derived from ClientOptions

Before: Generated RequestHandlerOptions.baseUrl was typed as string?.
After: The baseUrl property is typed as ClientOptions['baseUrl']? when the TypeScript plugin emits a ClientOptions type, falling back to string otherwise.

The createRequestHandlerOptions function uses plugin.querySymbol to look up the TypeScript plugin's ClientOptions type at generation time. When found, it uses a conditional $if branch to derive the baseUrl type as an indexed access on that symbol, ensuring MSW handler base URLs accept exactly the same server URL union as the generated client. A responseFallback property is also included on RequestHandlerOptions, allowing per-handler override of the global fallback behavior.

shared/types.ts · client-core/client.ts

Extract getBaseUrl() to shared package

Before: resolveBaseUrlString was a private function inside the client-core plugin. OpenAPI 2.0 specs with host-only server URLs (e.g. api.postmarkapp.com/) did not emit a baseUrl in generated client config.
After: Base URL resolution is a public getBaseUrl() utility in @hey-api/shared, consumed by both client-core and the new MSW plugin. Host-only URLs are now correctly emitted.

The extracted function simplifies the client-core code — the old 20-line resolveBaseUrlString + inline URL validation is replaced by a single getBaseUrl(plugin.config.baseUrl ?? true, plugin.context.ir) call, with property building via $if chaining on the $.object().

url.ts · client-core/client.ts

New @hey-api/examples plugin and plugin taxonomy changes

Before: Data-source plugins were tagged as mocker and referenced via PluginMockNames.
After: A new @hey-api/examples plugin scaffold is introduced with a source tag, PluginMockNames is renamed to PluginSourceNames, and a new handler tag is added for the MSW plugin.

The @hey-api/examples plugin currently has a stub handler (() => {}) — its full implementation is deferred. The MSW plugin declares it as a dependency via config.source, which resolveConfig normalizes to an array and adds to plugin.dependencies. This replaces the previous valueSources approach with a plugin-based dependency model where source: [] disables example embedding entirely.

examples/config.ts · examples/types.ts · plugins/types.ts · shared/plugins/types.ts

Tests, specs, and documentation

Before: No MSW test infrastructure; docs page was a feature-status placeholder.
After: Full test coverage across 3 snapshot scenarios, runtime integration tests, type-level tests, the mockers.yaml test spec, and complete plugin documentation.

Snapshot tests in packages/openapi-ts-tests/msw/v2/ cover default, source-default (with examples), and source-disabled (without examples) scenarios. The mockers.yaml spec exercises GET, POST, and PUT operations with varying response content types (json, text, binary) and example values. The openapi-ts-fetch example adds runtime tests verifying actual MSW behavior (static responses, custom resolvers, path params, status codes, void operations, handler overrides) and type tests validating type safety with expectTypeOf. Documentation replaces the placeholder with full installation, usage, and API reference sections.

3.1.x.test.ts · msw.test.ts · msw-types.test-d.ts · msw.md

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ 𝕏}

[mrlubos]

@malcolm-kee from now on the builds should be passing. I'm going to move examples from OpenAPI into their own plugin so they can be freely combined with other sources such as Faker