From 7d16138a43e44a546fbffc4882420d42a853846a Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 17:34:58 +0000 Subject: [PATCH 1/3] docs(migration): compare kubb v4/v5 against hey-api and orval Adds a "Compared to other codegen tools" section to the migration guide: a benchmark-machine table, per-metric ToolComparison charts (time, memory, files, output size) across small/medium/big specs, and an overall per-tool scorecard with a ranked summary. Mirrors a shorter version into the v5 blog post's speed section. Labels the existing v4-vs-v5 chart bars "kubb v4"/"kubb v5" for clarity now that other tools are compared alongside kubb. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019xRkYw3bDucJ342j15p9yg --- blog/v5.md | 44 ++++++++++++++ docs/5.x/migration.md | 131 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 175 insertions(+) diff --git a/blog/v5.md b/blog/v5.md index 0eeeaba..4b63ebe 100644 --- a/blog/v5.md +++ b/blog/v5.md @@ -59,6 +59,50 @@ Two changes explain the gap. In v4 every plugin bootstrapped its own OpenAPI par The full tables, one per plugin combination, live in the [migration guide](/docs/5.x/migration#performance). +## How v5 compares to hey-api and orval + +v4 was the baseline above. Here's v5 next to the two other TypeScript OpenAPI generators teams +usually put on the shortlist: `@hey-api/openapi-ts@0.99.0` and `orval@8.22.0`. Measured on the same +machine as the numbers above: Linux 6.18.5, an Intel Xeon @ 2.10GHz with 4 cores, 15.7 GB of +memory, Node v22.22.2. + + + + + +hey-api is the fastest tool at every spec size, and its lead over v5 grows with the spec: v5 is +1.4x slower on the small spec and 3.9x slower on the big one. orval sits close to v5 on time but +writes far more files (474 on the medium spec, 3,081 on the big one, versus v5's flat 6), since it +splits output one file per schema by default where v5 stays consolidated. Peak memory, file counts, +and output size for all four tools live in the [migration guide](/docs/5.x/migration#compared-to-other-codegen-tools). + ## A smaller config v4 read the spec through a `pluginOas` entry in the plugins array, and every schema plugin repeated the same schema options like `dateType` and `integerType`. v5 moves spec reading to a top-level `adapter` and the schema options along with it, so each plugin keeps only what it generates. diff --git a/docs/5.x/migration.md b/docs/5.x/migration.md index 9a6641f..68190ec 100644 --- a/docs/5.x/migration.md +++ b/docs/5.x/migration.md @@ -735,6 +735,137 @@ The gap widens on bigger specs. In v4, every plugin bootstrapped its own `plugin parsing ran once per plugin. In v5, `adapterOas` parses the spec once and shares the result across all plugins. +## Compared to other codegen tools + +How does v5 compare outside the kubb family, against `@hey-api/openapi-ts` and `orval`, the two +other TypeScript OpenAPI generators most teams evaluate against kubb? The numbers below add kubb +v4, `@hey-api/openapi-ts@0.99.0`, and `orval@8.22.0` to the same harness. All four tools generate +TypeScript types, an axios client, and Zod schemas, each in its own default output mode, across +three specs of increasing size. The harness lives at +[`scripts/benchmark/kubb-vs-heyapi`](https://github.com/kubb-labs/kubb/tree/main/scripts/benchmark/kubb-vs-heyapi) +in the kubb repository. + +### Benchmark machine + +| | | +| --- | --- | +| OS | Linux 6.18.5 | +| CPU | Intel(R) Xeon(R) Processor @ 2.10GHz | +| Cores | 4 | +| Memory | 15.7 GB | +| Node | v22.22.2 | + + + +### Generation time + + + +hey-api is the fastest tool at every spec size tested, and its lead over kubb v5 grows with the +spec: v5 is 1.4x slower than hey-api on the small spec and 3.9x slower on the big one. Kubb v5 +still pulls ahead of v4 and orval as the spec grows, finishing the big spec 2.6x faster than v4. + +### Peak memory + + + +Kubb v4's peak memory grows linearly with the plugin count and the spec size, reaching 1.28 GB on +the big spec. Kubb v5, hey-api, and orval all stay under 400 MB on the same input. + +### Files generated + + + +Kubb v5 writes 6 files (one per plugin for types, client, and schemas, plus 3 shared runtime +helpers under `.kubb/`) regardless of spec size, since file mode is its default. hey-api's bundled +output stays flat too. Kubb v4 and orval both write one file per schema by default, so their file +counts scale with the spec: orval writes 3,081 files for the big spec, kubb v4 writes 1,379. + +### Output size + + + +Kubb v4's exploded file layout carries per-file boilerplate (imports, banners) that a single +consolidated file doesn't, so it produces the largest output on the medium and big specs even +though it isn't generating more actual types. The small spec doesn't have enough content to spread +that per-file overhead across, so kubb v5's output ends up fractionally larger than v4's there. + +### Overall, on the big spec + + + +Ranking each tool 1st through 4th on every metric and summing the placements (1 point for 1st, +4 for 4th, lowest total wins): + +| Rank | Tool | Points | Wins | +| --- | --- | --- | --- | +| 1 | hey-api | 6 | Time, output size | +| 2 | kubb v5 | 7 | Memory, files | +| 3 | orval | 12 | — | +| 4 | kubb v4 | 15 | — | + +hey-api and kubb v5 trade the lead depending on the metric: hey-api generates faster and produces +smaller output, kubb v5 uses less memory and writes fewer files. Both clear orval and kubb v4 by a +wide margin overall. + ## See also - [Adapters](/docs/5.x/guide/concepts/adapters): how the OpenAPI input is parsed into the universal AST. From ad1450c56270f2fa046be4009016a4635ac9be75 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 17:40:03 +0000 Subject: [PATCH 2/3] revert(migration): drop the hey-api/orval comparison section Not needed in the docs. Keeps the v4-vs-v5 Performance section as-is. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019xRkYw3bDucJ342j15p9yg --- blog/v5.md | 44 -------------- docs/5.x/migration.md | 131 ------------------------------------------ 2 files changed, 175 deletions(-) diff --git a/blog/v5.md b/blog/v5.md index 4b63ebe..0eeeaba 100644 --- a/blog/v5.md +++ b/blog/v5.md @@ -59,50 +59,6 @@ Two changes explain the gap. In v4 every plugin bootstrapped its own OpenAPI par The full tables, one per plugin combination, live in the [migration guide](/docs/5.x/migration#performance). -## How v5 compares to hey-api and orval - -v4 was the baseline above. Here's v5 next to the two other TypeScript OpenAPI generators teams -usually put on the shortlist: `@hey-api/openapi-ts@0.99.0` and `orval@8.22.0`. Measured on the same -machine as the numbers above: Linux 6.18.5, an Intel Xeon @ 2.10GHz with 4 cores, 15.7 GB of -memory, Node v22.22.2. - - - - - -hey-api is the fastest tool at every spec size, and its lead over v5 grows with the spec: v5 is -1.4x slower on the small spec and 3.9x slower on the big one. orval sits close to v5 on time but -writes far more files (474 on the medium spec, 3,081 on the big one, versus v5's flat 6), since it -splits output one file per schema by default where v5 stays consolidated. Peak memory, file counts, -and output size for all four tools live in the [migration guide](/docs/5.x/migration#compared-to-other-codegen-tools). - ## A smaller config v4 read the spec through a `pluginOas` entry in the plugins array, and every schema plugin repeated the same schema options like `dateType` and `integerType`. v5 moves spec reading to a top-level `adapter` and the schema options along with it, so each plugin keeps only what it generates. diff --git a/docs/5.x/migration.md b/docs/5.x/migration.md index 68190ec..9a6641f 100644 --- a/docs/5.x/migration.md +++ b/docs/5.x/migration.md @@ -735,137 +735,6 @@ The gap widens on bigger specs. In v4, every plugin bootstrapped its own `plugin parsing ran once per plugin. In v5, `adapterOas` parses the spec once and shares the result across all plugins. -## Compared to other codegen tools - -How does v5 compare outside the kubb family, against `@hey-api/openapi-ts` and `orval`, the two -other TypeScript OpenAPI generators most teams evaluate against kubb? The numbers below add kubb -v4, `@hey-api/openapi-ts@0.99.0`, and `orval@8.22.0` to the same harness. All four tools generate -TypeScript types, an axios client, and Zod schemas, each in its own default output mode, across -three specs of increasing size. The harness lives at -[`scripts/benchmark/kubb-vs-heyapi`](https://github.com/kubb-labs/kubb/tree/main/scripts/benchmark/kubb-vs-heyapi) -in the kubb repository. - -### Benchmark machine - -| | | -| --- | --- | -| OS | Linux 6.18.5 | -| CPU | Intel(R) Xeon(R) Processor @ 2.10GHz | -| Cores | 4 | -| Memory | 15.7 GB | -| Node | v22.22.2 | - - - -### Generation time - - - -hey-api is the fastest tool at every spec size tested, and its lead over kubb v5 grows with the -spec: v5 is 1.4x slower than hey-api on the small spec and 3.9x slower on the big one. Kubb v5 -still pulls ahead of v4 and orval as the spec grows, finishing the big spec 2.6x faster than v4. - -### Peak memory - - - -Kubb v4's peak memory grows linearly with the plugin count and the spec size, reaching 1.28 GB on -the big spec. Kubb v5, hey-api, and orval all stay under 400 MB on the same input. - -### Files generated - - - -Kubb v5 writes 6 files (one per plugin for types, client, and schemas, plus 3 shared runtime -helpers under `.kubb/`) regardless of spec size, since file mode is its default. hey-api's bundled -output stays flat too. Kubb v4 and orval both write one file per schema by default, so their file -counts scale with the spec: orval writes 3,081 files for the big spec, kubb v4 writes 1,379. - -### Output size - - - -Kubb v4's exploded file layout carries per-file boilerplate (imports, banners) that a single -consolidated file doesn't, so it produces the largest output on the medium and big specs even -though it isn't generating more actual types. The small spec doesn't have enough content to spread -that per-file overhead across, so kubb v5's output ends up fractionally larger than v4's there. - -### Overall, on the big spec - - - -Ranking each tool 1st through 4th on every metric and summing the placements (1 point for 1st, -4 for 4th, lowest total wins): - -| Rank | Tool | Points | Wins | -| --- | --- | --- | --- | -| 1 | hey-api | 6 | Time, output size | -| 2 | kubb v5 | 7 | Memory, files | -| 3 | orval | 12 | — | -| 4 | kubb v4 | 15 | — | - -hey-api and kubb v5 trade the lead depending on the metric: hey-api generates faster and produces -smaller output, kubb v5 uses less memory and writes fewer files. Both clear orval and kubb v4 by a -wide margin overall. - ## See also - [Adapters](/docs/5.x/guide/concepts/adapters): how the OpenAPI input is parsed into the universal AST. From 47b92fcf5d31b24ec10602b41b4e7d248f7c7464 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 17:41:13 +0000 Subject: [PATCH 3/3] docs(migration): add a benchmark-machine table to the Performance section Replaces the vague "measured on the CI runner" note with the actual OS, CPU, core count, memory, and Node version used. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019xRkYw3bDucJ342j15p9yg --- docs/5.x/migration.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/5.x/migration.md b/docs/5.x/migration.md index 9a6641f..439485f 100644 --- a/docs/5.x/migration.md +++ b/docs/5.x/migration.md @@ -703,9 +703,19 @@ per configuration, both versions writing to a fresh directory so the comparison +### Benchmark machine + +| | | +| --- | --- | +| OS | Linux 6.18.5 | +| CPU | Intel(R) Xeon(R) Processor @ 2.10GHz | +| Cores | 4 | +| Memory | 15.7 GB | +| Node | v22.22.2 | + > [!NOTE] -> 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. +> Absolute milliseconds and megabytes are hardware-dependent. Treat the speedup and +> memory-reduction percentages as the portable takeaway. **`petStore.yaml`**, 21 operations