Changelog
v5.21.2
Latestpatch@kubb/ast
Add ast.json.stringify and ast.json.parse to cache a parsed spec or send it to another thread or process.
ast.json.stringify(input)writes every schema a ref points at once. A plainJSON.stringify(input)writes it again at every ref, which made a 618-schema spec 76 MB instead of 10 MB.ast.json.parse(text)returns theInputNode, with refs to one schema sharing one object again.
import { ast } from 'kubb/kit'
const text = ast.json.stringify(input)
const restored = ast.json.parse(text)(#4663)
@kubb/core
beta to kubb-extension.json and ExtensionManifest. Set "beta": true while an extension is in beta. kubb.dev and Kubb Studio then show a Beta badge next to its name. (#4671)v5.21.1
patch@kubb/core
ctx.schemas. ctx.driver is deprecated: use ctx.schemas, ctx.getPlugin, ctx.getResolver and ctx.memo instead. It will be removed in the next major version. (#4655)v5.21.0
minor@kubb/adapter-oas
type: string, format: byte is now a string instead of a Blob. OpenAPI defines byte as base64-encoded text, and contentEncoding: base64 already gave a string. Generated types change: fields that were Blob are now string, and plugin-zod now emits z.base64() for them. (#4651)@scalar/openapi-upgrader 0.4.9. (#4646)unplugin-kubb
kubb/farm and unplugin-kubb/farm now work with Farm 2. The @farmfe/core peer range is ^1.7.0 || ^2.0.0, so Farm 1 projects keep working. (#4647)v5.20.3
patchunplugin-kubb
An import of a config's input file now loads as a spec module whatever its name, so import { Pet } from './my-api.openapi.json' works when input is ./my-api.openapi.json. Before, only *.openapi.yaml and *.openapi.yml imports loaded. Other specs still need one of those names.
Spec modules load as JavaScript in every bundler, so esbuild, Rolldown and Vite no longer parse a .json spec as JSON. If your app imports its input file as plain JSON data, that import now returns the generated module instead. (#4644)
v5.20.2
patch@kubb/adapter-oas
export type statement and that a path outside the output root fails with KUBB_PATH_TRAVERSAL. (#4634)@kubb/cli
kubb generate, validate, mcp, and studio exit as soon as their work is done. Before, the process waited up to a second for the request, about 350–500 ms on a typical connection. (#4632)@kubb/core
GeneratorContext.root is the build's output directory, the same for every plugin, not the current plugin's folder. The default group.name for path groups camelCases the first path segment. Adapter.sources no longer claims that a watcher rebuilds from it: kubb generate --watch watches only input. (#4634)kubb
kubb now depends on @kubb/kit and @kubb/renderer-jsx with a caret range, like @kubb/core, so a plugin built against a newer patch or minor shares one copy with kubb instead of installing a second one. (#4628)v5.20.1
patch@kubb/cli
kubb studio keeps the agent key in the system keychain: macOS Keychain, Windows Credential Manager, or Secret Service on Linux. (#4624)v5.20.0
minor@kubb/adapter-oas
Add pathParamsCasing: 'camelcase' to adapterOas(). It renames path parameters and their {placeholder} in the operation path, so GET /pets/{pet-id} is called as getPet({ path: { petId } }). (#4621)
{pet-id},{pet_id}, and{PetId}all becomepetId, the name MSW routes and query keys then use too. Colliding names get a counter suffix (groupId,groupId2).- Query, header, cookie, and body names stay as the spec writes them, and the HTTP request is unchanged.
@kubb/kitaddsUrl.toParamNames, which maps each placeholder to a unique camelCase name.
@kubb/cli
kubb studio no longer forgets a token another process stored while its own was being rejected. (#4622)v5.19.2
patch@kubb/studio
kubb studio keeps a connected project paired. (#4619)
- The CLI renews its token once a day while connected.
- Pairing creates a key that stays on the machine.
@kubb/studioaddsrefreshAgentTokenandgenerateAgentKey.
v5.19.1
patch@kubb/adapter-oas
Harden the Kubb Studio agent against specs it does not control. (#4616)
- On a Studio agent, a
$refonly reads local files inside the project and the folder of the config's own input file. A sandbox agent reads none, and a managed agent only inside the checkout of a git input.kubb studio --allow-file-refslifts the project limit, andkubb generateis unchanged. - A URL input no longer reads local files through a
$ref. - A sandbox agent only fetches a URL
$reffrom public addresses, and a managed agent only checks out a git input from them. - Only the host's new
agentTypeoption ofconnectAgent, set to'sandbox'or'global', lets Studio read a sandbox's output. Studio's own flag no longer does. - Studio can no longer save an
inputoutside the project, or anoutput.pathoutside the output folder. createKubband an adapter'sparsetakefileRefs, the folders a$refmay read from.
v5.19.0
minor@kubb/core
memo now also caches in a store you own: memo(store, key, compute) takes a Map or WeakMap and needs no build. memo.create() creates a store, and memo.create({ weak: true }) one that frees an entry with its key. (#4612)memo.create({ max }) creates a bounded store: it empties itself before the entry that would pass max, so a cache in a long-running process cannot grow without end. max: 1 keeps only the last entry. (#4614)v5.18.8
patch@kubb/adapter-oas
$id and $anchor targets, and Swagger 2.0 path refs, and builds JSON pointers only when a spec has an $id or $anchor. On large specs the adapter parses about 0.2 s sooner. (#4610)kubb generate prints the same locations about 16 s sooner and peaks about 620 MB lower. A large JSON spec peaks about 70 MB higher. (#4594)@kubb/ast
ast.schema.find takes an optional cache (a WeakMap you keep per predicate), so repeated searches with followRefs skip parts of the schema graph they already searched. (#4600)@kubb/cli
kubb generate start the build as soon as the config loads in an interactive terminal, instead of waiting for the mascot animation to finish. A small spec now finishes about 0.8 seconds sooner, with the same final output. (#4604)output.clean: hashing each line of the old output no longer copies it into an array of characters, and a regenerated file with a different length skips the SHA-1 check. The summary is the same. (#4608)kubb generate faster on most runs: it asks npm for a newer version at most once every 24 hours, keeps the answer in ~/.kubb/cache, and never asks in CI. (#4605)Rerun kubb generate with less memory and time: the "File changes" summary no longer reads the whole output folder up front. (#4597)
- Add
storedtokubb:file:processed: what the storage held at that path before the write, ornullwhen there was nothing.
@kubb/core
memo hit with one map read. On the 45 MB Microsoft Graph spec, kubb generate uses about 3% less CPU, with the same output. (#4602)kubb generate writes and compares output files faster: it reads a stored file synchronously, skips the read for a file that is not on disk, and writes through the callback fs API instead of fs/promises. The files on disk stay the same. (#4599)@kubb/kit
text.quote about 13 times faster, with the same output. (#4594)v5.18.7
patch@kubb/adapter-oas
unknownType and emptySchemaType describe the schemas they cover, and parserMd().print is documented as joining strings. (#4589)@kubb/cli
kubb add --dry-run and kubb remove --dry-run now stop after the preview instead of installing packages and editing kubb.config.ts. A config function receives the reporters selected with --reporter, and the kubb studio snapshot error names the --package-version flag. (#4591)kubb generate --reporter json now writes the run log to stderr. Stdout still holds only the JSON report. (#4592)@kubb/core
Kubb.generate(configs), which builds every config of a defineConfig([...]) array and keeps going when one fails. kubb generate, kubb update, unplugin-kubb and kubb studio snapshot now use it. (#4592)type: 'method' filter now matches in either case, so the documented pattern: 'GET' selects operations like 'get' does. An override entry's output gets its mode from output.path, which fixes the No extname found crash for output: { path: 'admin' }. Core now emits kubb:generation:summary after kubb:generation:end, and the KUBB_PATH_TRAVERSAL message for a resolver file.path names the output directory. (#4591)@kubb/studio
kubb studio snapshot now publishes every entry of a defineConfig([...]) array in one package. createSnapshot takes configs in place of config. (#4592)v5.18.6
patch@kubb/ast
Add shared helpers for plugins: ast.ref, ast.graph, ast.schema, ast.mediaType, ast.http, ast.server and ast.auth in @kubb/ast, casing and text in @kubb/kit, and resolver.groupDir in @kubb/core. (#4583)
@kubb/adapter-oasspreads a form-encoded OpenAPI 3.2querystringobject into one query parameter per property.@kubb/adapter-oasreads anyapplication/*+json-seqtype as a stream, and readsmultipart/mixedas one only when it declaresitemSchema.resolver.imports({ checks: true })skips refs in checks that cannot fail.
The top-level ref, graph and schema helpers on ast, ast.isHttpOperationNode, ast.collectSync, ast.optionality, ast.extractStringsFromNodes, ast.compareEnforce, ast.applyMacros, ast.nodeKinds, ast.schemaTypes, ast.findSchema, ast.narrowSchema, ast.transform, ast.collect, ast.inlineFiles (now under ast.macro, ast.node, ast.schema and ast.file), ast.createPrinter and ast.defineMacro (now createPrinter and defineMacro from @kubb/kit), and camelCase, pascalCase, extractRefName, syncSchemaRef, isStringType and containsCircularRef from @kubb/kit are deprecated. Each one's JSDoc names its replacement. Kubb v6 removes them.
v5.18.5
patch@kubb/adapter-oas
text/event-stream item whose event sits next to payload fields, such as Scalar Galaxy's { event, planet, note }, as the event's data instead of the whole event. Before, mocks dropped planet and note, the type put them on the event, and the client never filled them. An item that declares data, or only the SSE fields event, id and retry, is still read as the whole event. (#4581)v5.18.4
patch@kubb/adapter-oas
data of a text/event-stream event from its contentSchema when the event is a $ref to a component, as a oneOf member or as the whole itemSchema, the same as inline events. The component itself keeps data as a string wherever it is used outside the stream. (#4579)v5.18.3
patch@kubb/ast
../) now come before sibling imports (./). (#4577)v5.18.2
patch@kubb/adapter-oas
Fix schemas found in real OpenAPI documents. (#4574)
- An
allOfmember that points at an alias$refgives its properties to arequired-only sibling, where they wereunknown. - A discriminator member with a nullable enum keeps its own value, where it got the schema name.
- A boolean schema (
trueorfalse) no longer stops the run. - A
contentparameter keeps itsencodingon the newParameterNode.encodingfield.
v5.18.1
patch@kubb/adapter-oas
servers list now gets its path item's servers, since an empty list overrides nothing. (#4570)$ref together with its target. Such a schema used to become a plain copy of the target, so its own description, required, properties, if/then/else, dependentRequired and dependentSchemas were dropped. An allOf next to the $ref keeps its members, and an allOf member's conditionals are no longer replaced by the ones of the schema around it. (#4570)@kubb/ast
2XX into 2xx, and StatusCode lists 2xx to 5xx. The response pointer keeps the key as the document spells it. camelCase and pascalCase keep a range such as 2xx as one word, so listPets Status 2xx becomes listPetsStatus2xx instead of listPetsStatus2Xx. (#4572)include filtering and imports now see the schemas inside conditionals, contains and a string's content. findCircularSchemas and collectUsedSchemaNames follow refs in these fields, so a cycle through them is detected and an include filter keeps a schema only they reference. resolver.imports and collectImportedRefNames add those refs only with checks: true, which a plugin that prints these checks passes. transform and collect still skip these fields. (#4570)v5.18.0
minor@kubb/adapter-oas
Read the OpenAPI 3.0, 3.1 and 3.2 fields the adapter skipped, so plugins get every field that affects generated code. (#4561)
metagetssummary,termsOfService,contact,license,externalDocs,tagsandauth.OperationNodegetsexternalDocsandauth,ResponseNodegetssummary,headersandlinks, andParameterNodegetsexamples,deprecatedandallowEmptyValue.- Schema nodes get
externalDocsandconditionals, array nodes getcontains, and string nodes getcontent. - A
$refto a schema's$id,$anchoror$dynamicAnchor, and a$dynamicRef, resolve like a local$ref.$selfsets the base URI that relative$refs resolve against. - A discriminator without
propertyNameand a response withoutdescriptionparse. - Deprecated:
minPropertiesandmaxPropertieson object nodes (useminandmax), andexclusiveMinimumandexclusiveMaximumon number nodes (useexclusive: { min, max }). These fields stay filled and are removed in Kubb v6. - Removed:
meta.securitySchemesandInputSecuritySchemeare replaced bymeta.authandAuthScheme.
// before: meta.securitySchemes
{ name: 'api_key', type: 'apiKey', in: 'header', parameterName: 'X-API-Key' }
// after: meta.auth
{ name: 'api_key', credential: { type: 'apiKey', in: 'header', name: 'X-API-Key' } }v5.17.1
patch@kubb/adapter-oas
format: binary body as a blob when its schema also has a description, title, example, or another annotation. The OpenAPI 3.1 upgrade drops format: binary and leaves the annotation, so the body became unknown. The annotation is kept on the blob schema. (#4559)contentType ('') instead of the request's media type. A body-less 304 on an operation with a text/plain request body was typed as string, while the client returns undefined. The adapter contentType option no longer adds its media type to a response without content either. (#4559)oneOf/anyOf without the discriminant intersection. Only an object can carry the discriminator property, so ContentDirectory & { type: 'array' } matched no value and Zod rejected every directory listing. (#4559)KUBB_UNSUPPORTED_FORMAT once per format, at the first schema that uses it, with the number of schemas that use it. The Stripe spec printed 826 warnings for three formats and now prints three. (#4559)v5.17.0
minor@kubb/adapter-oas
servers declared on a path item or an operation, such as an upload or streaming host. OperationNode gets an optional servers field from the operation's servers, else its path item's, mapped the same way as InputMeta.servers: entries without a url are dropped and variable defaults are filled in. The field is absent when neither declares servers, so plugins fall back to the document's servers. (#4554)v5.16.1
patch@kubb/adapter-oas
KUBB_DUPLICATE_DISCRIMINATOR when two oneOf/anyOf members pin the declared discriminator property to the same value, pointing at the union in the spec. Such a union can't pick a branch, and Zod's z.discriminatedUnion throws Duplicate discriminator value on the first parse. (#4538)@kubb/kit
macroSimplifyUnion as a deprecated alias of macroDedupeUnion. A plugin built before the rename in 5.16, such as @kubb/plugin-axios 5.12, imports the old name and crashed with Cannot read properties of undefined (reading 'input') in composeMacros. Update the import to macroDedupeUnion; the alias goes away in the next major. (#4552)v5.16.0
minor@kubb/adapter-oas
Read the OpenAPI 3.2 fields for streamed responses, so plugins can type text/event-stream, JSON Lines, NDJSON and JSON Text Sequence content. (#4541)
ContentNodegetsstreamwith the itemschemaandshapefor a stream of items.schemaholds the same item node, so a plugin that only readsschematypes one item.- A
text/event-streamitem schema becomes one event type peroneOfmember, witheventas a literal anddatatyped fromcontentSchema. - The adapter also reads
in: querystringparameters,$refs intocomponents.mediaTypes,additionalOperations, anddiscriminator.defaultMapping.
text/event-stream:
itemSchema:
required: [event]
properties:
event: { type: string }
data: { type: string }
oneOf:
- properties:
event: { const: message_delta }
data: { contentMediaType: application/json, contentSchema: { $ref: '#/components/schemas/MessageDelta' } }
- properties:
event: { const: ping }type StreamEvent = { event: 'message_delta'; data?: MessageDelta } | { event: 'ping'; data?: string }@kubb/kit
Keep the enum values in a union of a plain scalar and an enum, such as anyOf: [{ type: string }, { type: string, enum: [gpt-a, gpt-b] }]. Before, the enum was dropped and the union generated as plain string or z.string(). With @kubb/plugin-ts and @kubb/plugin-zod it now generates (string & {}) | 'gpt-a' | 'gpt-b' and z.union([z.string(), z.enum(['gpt-a', 'gpt-b'])]).
Rename macroSimplifyUnion to macroDedupeUnion, since it now only drops repeated union members. Update imports from kubb/kit or @kubb/kit to the new name. (#4536)
v5.15.4
patch@kubb/adapter-oas
minimum, maximum, exclusiveMinimum, exclusiveMaximum or multipleOf, so { type: integer, enum: [0, 1], minimum: 1 } generates 1 instead of 0 | 1. The matching x-enumNames and x-enumDescriptions entries are dropped with them. (#4526)JSON.parse, about ten times faster than js-yaml on the same file. A duplicate key in JSON input now keeps the last value, as every JSON parser does, instead of failing with KUBB_INVALID_DOCUMENT. YAML input is unchanged and still rejects duplicate keys. (#4522)Keep the values of an enum that also has a format, such as type: integer, format: int32. These enums generated as a plain number (or z.int32()) and now generate a union of their values, such as 0 | 1 | 2, under the same type name. Enums whose format prints as Date, bigint or Blob are unchanged.
Keep each x-enumNames and x-enumDescriptions entry with its own value when the enum holds null, such as enum: [null, 0, 1]. Before, the names shifted by one and the last one was dropped. (#4526)
v5.15.3
patch@kubb/cli
Make kubb generate up to 4 times faster on large specs that raise many diagnostics or write thousands of files.
- Index the spec once per run for diagnostic code frames, instead of splitting it into lines for every diagnostic. Cloudflare's 27.7 MB spec, with 239 deprecation notices, drops from 60 s to about 14 s.
- Count the "File changes" summary from each file as it is written, instead of reading the whole output back afterwards, and read the previous output while the plugins generate.
- Print only the start and end of the write in plain output, such as CI logs and piped runs, instead of one line per file.
--log-level verbosestill lists every file. - Add the
kubb:file:processedhook, which carries each file's source as it is handed to the storage. (#4517)
v5.15.2
patch@kubb/adapter-oas
@kubb/core and @kubb/ast as caret ranges instead of exact versions. A plugin that pulls in a newer @kubb/parser-ts, @kubb/kit, or @kubb/renderer-jsx can now share the project's @kubb/core and @kubb/ast when the project's version is the same or newer, instead of installing a second copy. (#4513)@kubb/ast
Remove InputMeta.circularNames and InputMeta.enumNames, so InputMeta only holds plain document metadata. A generator that needs either set builds it once per build with ctx.memo:
const schemas = ctx.driver.inputNode?.schemas ?? []
const circularNames = ctx.memo('circularNames:set', () => ast.findCircularSchemas(schemas))
const enumNames = ctx.memo('enumNames:set', () => new Set(schemas.flatMap((schema) => (schema.type === 'enum' && schema.name ? [schema.name] : []))))BannerMeta loses both fields too. Kubb Studio now stores and sends meta as it is. (#4508)
Remove exports that nothing in Kubb or the official plugins used, and trim the code behind the rest. Generated output does not change.
- Remove
ast.forEachChild,ast.forEachSchema,ast.composeMacros,ast.isVirtualFile,ast.findCircularSchemasFromGraph, and theParentOftype.VisitorContextis now{ parent?: Node }. Useast.collectto walk nodes andast.applyMacrosto run macros. - Remove
macroRenameSchemafromkubb/kit. The macros guide shows its source to copy into your project. - Warn with a
DeprecationWarningwhen a printer handler returns a TypeScript compiler node toprintfrom@kubb/parser-ts. Compiler nodes still print, and support for them is removed in the next major; return a string. - Remove
Hookable.setMaxListenersand theKubbInfoContext,KubbSuccessContext, andKubbWarnContextaliases ofKubbMessageContext. - Remove
ctx.cacheand theNodeCachetype, soctx.memoandresolver.memoare the one way to cache. Replacectx.cache.ensureItem(key, compute)withctx.memo(key, compute)and put the node in the key, such asplugin-ts:imports:${node.operationId}. - Remove the Vitest-backed test helpers:
@kubb/core/mocks,@kubb/kit/testing, andkubb/kit/testingare gone, and no package lists Vitest as a peer dependency. Copy the helpers you use from kubb-labs/plugins into your own test setup. (#4510)
v5.15.1
patch@kubb/ast
InputMeta.circularNames and InputMeta.enumNames are now ReadonlySet<string> instead of arrays, so a generator calls ctx.meta.enumNames.has(name) without building its own set. Code that reads them as arrays needs .has instead of .includes, .size instead of .length, and [...meta.enumNames] for array methods. new Set(meta.enumNames) keeps working. This includes banner and footer functions, whose BannerMeta extends InputMeta. Kubb Studio still stores and sends both fields as arrays. (#4506)v5.15.0
minor@kubb/cli
kubb studio permissions to change the permissions saved for a project. It shows the same list as kubb studio, with the saved answers checked, and keeps the pairing. Before, the only way to undo an answer was to edit credentials.json or pair again with kubb studio login. (#4489)kubb generate about 0.25 s faster on every run. The update check no longer delays the build: the notice prints at the end only when the registry answered in time. The telemetry request runs in the background with a 1 s cap. kubb generate no longer loads the code of the other commands, and source maps load only when KUBB_DEBUG is set. (#4500)@kubb/core
output.clean. Files written into the cleaned output are no longer read back first, and fsStorage moves the previous output aside and deletes it in the background while the new files are written. (#4499)@kubb/kit
this.memo(key, compute) to every resolver, one cache per plugin per build, and ctx.memo plus the memo() composable, one cache per build shared by every plugin. Register a key prefix and its value type in Kubb.MemoRegistry to type the value. Export camelCase and pascalCase from @kubb/kit and @kubb/core, so a plugin computes each name once per build. Cache Resolver.resolveName allocations, ast.refName, and the TypeScript parser's relative import paths, and dedent text nodes in one pass. Generated output is unchanged. A large spec generates about 10% faster. (#4501)macroSimplifyUnion on specs whose unions reference large components, with the same output. A union member that is a $ref is now compared by its pointer instead of by its whole resolved schema, so a spec such as Stripe's generates in about half the time. (#4491)@kubb/plugin-barrel
Add named service namespace exports alongside standalone operation functions with output.barrel.namespace.
- Enable nested barrels and export each immediate subdirectory under its PascalCase name.
- Forward service namespaces through an enabled root barrel.
- Keep standalone fetch functions available for React Query hooks and options.
pluginFetch({
output: { path: 'client', barrel: { type: 'named', namespace: true } },
group: { type: 'tag', name: ({ group }) => `${group}Service` },
})Import the generated service with import { PetService } from './gen/client' and call PetService.getPet(...). (#4487)
v5.14.6
patch@kubb/adapter-oas
$ref that Kubb cannot read inside an x- vendor extension as a KUBB_REF_NOT_FOUND warning instead of an error. Kubb never reads extensions, so such a ref cannot change the output, and a spec like Spotify's no longer fails generation over it. (#4479)v5.14.5
patch@kubb/core
$ref files in inline input and parsed objects against root, the way a file input already does. A $ref to a file or URL Kubb cannot read now reports KUBB_REF_NOT_FOUND at the key that holds it, instead of leaving the type as unknown. The new adapter.sources lists the files and URLs the last parse read, and generateModule returns them, so a watcher can rebuild when a $ref file changes. (#4478)resolveName's normalize return several names, so a declaration that emits more than one identifier takes a name only when all of them are free. A plugin naming an enum no longer has to allocate its value and its type alias in two passes. (#4475)v5.14.4
patch@kubb/core
Resolver.reserveNames and Resolver.resolveName to prevent duplicate exports. Keys can be strings or arrays. The driver reserves component names after applying macros and filters. (#4474)@kubb/kit
v5.14.3
patch@kubb/adapter-oas
required fields declared in oneOf and anyOf members without changing the referenced component schemas. (#4471)@kubb/kit
oneOf: [string, string, number] becomes string | number for every plugin. (#4468)v5.14.2
patch@kubb/adapter-oas
allOf around a $ref is no longer resolved to unknown as an alias cycle with itself. (#4464)encoding style outside the OpenAPI set is no longer carried onto the request body content. (#4465)style outside the OpenAPI set is no longer carried onto the parameter. (#4466)v5.14.1
patch@kubb/adapter-oas
allOf member that only holds annotations (description, title, example) or if/then/else no longer becomes unknown. The annotations move onto the parent schema. The conditional keywords are dropped, not enforced. (#4456)allOf member that only lists required next to a $ref or properties no longer becomes unknown. The listed properties now keep their schema and stay required in the generated types, Zod schemas and fakers. (#4454)integer, number or boolean discriminator produces type_id: 1 or z.literal(1) instead of the string '1', so the union members no longer collapse to never and valid payloads pass validation. (#4458)$ref to a path outside components.schemas, such as #/paths/~1foo/get/responses/200/content/application~1json/schema/items, is now inlined. Before, it was named after its last segment and imported from a file that was never generated, so the output failed to compile. (#4459)allOf and declares its own discriminator for grandchildren no longer collapses to never. The parent's discriminator property now accepts the keys of every level, the child keeps the parent's type, and a grandchild narrows to its own mapping key. (#4460)const next to a $ref (OpenAPI 3.1) is no longer dropped. The property narrows to the literal, so a z.discriminatedUnion over members that pin the discriminator to different values no longer throws Duplicate discriminator value. (#4455)$ref twice inside a response schema no longer fails with KUBB_REF_NOT_FOUND. The bundler's second reference pointed at the old responses/200/schema location, which the upgrade to 3.x moves, so such references are now inlined before the upgrade. (#4457)$ref each other no longer print a self-referencing type such as export type Baz = Baz. A chain of pure aliases that leads back to itself now resolves to unknown. (#4461)swagger: 2.0 (parsed by YAML as the number 2) is now upgraded like swagger: '2.0', so its definitions are no longer dropped. (#4456)@kubb/ast
encoding record with the contentType, style, explode and allowReserved of every property that sets one in the spec. (#4463)$ref to a component whose name contains / or ~ now resolves to the same name as the component. The last segment of the pointer is decoded the way the resolver does it: percent-escapes first, then ~1 and ~0 (RFC 6901). Before, #/components/schemas/a~1b~0c imported A1B0C from a file that was never emitted, because the component itself is a/b~c and is emitted as ABc. (#4462)@kubb/cli
kubb update <id> now exits with code 1 when it skips a named extension because it needs a newer Kubb or Node.js. Kubb Studio no longer reports such an update as a success. (#4440)@kubb/core
$ref each other now reports a KUBB_ALIAS_CYCLE warning, in addition to resolving to unknown. (#4461)v5.14.0
minor@kubb/ast
Add inline sources. Files that import a source marked inline: { expression } get the expression in place of the name, and a file whose sources are all inline is not written. The parser for the file's extension supplies the language rules through the new inline member, which parserTs implements. (#4438)
<File.Source name="AddPetStatus200" isTypeOnly isExportable inline={{ expression: 'Pet' }}>
{`export type AddPetStatus200 = Pet`}
</File.Source>v5.13.1
patch@kubb/ast
Add direct child and schema traversal helpers, early schema lookup, and ref resolution to the AST package.
- Expose
forEachChild,forEachSchema,findSchema, andresolveRef. - Keep OpenAPI
propertyNamesschemas on typed object nodes. (#4437)
@kubb/cli
kubb add writes parsers into kubb.config.ts, and kubb update <id> exits with code 1 when the id is not installed. (#4431)kubb add and kubb init edit kubb.config.ts without @kubb/studio. The config editor uses yuku-parser instead of magicast.
Breaking: applyConfigEdits and writeConfigEdits are now editConfig and editConfigFile, and the set and remove operations are now set-option and remove-option. (#4433)
kubb remove ignores plugins Studio switched off, and kubb add stops before installing a parser when there is no config. (#4435)@kubb/core
@kubb/studio
v5.13.0
minor@kubb/adapter-oas
servers[].url values (@readme/openapi-parser 10). (#4426)@kubb/ast
pointer prop on File.Source. (#4424)@kubb/core
@kubb/mcp
@kubb/parser-ts
typescript installed. (#4416)@kubb/studio
v5.12.8
patch@kubb/ast
content instead of schema get their type from the media type's schema instead of unknown. ParameterNode.contentType holds that media type, so clients can JSON-encode the value. (#4413)v5.12.7
patch@kubb/adapter-oas
$defs and definitions blocks and resolve references to them. (#4401)iri, iri-reference, base64url, jwt, ulid, iban and duration no longer raise KUBB_UNSUPPORTED_FORMAT. Generated output is unchanged. (#4412)uri-reference, hostname and idn-hostname map to a string instead of a URL, so plugin-zod prints z.string() and relative references pass validation. (#4410)unplugin-kubb
root defaults to the folder of kubb.config.ts instead of process.cwd(). A *.openapi.yaml import only uses a config whose input is that spec, and fails with No Kubb config applies to <spec> when none fits. (#4409)v5.12.6
patchunplugin-kubb
*.openapi.yaml spec to get the output of every plugin in your config as one module. kubb() without a config option loads kubb.config.ts. (#4402)v5.12.5
patch@kubb/adapter-oas
js-yaml first, which loads a 1.4 MB YAML spec in about 105 ms instead of 470 ms. A JSON spec with a duplicate key now fails with KUBB_INVALID_DOCUMENT. (#4398)locate compares the spec text once instead of on every call, so many pointer lookups on one spec run about 9× faster. (#4394)@kubb/ast
output.mode: 'file' merge generator results once, which cuts a 1.9 MB spec from 3.3 s to 2.3 s. Named imports can come out in a different order. (#4396)v5.12.4
patch@kubb/studio
output options barrel, format, lint, clean and defaultBanner through the new set-output and remove-output config edits. (#4390)v5.12.3
patch@kubb/core
checkoutGitInput takes an authorization option and GenerateInput gains gitAuth, so Studio can fetch a private repository without a credential in the input URL. (#4384)@kubb/studio
--allow-save-input permission. (#4385)v5.12.2
patch@kubb/studio
--allow-install and --allow-update permissions. kubb add exits with code 1 when it cannot write the plugin into kubb.config.ts. (#4382)v5.12.1
patch@kubb/core
checkoutGitInput takes a publicOnly option that accepts https repositories on public addresses only. Core also exports isPublicAddress. (#4381)@kubb/studio
git+<repo>#<ref>:<path> file. (#4379)v5.12.0
minor@kubb/cli
kubb generate --watch follows a local input file only and no longer polls a URL input. A URL or git input is generated once, with a warning, so rerun Kubb after the remote spec changes. (#4375)@kubb/core
input reads a spec from a git repository with git+<repo>#<ref>:<path>. Private repositories use your git credentials and kubb validate accepts the same form. (#4375)@kubb/parser-ts
@typescript/typescript6, so print keeps working next to TypeScript 7. Custom printers import ts from that package too. (#4370)kubb
v5.11.6
patch@kubb/studio
defineConfig([...]) array to Studio and generate from the entry Studio names. loadConfig on connectAgent is now loadConfigs. (#4368)v5.11.5
patch@kubb/cli
kubb generate, previews for kubb add, kubb update and kubb init, and one-line job logs for kubb studio. kubb update --dry-run replaces --check. (#4355)@kubb/core
kubb.config.ts. (#4364)Report gains filesUnchanged. Diagnostics carry a file:line:column position. (#4355)@kubb/studio
requestedBy on startGeneration and saveConfig and name that Studio user in the agent log. (#4362)v5.11.4
patch@kubb/studio
{ jobId, paths }; jobType, source and FileSource are removed. Upgrade Studio and its agents together. (#4360)v5.11.3
patch@kubb/studio
v5.11.2
patch@kubb/studio
KUBB_PATH_TRAVERSAL. (#4353)v5.11.1
patch@kubb/cli
kubb generate with the Kubb mascot in fixed 256-color codes. CI, AI agents and narrow terminals keep the plain Kubb CLI vX line. (#4350)v5.11.0
minor@kubb/core
include, exclude and override accept { type: 'extension', key: 'x-…', value? }. (#4316)v5.10.4
patchAll packages
unplugin-kubb, the bundler integrations in kubb and the test helpers ship as ES modules only; from CommonJS read the plugin from .default. (#4343)v5.10.3
patchAll packages
require consumers get correct types under moduleResolution: node16 and nodenext. vitest is an optional peer of @kubb/core, @kubb/kit and kubb. (#4337)@kubb/studio
readDiff pages include stats and end on hunk boundaries. (#4336)v5.10.2
patch@kubb/adapter-oas
@kubb/core as a dependency, so the published types resolve under pnpm and other strict installers. (#4332)@kubb/core
plugins now fails. (#4329)@kubb/studio
output.path and keep banner as it is. (#4330)readDiff to the agent, so Studio shows the diff of a large generated file page by page. @kubb/studio/protocol exports AgentMessage, FileSource and AgentPermission const enums instead of loose constants. (#4333)v5.10.1
patch@kubb/cli
kubb.tty and, for kubb mcp, the name of the connected MCP client. startServer in @kubb/mcp returns the server. (#4325)v5.10.0
minor@kubb/adapter-oas
InputMeta.servers. InputServer gains an optional variables field with the source URL template's variables, copied as-is next to the resolved url, so a consumer can tell a templated server from a literal one. It is absent when the server declares no variables. (#4315)OperationNode and InputMeta gain an optional extensions bag with every x-* key copied as-is, set only when the source has one. The OAS adapter fills it from the operation object and the document root, so plugins can read keys like x-org-ignore without walking the raw document. Path-level extensions are not copied. (#4311)@kubb/cli
KUBB_AGENT_TOKEN from kubb studio. The CLI now connects only through a paired machine, and in CI you run kubb studio snapshot with KUBB_TOKEN instead. (#4317)@kubb/studio
allowReadAst permission (--allow-read-ast) for reading the parsed spec. allowRead now covers only generated files, so projects that granted allowRead before are asked once more about the spec. (#4320)v5.9.6
patch@kubb/adapter-oas
@kubb/ast
not keyword as a not schema node instead of dropping it. TypeScript output does not change. (#4308)Heading, Paragraph, List, Callout and Frontmatter in a markdown file instead of only the first of each kind. (#4302)v5.9.5
patch@kubb/studio
--allow-read return the Kubb AST through readInput, so Kubb Studio can describe your API. InputMeta gains servers and securitySchemes. (#4300)v5.9.4
patch@kubb/adapter-oas
datetime schema nodes always set both offset and local, and circular schemas are found through the shared @kubb/ast graph. (#4293)@kubb/ast
OutputNode, createOutput, ast.factory.update, InferSchemaNode and the @kubb/ast/types subpath. Ipv4SchemaNode and Ipv6SchemaNode become 'ipv4' | 'ipv6' scalars. Add ast.refName(ref). (#4293)@kubb/cli
unconfig dependency. Config discovery is unchanged. (#4293)@kubb/core
createAdapter, defineParser and definePlugin accept only the definition object; use defineExtension. Remove Storage.existsItem, FileManagerHooks, FileManager#hooks and applyConfigDefaults. (#4293)@kubb/kit
Url.toGroupedTemplateString uses dot access for path parameters named like reserved words. (#4293)@kubb/mcp
generate finds the config the way kubb generate does, and init hands plugin installs to kubb add. (#4293)@kubb/parser-md
@kubb/renderer-jsx
@kubb/renderer-jsx/types subpath; import types from the root. Component props are the matching @kubb/ast node fields. (#4293)unplugin-kubb
kubb generate summary after a build and apply the defineConfig defaults. Remove the unplugin-kubb/types and unplugin-kubb/unpluginFactory subpaths and the BarrelType re-export. (#4293)v5.9.3
patch@kubb/cli
kubb add without an id asks which extension to add from the registry, and kubb update asks which updates to install. (#4291)v5.9.2
patch@kubb/core
readInstalledPackages throwing when root is a relative path, which made CI snapshots fail. (#4288)v5.9.1
patch@kubb/adapter-oas
@kubb/ast
defineNode, NodeDef, nodeDefs and the *Def objects. StatusCode accepts any three-digit status string. (#4278)@kubb/cli
kubb init takes its plugins from the Kubb registry and stops before installing when a plugin's dependencies are missing. (#4275)@kubb/core
KUBB_PLUGIN_FAILED, KUBB_ADAPTER_FAILED or KUBB_PARSER_FAILED with a link to the extension's issue tracker from meta.issues. (#4279)PluginFactoryOptions to PluginType. Remove KubbDriver.dispatch and KubbDriver.hasHookGenerators. (#4278)@kubb/kit
@kubb/studio
v5.9.0
minor@kubb/cli
kubb add installs a reviewed plugin, adapter, or parser at the version the registry pins, kubb update moves installed extensions to that version, and kubb list shows what is installed. Registry support landed across 5.8.1 to 5.8.4.unplugin-kubb
output.clean, and Astro no longer generates twice. (#4266)nuxt build. The module now needs @nuxt/kit 3.14 or later. (#4266)v5.8.4
patch@kubb/core
kubb add and kubb update install it as github:<owner>/<repo>#<commit>. (#4264)v5.8.3
patch@kubb/core
maintainers and dependencies to kubb-extension.json. Each package now ships its overview, options page, and guides in a docs/ folder. (#4260)v5.8.2
patch@kubb/core
Add defineExtension to define a plugin, an adapter, or a parser. definePlugin, defineParser, and createAdapter still work but are deprecated. (#4258)
export const pluginZod = defineExtension<PluginZod>({
kind: 'plugin',
meta: { name: 'plugin-zod' },
setup(options, kubb) {
kubb.addGenerator(zodGenerator)
return options
},
})v5.8.1
patch@kubb/cli
kubb add, kubb update, and kubb list to install and update extensions from the Kubb registry. (#4253)@kubb/core
kubb-extension.json manifest. Studio runs installed third-party plugins that ship one. (#4253)createAdapter takes an object with meta, setup, and build, like definePlugin. defineParser takes build instead of setup. (#4249)schema from definePlugin and @kubb/kit/options, both added in 5.8.0. Type plugin options with TypeScript and apply their defaults in setup. (#4252)@kubb/plugin-barrel
barrel: false plugin that writes to the output root no longer removes the other plugins' barrels. (#4254)output.path no longer takes over the other plugins' barrels. (#4255)v5.8.0
minor@kubb/core
setResolver() work in plugins that a CommonJS config loads, instead of failing with KUBB_NO_CONTEXT. (#4246)v5.7.0
minor@kubb/core
definePlugin and defineParser accept an object with meta, dependencies, and setup(options, kubb). The factory form is deprecated. A mismatch in meta.compatibility or dependencies fails the run with KUBB_INCOMPATIBLE_EXTENSION, KUBB_MISSING_DEPENDENCY, or KUBB_INCOMPATIBLE_DEPENDENCY. (#4241)kubb/kit, such as addGenerator(), setResolver(), and useOptions(), so a plugin can call setup helpers without passing ctx around. (#4240)v5.6.3
patch@kubb/core
ctx.requirePlugin(name) and assertPluginOption() for plugin setup checks, and createMockedSetupContext() in @kubb/kit/testing for unit tests. (#4238)@kubb/mcp
@kubb/studio
kubb studio agent's config edits and sandbox input, and reload JavaScript configs on every generation. (#4233)v5.6.2
patch@kubb/studio
v5.6.1
patch@kubb/cli
@kubb/core
@kubb/studio
v5.6.0
minor@kubb/adapter-oas
@kubb/ast
Visit schemas inside a tuple's rest and inside patternProperties, so refs there are collected, transformed by macros, and imported in generated files.
@kubb/cli
@kubb/core
Run output.format, output.lint and output.postGenerate from Kubb.generate() by default, so every host gets the same passes.
- Adds
runOutputPassesandrunHook, the one implementation of the format, lint and post-generate steps.runHookspawns the command withnode:child_process, in the configroot, and emitskubb:hook:start,kubb:hook:lineandkubb:hook:enditself. generate({ processOutput })still replaces the passes when a host needs to; its context now also carrieshooksandsignal.unplugin-kubbandkubb mcpstart honoringoutput.format,output.lintandoutput.postGenerate, which they ignored before. (#4196,50617dd)
Run output.format, output.lint and output.postGenerate commands through tinyexec, which resolves Windows command shims and the project's node_modules/.bin.
Formatter and linter detection for 'auto' also finds a tool installed only in node_modules/.bin under config.root, the folder the tool then runs from. (#4218, 0fb79d5)
@kubb/kit
@kubb/mcp
@kubb/parser-ts
@kubb/plugin-barrel
@kubb/renderer-jsx
Set or generator passed as children is now a type error instead of silently rendering nothing. The element type also carries its $typeof brand, and the renderer only walks elements the Kubb JSX runtime created. (#4192, 068f4a9)@kubb/studio
unplugin-kubb
v5.5.6
patch@kubb/adapter-oas
@kubb/cli
v5.5.5
patch@kubb/adapter-oas
Fix a batch of small bugs:
@kubb/adapter-oas: resolve local$refpointers per RFC 6901, so#/paths/~1pets/getand keys with~or an encoded/resolve. On Windows, an absolute input such asC:\specs\api.yamlno longer counts as a URL, so a missing file now reportsKUBB_INPUT_NOT_FOUNDinstead of failing later.@kubb/mcp: reloadkubb.config.tson every tool call. The server cached the first load, so edits only showed up after a restart.@kubb/cli:CI=falseandCI=0no longer count as running in CI, andkubb initdetects Bun frombun.lockas well asbun.lockb.@kubb/studio: a failing format, lint orpostGeneratecommand reports onekubb:errorinstead of two.@kubb/renderer-jsx: fix themetaprop type on<kubb-file>, which referencedFileNodewithout importing it. (#4175,11cd291)
v5.5.4
patch@kubb/adapter-oas
KUBB_INVALID_SPEC warnings during kubb generate. The adapter validated the spec by default but discarded the result, so an invalid spec generated silently. Each problem is now listed and generation continues. Set validate: false on the adapter to skip the check, which on a large spec saves about 20% of the run. (#4172, 75b2c47)@kubb/cli
@kubb/parser-ts
typescript with require instead of import. When ESM code imports a CommonJS package, Node keeps a second copy of its source, and for TypeScript that copy is about 9 MB. With plugin-ts and plugin-zod loaded, heap drops by about 9 MB and RSS by about 25 MB, which matters most for the long-running kubb studio agent. (#4169, 34b95e8)@kubb/studio
kubb studio agent uses while idle. tsdown and magicast now load only when Studio packs a snapshot or reads or edits kubb.config.ts. The agent also drops its reference to a finished generation's output, which held every generated file in memory when allowWrite was off. (#4169, c705ba7)v5.5.3
patch@kubb/cli
acff588)v5.5.2
patch@kubb/studio
v5.5.1
patch@kubb/core
v5.5.0
minor@kubb/adapter-oas
oneOf/anyOf const unions as named enums when their members have distinct, non-empty titles and distinct string or number values. Member titles and descriptions are retained alongside their original wire values, without an additional adapter option. Recognition runs after Kubb's existing upgrade to OpenAPI 3.1. Ordinary enum unions and incomplete, ambiguous or additionally constrained unions retain their existing representation. Recognition can change generated enum exports, such as a literal-union Status type becoming an enum-backed StatusKey with @kubb/plugin-ts and enum.type: 'asConst'. (#4155, 0d3468f)v5.4.5
patch@kubb/adapter-oas
format such as double, float or int32 keep their minimum, maximum, exclusiveMinimum, exclusiveMaximum and multipleOf constraints, so { type: 'number', format: 'double', minimum: -90, maximum: 90 } generates z.number().min(-90).max(90) again. int64 and uint64 now keep multipleOf as well. (#4149, 8ff2b1e)@kubb/parser-ts
v5.4.4
patch@kubb/cli
v5.4.3
patch@kubb/studio
v5.4.2
patch@kubb/cli
kubb
v5.4.1
patch@kubb/cli
Add kubb studio start and stop for a background connection per project. status reports its connection state and log path, and logout stops it before removing credentials. Rejected tokens stop the worker until you log in again.
Use one shared connection loop for the CLI and Docker agent. Abort pending registration on shutdown and wait for canceled generation cleanup before reconnecting. (#4128, 5d9151c)
v5.4.0
minor@kubb/core
v5.3.19
patch@kubb/studio
kubb studio snapshot saying "No snapshot of main to compare with" even when a CI agent for the base branch already exists and simply has no snapshot of this package yet, such as a package newly added in the pull request. branchChanges now carries baseFound, and the summary line tells the two cases apart: "No snapshot of main to compare with" (no agent has run there) versus "No snapshot of main for this package yet" (the agent exists, this package is new to it). (#4123, 3561e19)v5.3.18
patch@kubb/studio
kubb studio snapshot runs its snapshot job on the agent process it connected, so two overlapping pipelines of the same CI agent never build each other's checkout.
v5.3.17
patch@kubb/studio
v5.3.16
patch@kubb/studio
v5.3.15
patch@kubb/core
v5.3.14
patch@kubb/adapter-oas
application/pdf, image/png, ...), not just application/octet-stream. A newer @scalar/openapi-upgrader release started emptying format: 'binary' schemas for every media type on the OAS 3.1 upgrade, not just application/octet-stream, so those bodies fell back to emptySchemaType instead of resolving to a blob. (#4094, cfcb497)@kubb/ast
v5.3.13
patch@kubb/studio
node_modules/.cache/kubb, so they survive a restart, and sandboxes keep them in memory. KUBB_AGENT_MAX_GENERATIONS (default 8), KUBB_AGENT_MAX_GENERATIONS_MB (default 100) and KUBB_AGENT_MAX_SNAPSHOT_MB (default 50) set the limits. Breaking for the Studio connection: readFiles now takes a jobId and a source, and GenerateResult.changes is replaced by hashes and disk.hashes. @kubb/core now exports cacheStorage. (#4090, 7b517b8)v5.3.12
patch@kubb/studio
Report which files a Studio run added, changed, or removed, and serve the previous run's contents so Studio can show a diff.
GenerateResult.changesmaps each path that differs from the session's previous successful run toadded,changed, orremoved. Unchanged files are left out, and the field is absent on a session's first run.readFilestakesrevision: 'previous'to read the run before the latest one, including files the latest run removed. The previous run is read into memory before the next run starts, so a session that writes to disk can still be diffed after its files are overwritten.- A failed run leaves the last successful run as the one to compare against.
FileChangeis exported from@kubb/studio. (#4086,300186d)
v5.3.11
patch@kubb/adapter-oas
v5.3.10
patch@kubb/cli
v5.3.9
patch@kubb/adapter-oas
@kubb/cli
kubb
v5.3.8
patch@kubb/studio
Carry an agent's organization slug through pairing and connecting, so a host can log and trace it alongside the agent's own slug.
PairingResult.agent and the studio:connected hook context gain an optional
organizationSlug, absent for a sandbox or global agent, which has none. studio:connected also
gains agentSlug, refreshed on every connect so a rename in Studio shows up without a re-pair.
Both fields are additive: a host built against an older type just ignores them. (#4066, eb5fa50)
v5.3.7
patch@kubb/studio
v5.3.6
patch@kubb/studio
Fix generation and heartbeat lifecycle bugs left over from the Cap'n Web RPC cutover:
- A dropped Studio connection now cancels the in-flight generation instead of letting it finish unwatched.
- Two
startGenerationcalls arriving in the same tick can no longer both start a run. - A heartbeat ping that never settles (a half-open socket) now closes the session instead of hanging it indefinitely.
- Removed an unreachable error path left over from the old JSON transport. (#4061,
f880342)
v5.3.5
patch@kubb/studio
Stop holding a whole generation's output in memory for the life of a Studio session.
studio:files and studio:snapshot used to read every generated file into one Record<string, string> the moment a run finished, and kept that map alive until the next generation. A run
producing gigabytes of source meant the agent process held gigabytes in RAM, whether or not anyone
ever opened a file or took a snapshot.
The agent now keeps the live Storage a run wrote through, plus the list of paths it produced, and
reads a file's content back from Storage only when studio:files or studio:snapshot actually
asks for it. A path outside that list is refused before it reaches storage, so this changes nothing
about what a session can read, only when the read happens. (#4059, 351e3c9)
Stop streaming generated source over the agent WebSocket by default. Reading it now needs
--allow-read (or KUBB_AGENT_ALLOW_READ=true), matching the other four Studio permissions.
Every kubb studio session used to send the full text of every generated file on
kubb:generation:end, whether or not anyone in the browser opened one. A spec producing hundreds
of files could put megabytes of source on the wire per run, and nothing gated it: allowWrite,
allowConfigEdit, allowInput, and allowExec all cover what Studio may do to a project, but
reading generated output back was never one of the four.
kubb:generation:end now carries nothing. Everything it used to carry moved somewhere better:
- The list of generated files is on
kubb:build:end, which already carried every path and fires earlier in a run. Its paths are now relative to the agent's root, matching every other path on the wire, where they used to be absolute. - The file count is on
kubb:generation:summary, which already had it and was always the accurate number (kubb:generation:end's old count went to 0 for a CI connection). - File contents are fetched on demand with a new
studio:filescommand, which the browser sends when someone opens a file. The agent replies withagent:files, refusing unlessallowReadwas granted. - Peer dependency metadata, previously sent on every generation and round-tripped straight back
into
studio:snapshot, now travels with theagent:snapshotreply instead, since the CI snapshot flow is its only consumer.studio:snapshottakesbundledDependenciesin place ofpeerDependencies.
--allow-read is off by default everywhere, like every other permission. A sandbox or global
agent is always granted it, since its output is the only thing it has:
kubb studio --allow-read # show generated files in the browserAn older Studio instance talking to this version of the agent (or the reverse) can fail: a snapshot
build errors because bundledDependencies and peerDependencies no longer line up between the two
ends, and a plain session shows an empty editor with no file contents. Point --url at a Studio
build that matches this version.
The in-process kubb:generation:end hook (kubb.hooks.hook('kubb:generation:end', ...), or a
plugin's own listener) is unaffected. It still carries config, storage, diagnostics,
status, hrStart, and filesCreated, exactly as before. Only the payload this event sends over
the Studio WebSocket changed. (#4059, 351e3c9)
v5.3.4
patch@kubb/studio
Back off while polling a Studio job, so a long snapshot stops exhausting the API key rate limit.
waitForJob polled GET /api/jobs/{id} every second, starting the instant the job was queued. The
CLI's kubb studio snapshot waits up to 10 minutes by default, which is up to 600 requests against
a budget of 100 per window. The window only resets after a whole window with no request, so a
one-second poll could never escape the limit once it hit it, and every later call failed until the
run gave up. The budget belongs to the organization key, so concurrent CI runs share it.
The first poll now waits two seconds, since a job runs a generation and packs a tarball before it
can possibly finish. From there the interval doubles to a 30 second ceiling, bringing a 10 minute
wait down from 600 requests to 22. A 429 pushes the next poll out by the tryAgainIn Studio
returns and never pulls it back in, and retry: false stops ofetch retrying a 429 with no delay. (#4057, 52637b6)
v5.3.3
patch@kubb/studio
The agent runtime now packs snapshot tarballs itself. A new studio:snapshot command builds the
npm-installable tarball from the session's most recent generation and uploads it to a Studio
endpoint, instead of Studio building the tarball on its own server. A snapshot request with no
prior generation is refused.
A CI connection also keeps generated files off every kubb:generation:end reply, since it has no
UI to render them in. kubb studio snapshot and the Studio UI's "Create snapshot" button keep
working as before, now backed by this protocol message. (#4052, 19e9c2c)
The background reconnect loop's "Retrying connection" and "Reconnect attempt failed" lines, and
the teardown notice disconnect() prints on the way out, now go through console.error instead
of console.info/console.log, and only print when a host passes a logLevel above silent to
StudioSession. Previously they always printed unconditionally, which a CI runner that only
streams a child process's stderr live (such as kubb-labs/action) never surfaces, and which
contradicted installLogger's own "prints nothing when left out" default.
kubb studio and kubb studio snapshot now pass their --log-level flag through, so these lines
respect the same flag as the rest of the command's output. (#4052, 19e9c2c)
v5.3.2
patch@kubb/cli
CLI flags are now kebab-case, matching the convention used by most command-line tools.
kubb generate --log-levelandkubb generate --dry-runreplace--logLeveland--dryRun.kubb studio --allow-write,--allow-config-edit,--allow-input, and--allow-execreplace--allowWrite,--allowConfigEdit,--allowInput, and--allowExec.kubb init --dry-runreplaces--dryRun.
To upgrade, replace any camelCase flag in a script or CI job with its kebab-case name. The CLI now rejects an unrecognized flag with an error instead of silently ignoring it.
# Before
kubb studio --allowWrite --allowExec
# After
kubb studio --allow-write --allow-exec@kubb/studio
Renamed the studio:ping heartbeat reply to studio:pong, matching the ping/pong pattern
agent:ping already implies (StudioPingMessage is now StudioPongMessage,
isStudioPingMessage is now isStudioPongMessage). This is a wire-protocol change: an agent
running an older @kubb/studio and a Studio running the new one won't recognize each other's
heartbeat reply. Update both sides together.
Also documented the full studio:/agent: message table in packages/studio/src/protocol/index.ts,
including why studio:generate has no dedicated agent:generate reply (its result rides the
agent:data/kubb:generation:end event stream instead, unlike studio:save/studio:snapshot,
which reply directly). (#4053, 76dd283)
v5.3.1
patch@kubb/core
v5.3.0
minor@kubb/core
v5.2.8
patch@kubb/cli
Add kubb studio snapshot to generate and publish a Kubb Studio snapshot from any CI, not only GitHub Actions.
- Registers or reuses a CI agent, connects it, queues a snapshot job, and polls until the tarball is ready.
- Reads the organization CI API key from
--tokenorKUBB_TOKEN. - Detects the calling CI (GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI) to reuse one agent per pull or merge request, or takes an explicit
--idon any other CI. - Prints a summary, or one JSON object with
--jsonfor a script to read. @kubb/studionow also exportscreateAgentandmachineTokenFrom, so a host can register a CI agent without hand-rolling the request.
KUBB_TOKEN=$KUBB_TOKEN kubb studio snapshot --jsonv5.2.7
patch@kubb/cli
af87dbc)@kubb/studio
v5.2.6
patch@kubb/studio
0a1e553)v5.2.5
patch@kubb/studio
Add a studio:ready acknowledgement so a host can tell "the socket is open" apart from "Studio has registered this connection and will dispatch jobs to it".
A connected socket announces itself with agent:connect but never waited for a reply, so a job could arrive at Studio moments before the agent was actually registered. StudioSession now waits up to 10 seconds for studio:ready after sending that handshake and fires a new studio:ready hook once it lands, warning instead of failing if an older Studio never sends one. kubb studio prints ✓ Ready to receive jobs once it does. (#4028, b93eb64)
v5.2.4
patch@kubb/studio
Report the package a plugin ships from, so plugin-ts reaches Studio as @kubb/plugin-ts while a third-party plugin keeps its own name.
The connect payload scoped every plugin name under @kubb/, which claimed a third-party plugin as one of Kubb's. It now follows the same rule the dependency check already used. (#4026, 628c98b)
v5.2.3
patch@kubb/cli
kubb generate --watch now works with URL inputs. A remote document emits no filesystem events, so watch mode polls the URL (every 2 seconds) and regenerates when the response body changes. Each poll request times out after 10 seconds, so a hung server never stalls the watcher. An unreachable server is reported once per outage and polling continues. After recovery, a rebuild only happens when the document actually changed, unless the server was already down at startup, in which case the first successful poll regenerates so the output catches up. Previously --watch was silently ignored for URL inputs and the CLI exited after a single build. (#4022, 5f4fd20)@kubb/studio
v5.2.2
patch@kubb/adapter-oas
oneOf/anyOf without a declared OpenAPI discriminator now infers one when a property
carries a distinct single literal value on every branch. UnionSchemaNode.discriminatorPropertyName
is set from that inference, so every printer that narrows on it (plugin-zod, plugin-faker)
picks it up without reimplementing the same scan. (#4019, c89f215)v5.2.1
patch@kubb/adapter-oas
@kubb/core
@kubb/studio
Trim @kubb/studio's public API to what the kubb studio CLI command and the Docker agent
actually use.
- Removed the unused hook context types
StudioCommandStartContext,StudioCommandEndContext,StudioConnectingContext,StudioDisconnectedContext,StudioErrorContext, andStudioWarnContextfrom the package's root export.StudioConnectedContextstays exported. Hook payloads forstudio:connecting,studio:command:start,studio:command:end,studio:disconnected,studio:warn, andstudio:errorstill type-check throughHookable<KubbHooks>['hook'], since the underlying types are still declared, just no longer importable by name. - Removed
ConnectionOutcomeandTokenRejectionfrom the root export. Both stay inferable fromrunConnection's return value andonTokenRejectedcallback.
Neither the CLI nor the Docker agent imports any of these by name, so this does not change their
behavior. A consumer that did import one of them by name gets the same type through inference at
the call site instead, such as runConnection's return value or a hooks.hook('studio:warn', ...)
callback's parameter. (#4012, 109abe8)
v5.2.0
minor@kubb/adapter-oas
@kubb/ast
@kubb/cli
@kubb/core
@kubb/studio
v5.1.0
minor@kubb/adapter-oas
Let dateType set date-time, date, and time independently, instead of one value driving all three
Pass an object to represent timestamps as a JS Date while keeping date-only and time-only fields as strings, since Date cannot round-trip those without inventing a timezone.
adapterOas({
dateType: {
dateTime: 'date',
date: 'string',
time: 'string',
},
})The scalar form (dateType: 'date') still applies one value to all three formats. (#3957, 9fca8e9)
v5.0.6
patch@kubb/cli
--dryRun to generate and init to preview a run without writing files, installing packages, formatting, linting, or running post-generate commands. When an AI coding agent runs the CLI, generate now uses the plain logger instead of the interactive one, and anonymous telemetry records the agent's name. (#3951, 9849de3)v5.0.5
patch@kubb/core
v5.0.4
patchunplugin-kubb
Move unplugin-kubb past its squatted npm version range.
Versions 5.0.1 through 5.0.30 were already published on npm from unplugin-kubb's
pre-monorepo history and depend on kubb v4, so the package's version was set directly to
5.0.31 to clear that range. This changeset picks up from that 5.0.31 baseline and puts
unplugin-kubb back through the normal release process, independent of kubb and @kubb/*. (#3940, b45071e)
v5.0.3
patch@kubb/adapter-oas
v5.0.2
patch@kubb/kit
Fix Url.toPath producing route masks that path-to-regexp (used by MSW/Express) rejects or misparses:
- A parameter name starting with a character outside
[A-Za-z0-9_](e.g.{$id}) now sanitizes to a safe capture name instead of keeping the disallowed character. - Distinct parameter names that normalize to the same identifier (e.g.
{group-id}and{group.id}) are now deduplicated with an incrementing suffix (groupId,groupId2) instead of producing two identically named captures. (#3922,56a072c)
v5.0.1
patch@kubb/adapter-oas
null came first. type: ["null", "string"] generated null instead of string | null, while type: ["string", "null"] generated the right type, so the output depended on the order the types happened to be written in. The normalized type now takes the first non-null entry, and type: ["null"] stays a null schema. (#3912, 331558e)@kubb/cli
@kubb/kit
Url.toPath producing an invalid Express-style route for a hyphenated path parameter (e.g. {point-id} became :point-id). path-to-regexp treats a hyphen as ending the parameter name, so the generated MSW handler matched :point followed by a literal -id and rejected valid values. Url.toPath now camelCases the parameter name the same way Url.toTemplateString already does, so {point-id} becomes :pointId. (#3895, bf9bdc8)v5.0.0
majorKubb v5 rebuilds code generation around adapters, a universal AST, parsers, and storage, and generates code up to 5.4x faster than v4. Config gets shorter, generated client calls change shape, and plugins move to their own repo (kubb-labs/plugins).
Read the release blog post for the highlights, and the migration guide for the full, per-package breaking-change list and upgrade steps.
For prior releases, see GitHub Releases.
