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: 06cd3db

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 17.99544% with 360 lines in your changes missing coverage. Please review.
✅ Project coverage is 38.42%. Comparing base (51d56b3) to head (711b7a0).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
examples/openapi-ts-fetch/src/client/msw.gen.ts	33.13%	99 Missing and 16 partials ⚠️
...penapi-ts/src/plugins/msw/shared/handlerCreator.ts	6.03%	92 Missing and 17 partials ⚠️
packages/openapi-ts/src/plugins/msw/v2/plugin.ts	1.75%	52 Missing and 4 partials ⚠️
.../src/plugins/msw/shared/computeDominantResponse.ts	8.92%	33 Missing and 18 partials ⚠️
...rc/plugins/msw/shared/sortHandlersBySpecificity.ts	12.50%	12 Missing and 2 partials ⚠️
packages/shared/src/utils/url.ts	0.00%	5 Missing and 9 partials ⚠️
...napi-ts/src/plugins/@hey-api/client-core/client.ts	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3570      +/-   ##
==========================================
- Coverage   38.99%   38.42%   -0.58%     
==========================================
  Files         515      533      +18     
  Lines       18901    19991    +1090     
  Branches     5591     6020     +429     
==========================================
+ Hits         7370     7681     +311     
- Misses       9326     9935     +609     
- Partials     2205     2375     +170     

Flag	Coverage Δ
unittests	38.42% <17.99%> (-0.58%)	⬇️

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: cfefe18

[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.

[malcolm-kee]

Simplify types - Only include ToResponseUnion if multiple status code is available.

[malcolm-kee]

I think there are still gap in the API. Right now the generated code use the 'dominant' response to determine if it should use HttpResponse.json or HttpResponse.text etc, but that's conceptually incorrect. OAS supports support multiple response types for a single status code. As a result, other than result and status, the override object should include another property, contentType to allows user to explicitly set the type of response they want.

Again, this is not a blocker because users always can provide custom function, but the type we're providing may be misleading.

[mrlubos]

@malcolm-kee why did you decide to add type tests to this example?

[malcolm-kee]

Hmmm… to make sure it works? Right now perhaps we could still eyeball it, but if we start adding abstraction to the generated code, they may not be so straightforward anymore.

Feel free to remove them if you think you don’t think it makes sense for this project.

[mrlubos]

I'm thinking about moving them to packages/openapi-ts-tests/msw/v2, what do you think? Separate package for testing this plugin

[mrlubos]

@malcolm-kee same question

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hey-api-docs	Ready	Preview, Comment	Mar 25, 2026 11:23pm

[mrlubos]

@malcolm-kee this is a really strong start! I found some errors with the OpenCode spec so I'm going to clean it up either way, here are the changes I've made so far:

1. Fallback base URL to *. It's easier to get something going that way, otherwise I was stuck on the very first step and had to figure out why it's not matching mocks.
2. Removed the _default mocks. It's easy to import and call createMswHandlerFactory() now to get the same result. I was bitten way too many times by the default HTTP clients we generate, not going to repeat the same mistake.
3. Added baseUrl allowing people to define their own default value or pick one from OpenAPI servers.
4. Smaller cleanup to the DSL usage.

I'll continue working on this, the main thing right now is the readability and organization of the generated code

[malcolm-kee]

@mrlubos I'm thinking of adding SSE support if #3657 looks good. But probably after this PR is merged.