From 19ece7e8c3c8aec5ba702ce21278c36384575fb5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 16:44:57 +0000 Subject: [PATCH 1/2] docs(migration): refresh v5 performance numbers with a real benchmark run The Performance section carried unsourced numbers with no reproducible script behind them and no memory data. Replace them with a real run of kubb-labs/kubb's scripts/benchmark/v4-vs-v5 harness against the current v4 (4.39.2) and v5 beta (5.0.0-beta.104), covering both time and memory, and embed the SpeedComparison chart. Update the v5 blog post's numbers (6x -> 5x, openai spec grew from 242 to 281 operations) to match. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019xRkYw3bDucJ342j15p9yg --- blog/v5.md | 14 ++++----- docs/5.x/migration.md | 67 ++++++++++++++++++++++++++++--------------- 2 files changed, 51 insertions(+), 30 deletions(-) diff --git a/blog/v5.md b/blog/v5.md index 6fb804f..0eeeaba 100644 --- a/blog/v5.md +++ b/blog/v5.md @@ -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 @@ -29,9 +29,9 @@ globalThis.addEventListener?.("load", (event) => { @@ -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). -## 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. -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. diff --git a/docs/5.x/migration.md b/docs/5.x/migration.md index 3aab3c4..69fd20d 100644 --- a/docs/5.x/migration.md +++ b/docs/5.x/migration.md @@ -695,36 +695,57 @@ 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. + + > [!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%** | - -**`openai.yaml`**, 242 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%** | - -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. +| 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`**, 281 operations, 2.7 MB ([openai/openai-openapi](https://github.com/openai/openai-openapi)) + +| 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, which is why memory stays close to flat for v5 as the spec grows while v4's climbs with +every additional plugin. + +Memory is more nuanced than speed. On the small `petStore.yaml` spec, v5 actually uses more memory +than v4. The shared adapter and its AST layer carry fixed overhead that a 21-operation spec is too +small to amortize. That overhead shrinks in relative terms as the spec grows: at 80 operations, v5 +already uses less memory than v4, and by 281 operations v5 holds a roughly flat memory footprint +while v4's grows linearly with the plugin count. The memory savings compound alongside the speed +gains. + +The `openai.yaml` operation count above reflects the spec's current size, and will keep growing since +the harness fetches it live from the upstream repository. Re-running the benchmark later means +comparing against a bigger spec than this page shows, which is expected. ## See also From 2687412c81189ce8bbd5dac81c075778d78454ba Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 16:50:55 +0000 Subject: [PATCH 2/2] docs(migration): trim extra Performance section prose Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019xRkYw3bDucJ342j15p9yg --- docs/5.x/migration.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/docs/5.x/migration.md b/docs/5.x/migration.md index 69fd20d..9a6641f 100644 --- a/docs/5.x/migration.md +++ b/docs/5.x/migration.md @@ -733,19 +733,7 @@ per configuration, both versions writing to a fresh directory so the comparison 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, which is why memory stays close to flat for v5 as the spec grows while v4's climbs with -every additional plugin. - -Memory is more nuanced than speed. On the small `petStore.yaml` spec, v5 actually uses more memory -than v4. The shared adapter and its AST layer carry fixed overhead that a 21-operation spec is too -small to amortize. That overhead shrinks in relative terms as the spec grows: at 80 operations, v5 -already uses less memory than v4, and by 281 operations v5 holds a roughly flat memory footprint -while v4's grows linearly with the plugin count. The memory savings compound alongside the speed -gains. - -The `openai.yaml` operation count above reflects the spec's current size, and will keep growing since -the harness fetches it live from the upstream repository. Re-running the benchmark later means -comparing against a bigger spec than this page shows, which is expected. +all plugins. ## See also