Skip to content

Refresh v5 migration guide performance numbers with a real benchmark run #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stijnvanhulle merged 2 commits into from
Jul 18, 2026
Merged

Refresh v5 migration guide performance numbers with a real benchmark run #159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19ece7e
docs(migration): refresh v5 performance numbers with a real benchmark…
claude Jul 18, 2026
2687412
docs(migration): trim extra Performance section prose
claude Jul 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions blog/v5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: doc
title: Release of Kubb 5.0
description: Kubb 5.0 rebuilds code generation around adapters, a universal AST, parsers, and storage, and generates code up to 6x faster than v4.
description: Kubb 5.0 rebuilds code generation around adapters, a universal AST, parsers, and storage, and generates code up to 5x faster than v4.
outline: deep
image: /blog/v5/cover.svg
date: 2026-07-09
Expand Down Expand Up @@ -29,9 +29,9 @@ globalThis.addEventListener?.("load", (event) => {

<script setup>
const highlights = [
{ value: 6, prefix: 'up to ', suffix: '×', label: 'faster than v4' },
{ value: 5, prefix: 'up to ', suffix: '×', label: 'faster than v4' },
{ value: 1, label: 'shared AST, parsed once' },
{ value: 242, label: 'OpenAI operations in 2.5s' },
{ value: 281, label: 'OpenAI operations in 5.9s' },
]
</script>

Expand All @@ -43,17 +43,17 @@ Published: 2026-05-26

Kubb generates TypeScript types, an Axios or Fetch client, Zod schemas, TanStack Query hooks, Faker mocks, and MSW handlers from an OpenAPI spec. v5 rewrites how it does that. One [adapter](/docs/5.x/guide/concepts/adapters) parses your spec into a universal [AST](/docs/5.x/guide/concepts/ast), plugins walk that AST, [parsers](/docs/5.x/guide/concepts/parsers) turn the result into source code, and [storage](/docs/5.x/guide/concepts/storage) writes it to disk.

You feel that rewrite in three places: your config gets shorter, your generated client calls change shape, and generation runs up to six times faster. The sections below show each one. For a before and after on every breaking change, read the [migration guide](/docs/5.x/migration).
You feel that rewrite in three places: your config gets shorter, your generated client calls change shape, and generation runs up to five times faster. The sections below show each one. For a before and after on every breaking change, read the [migration guide](/docs/5.x/migration).

<StatHighlights :items="highlights" />

## Up to 6x faster generation
## Up to 5x faster generation

The [OpenAI spec](https://github.com/openai/openai-openapi) is 242 operations across 2.7 MB of YAML. Generating types, an Axios client, Zod schemas, and Faker mocks from it took 14.9 seconds in v4. v5 does the same work in 2.5 seconds.
The [OpenAI spec](https://github.com/openai/openai-openapi) is 281 operations across 2.7 MB of YAML. Generating types, an Axios client, Zod schemas, and Faker mocks from it took 31.2 seconds in v4. v5 does the same work in 5.9 seconds.

<SpeedComparison />

Each run uses `plugin-ts` with the Axios, Zod, and Faker plugins, on a 4-core Intel Xeon with file writing disabled, so the numbers reflect the pipeline alone.
Each run uses `plugin-ts` with the Axios, Zod, and Faker plugins, median of three runs, both versions writing to disk.

Two changes explain the gap. In v4 every plugin bootstrapped its own OpenAPI parser, so a config with four plugins read the same spec four times. In v5 the adapter parses it once and hands the same AST to every plugin. The renderer changed too: v5 prints synchronously and drops the React runtime that v4 loaded to render files. The larger the spec, the more that parse-once saving compounds, which is why the OpenAI numbers move the most.

Expand Down
49 changes: 29 additions & 20 deletions docs/5.x/migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -695,36 +695,45 @@ Once the config compiles, confirm the output:

## Performance

v5 generates code faster than v4. The benchmarks compare `@kubb/core@4.37.8` with the v5 `kubb` meta-package, with file writing disabled so the numbers reflect the generation pipeline alone.
v5 generates code faster than v4, and the gap widens as the spec grows. The numbers below come from
[`scripts/benchmark/v4-vs-v5`](https://github.com/kubb-labs/kubb/tree/main/scripts/benchmark/v4-vs-v5)
in the kubb repository, a harness anyone can run and reproduce. It benchmarks `@kubb/core@4.39.2`
against the v5 beta (`@kubb/core@5.0.0-beta.104`, plugins at `5.0.0-beta.103`), median of three runs
per configuration, both versions writing to a fresh directory so the comparison stays apples-to-apples.

<SpeedComparison />

> [!NOTE]
> Measured on a 4-core Intel Xeon @ 2.80 GHz, Linux. Speedup is the headline. Absolute milliseconds are hardware-dependent.
> Measured on the CI runner that generated this page. Absolute milliseconds and megabytes are
> hardware-dependent. Treat the speedup and memory-reduction percentages as the portable takeaway.

**`petStore.yaml`**, 19 operations
**`petStore.yaml`**, 21 operations

| Plugins | v4 mean | v5 mean | Speedup |
| ------------------------------------------------------------- | --------- | -------- | --------- |
| `plugin-ts` | 130.53 ms | 66.03 ms | **+98%** |
| `plugin-ts` + `plugin-axios` | 198.64 ms | 76.77 ms | **+159%** |
| `plugin-ts` + `plugin-axios` + `plugin-zod` + `plugin-faker` | 331.90 ms | 99.07 ms | **+235%** |
| Plugins | v4 time | v5 time | Speedup | v4 memory | v5 memory | Memory |
| ------------------------------------------------------------- | ------- | ------- | --------- | --------- | --------- | ---------- |
| `plugin-ts` | 579 ms | 345 ms | **+68%** | 13.0 MB | 23.4 MB | -80% |
| `plugin-ts` + `plugin-axios` | 630 ms | 384 ms | **+64%** | 15.8 MB | 24.5 MB | -55% |
| `plugin-ts` + `plugin-axios` + `plugin-zod` + `plugin-faker` | 954 ms | 398 ms | **+140%** | 19.5 MB | 25.1 MB | -29% |

**`twitter.json`**, 80 operations, 374 KB

| Plugins | v4 mean | v5 mean | Speedup |
| ------------------------------------------------------------- | -------- | ------- | --------- |
| `plugin-ts` | 1,486 ms | 375 ms | **+296%** |
| `plugin-ts` + `plugin-axios` | 1,743 ms | 401 ms | **+335%** |
| `plugin-ts` + `plugin-axios` + `plugin-zod` + `plugin-faker` | 2,997 ms | 711 ms | **+322%** |
| Plugins | v4 time | v5 time | Speedup | v4 memory | v5 memory | Memory |
| ------------------------------------------------------------- | -------- | -------- | ---------- | --------- | --------- | ------ |
| `plugin-ts` | 2,993 ms | 1,071 ms | **+179%** | 110.6 MB | 60.2 MB | **+46%** |
| `plugin-ts` + `plugin-axios` | 3,560 ms | 1,160 ms | **+207%** | 115.5 MB | 59.7 MB | **+48%** |
| `plugin-ts` + `plugin-axios` + `plugin-zod` + `plugin-faker` | 5,928 ms | 1,674 ms | **+254%** | 179.3 MB | 68.5 MB | **+62%** |

**`openai.yaml`**, 242 operations, 2.7 MB ([openai/openai-openapi](https://github.com/openai/openai-openapi))
**`openai.yaml`**, 281 operations, 2.7 MB ([openai/openai-openapi](https://github.com/openai/openai-openapi))

| Plugins | v4 mean | v5 mean | Speedup |
| ------------------------------------------------------------- | --------- | -------- | --------- |
| `plugin-ts` | 6,033 ms | 1,450 ms | **+316%** |
| `plugin-ts` + `plugin-axios` | 7,662 ms | 1,544 ms | **+396%** |
| `plugin-ts` + `plugin-axios` + `plugin-zod` + `plugin-faker` | 14,943 ms | 2,461 ms | **+507%** |
| Plugins | v4 time | v5 time | Speedup | v4 memory | v5 memory | Memory |
| ------------------------------------------------------------- | --------- | -------- | ---------- | --------- | --------- | ------ |
| `plugin-ts` | 14,775 ms | 3,600 ms | **+310%** | 442.4 MB | 146.3 MB | **+67%** |
| `plugin-ts` + `plugin-axios` | 16,611 ms | 3,891 ms | **+327%** | 501.8 MB | 148.0 MB | **+70%** |
| `plugin-ts` + `plugin-axios` + `plugin-zod` + `plugin-faker` | 31,205 ms | 5,887 ms | **+430%** | 898.0 MB | 149.3 MB | **+83%** |

The gap widens on bigger specs. In v4, every plugin bootstrapped its own `pluginOas` instance, so parsing ran once per plugin. In v5, `adapterOas` parses the spec once and shares the result across all plugins.
The gap widens on bigger specs. In v4, every plugin bootstrapped its own `pluginOas` instance, so
parsing ran once per plugin. In v5, `adapterOas` parses the spec once and shares the result across
all plugins.

## See also

Expand Down