From f9f6c59760fa7c30b2125cbd5537847cd4150563 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 17:56:21 +0000 Subject: [PATCH] docs(migration): clarify Performance section uses directory mode "writing to a fresh directory" read as just a clean output folder, not output.mode: 'directory' on every plugin. Spells that out and notes that switching to kubb's default file mode changes the numbers substantially, since it costs v5 more than v4, validated against a real run of both modes. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019xRkYw3bDucJ342j15p9yg --- docs/5.x/migration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/5.x/migration.md b/docs/5.x/migration.md index 439485f..2a1c6b5 100644 --- a/docs/5.x/migration.md +++ b/docs/5.x/migration.md @@ -699,7 +699,11 @@ v5 generates code faster than v4, and the gap widens as the spec grows. The numb [`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. +per configuration, both versions writing to a fresh directory. Every plugin runs in directory mode +(one file per schema or operation, `output.mode: 'directory'`) on both versions, so the comparison +stays apples-to-apples. Output mode changes the numbers substantially: switching both versions to +kubb's default file mode instead makes both v4 and v5 slower, but it costs v5 disproportionately +more, so the speedup shrinks to a smaller, flatter number that no longer grows with spec size.