diff --git a/blog/kubb-studio.md b/blog/kubb-studio.md new file mode 100644 index 00000000..5bd2fe57 --- /dev/null +++ b/blog/kubb-studio.md @@ -0,0 +1,66 @@ +--- +layout: doc +title: Introducing Kubb Studio +description: Kubb Studio is a browser front end for a Kubb project. You change plugin options and trigger generation from a tab, while Kubb runs on your own machine and your spec stays on disk. +outline: deep +image: /blog/kubb-studio/cover.svg +date: 2026-09-04 +--- + +[← Blog](/blog) + +Published: 2026-09-04 + +![Introducing Kubb Studio](/blog/kubb-studio/cover.svg) + +# Introducing Kubb Studio + +Tuning a Kubb config is a slow loop. You change one plugin option, run `kubb generate`, open the output folder, decide it was wrong, and start over. + +[Kubb Studio](https://kubb.studio) puts that loop in a browser tab. You pick plugin options in a form, hit generate, and watch files appear as they are written. What you do not do is upload anything. + +> [!WARNING] +> Studio is under active development. Expect breaking changes while it settles. + +## Your code never leaves your machine + +To generate from your spec, a hosted generator needs your spec. For a public Petstore that is fine. For the internal API that describes your billing system, it usually is not. + +Studio splits the two halves. The browser holds the UI, your machine holds the code. When you click generate, Studio sends a command over a WebSocket, Kubb runs locally against the files already on disk, and progress and output stream back to the tab. Nothing is uploaded, so you get the plugin versions already installed in your project, not whatever a server happens to have. + +## One command to connect + +The runtime ships with the CLI, so there is nothing extra to install: + +```shell +kubb studio +``` + +The first run asks you to approve this machine in Studio. Every later `kubb studio` connects straight away. + +## Read-only until you say otherwise + +A fresh session can do almost nothing: generation runs in memory and streams to the browser, and not a single file on disk changes. Four flags open that up one at a time: + +| Permission | What it grants | +| -------------------- | ----------------------------------------------------------------------------- | +| `--allowWrite` | Generated files are written to disk instead of only streaming to Studio. | +| `--allowConfigEdit` | Studio may change plugin options in your `kubb.config.ts`. | +| `--allowInput` | A spec sent by Studio replaces the one on disk for that generation. | +| `--allowExec` | The formatter, the linter, and `output.postGenerate` run as child processes. | + +The CLI asks about each one on the first connect to a project and remembers your answer. Nothing is ever asked in CI or without a TTY: an unattended run stays at whatever access it was explicitly given. + +## Editing config from the browser + +With `--allowConfigEdit`, the options you change in Studio are written back to your `kubb.config.ts` as an AST patch, not a regeneration, so it touches only the fields you changed and leaves the rest alone. Try `group.type: 'tag'`, look at the resulting file tree, switch back, all without leaving the tab. + +## Beyond your laptop + +`kubb studio` also runs from CI or a long-lived server, and the `kubblabs/kubb-agent` Docker image runs the same runtime for a team that wants one shared agent. See the [guide](/docs/5.x/guide/integrations/studio) for how. + +## Try it + +Studio is live at [kubb.studio](https://kubb.studio). The [guide](/docs/5.x/guide/integrations/studio) walks through connecting a project, and the [`kubb studio` reference](/docs/5.x/reference/commands/studio) lists every action and flag. + +Feedback goes to [GitHub](https://github.com/kubb-labs/kubb/issues) or [Discord](https://discord.gg/shfBFeczrm). The permission model in particular is the part we would most like to hear about before it hardens. diff --git a/docs/5.x/guide/integrations/index.md b/docs/5.x/guide/integrations/index.md index 61047db0..aa4aa50a 100644 --- a/docs/5.x/guide/integrations/index.md +++ b/docs/5.x/guide/integrations/index.md @@ -1,12 +1,16 @@ --- layout: doc title: Integrations -description: Run Kubb as part of your bundler with kubb's build integrations. Supported targets include Vite, Rollup, Rolldown, webpack, Rspack, esbuild, Farm, Nuxt and Astro. +description: Run Kubb from somewhere other than the CLI. Generate inside your bundler with Vite, Rollup, Rolldown, webpack, Rspack, esbuild, Farm, Nuxt or Astro, or from the browser with Kubb Studio. outline: [2, 3] --- # Integrations +Kubb runs from the CLI, and it also runs from the places you already work. A bundler integration generates during your build, and [Kubb Studio](./studio) generates from a browser tab while Kubb runs on your machine. + +## Bundlers + `kubb`'s bundler entrypoints run code generation inside your build. You skip the separate `kubb generate` step. Pass the same config you write in `kubb.config.ts`, and Kubb runs it as part of your build instead. Each entrypoint is powered by [`unplugin-kubb`](https://www.npmjs.com/package/unplugin-kubb) under the hood, re-exported from `kubb` so you only install one package. > [!NOTE] @@ -75,3 +79,9 @@ export default defineViteConfig({ plugins: [kubb({ config })], }) ``` + +## Kubb Studio + +[Kubb Studio](./studio) is the other way in, and it works differently from the entrypoints above. Rather than generating during a build, you open a session with `kubb studio` and drive generation from a browser tab. Kubb still runs on your machine against the files on disk, so your spec is never uploaded. + +Reach for it when you want to change plugin options and see the result straight away, and for a bundler entrypoint when generation should happen as part of your build. diff --git a/docs/5.x/guide/integrations/studio.md b/docs/5.x/guide/integrations/studio.md new file mode 100644 index 00000000..43c3a951 --- /dev/null +++ b/docs/5.x/guide/integrations/studio.md @@ -0,0 +1,65 @@ +--- +layout: doc +title: Kubb Studio +description: Connect a Kubb project to Kubb Studio and generate from the browser while Kubb runs on your own machine. Covers connecting, permissions, headless runs, and self-hosted instances. +outline: [2, 3] +--- + +# Kubb Studio + +[Kubb Studio](https://kubb.studio) is a browser front end for a Kubb project. You edit plugin options, trigger a generation, and watch the output appear, while the generation itself runs on your machine against the files already on disk. + +That split is the point. Studio sends a command over a WebSocket, your machine runs Kubb, and progress events and generated files stream back to the browser. Your spec and your source never leave your infrastructure. + +> [!WARNING] +> This feature is under active development. Use it with caution and expect breaking changes. + +> [!NOTE] +> Studio is not a [bundler integration](/docs/5.x/guide/integrations/) you add to a build. It is a session you open from the CLI and close when you are done. + +## Connect a project + +The Studio runtime ships with the CLI, so a project that already has `kubb` installed needs nothing else. Run this from the project root, next to your `kubb.config.ts`. + +```shell [Terminal] +kubb studio +``` + +The first run opens the approval page in Studio and waits for you to approve this machine. Later runs connect straight away. Once the session is open, the project shows up in Studio and stays there until you stop the command. Check what a machine is connected as with `kubb studio status`, and disconnect it with `kubb studio logout`. + +## Choose what Studio may do + +A session is read-only by default. Generated files stream to the browser and nothing on disk changes, which makes the first connect safe to try on a real project. + +Four permissions widen that, and the CLI asks about each one on the first connect to a project, then remembers your answer. + +| Permission | What it grants | +| -------------------- | ----------------------------------------------------------------------------- | +| `--allowWrite` | Generated files are written to disk instead of only streaming to Studio. | +| `--allowConfigEdit` | Studio may change plugin options in your `kubb.config.ts`. | +| `--allowInput` | A spec sent by Studio replaces the one on disk for that generation. | +| `--allowExec` | The formatter, the linter, and `output.postGenerate` run as child processes. | + +```shell [Terminal] +kubb studio --allowWrite --allowExec +``` + +Grant `--allowConfigEdit` when you want to tune plugin options from the browser and keep the result. Studio patches the matching fields in `kubb.config.ts` and leaves the comments and formatting around them alone. + +## Run headless or self-hosted + +`kubb studio` also runs on a build agent, with the agent token passed through `KUBB_AGENT_TOKEN` instead of an interactive approval: + +```shell [Terminal] +KUBB_AGENT_TOKEN=$KUBB_TOKEN kubb studio +``` + +Nothing is asked without a TTY, so grant what the run needs with flags on the command line. Point at a self-hosted instance with `--url`, and set `KUBB_HOME` to move the CLI's Studio state out of `~/.kubb`. + +For a connection that outlives your terminal, the [`kubblabs/kubb-agent` Docker image](https://hub.docker.com/r/kubblabs/kubb-agent) runs the same runtime and stays connected on its own. Use it when a team wants one shared agent instead of everyone connecting their own checkout. + +## See also + +- [`kubb studio` command](/docs/5.x/reference/commands/studio): every action, flag, and environment variable +- [Configuration](/docs/5.x/reference/configuration): the `kubb.config.ts` a session reads +- [Integrations](/docs/5.x/guide/integrations/): run generation inside your bundler instead diff --git a/docs/5.x/reference/commands/index.md b/docs/5.x/reference/commands/index.md index ec5319c1..cde9a938 100644 --- a/docs/5.x/reference/commands/index.md +++ b/docs/5.x/reference/commands/index.md @@ -1,13 +1,13 @@ --- layout: doc title: Commands -description: Reference for every command and flag exposed by the kubb CLI including init, generate, validate and mcp. +description: Reference for every command and flag exposed by the kubb CLI including init, generate, validate, mcp and studio. outline: [2, 3] --- # Commands -The `kubb` CLI is the main way to run Kubb. It reads your [configuration](/docs/5.x/reference/configuration) and runs the generation pipeline. It also scaffolds projects, validates specs, and starts a Model Context Protocol server for LLM clients. +The `kubb` CLI is the main way to run Kubb. It reads your [configuration](/docs/5.x/reference/configuration) and runs the generation pipeline. It also scaffolds projects, validates specs, starts a Model Context Protocol server for LLM clients, and connects a project to Kubb Studio. ## Usage @@ -19,6 +19,7 @@ COMMANDS generate [input] Generate files based on a 'kubb.config.ts' file (default) validate Validate a Swagger/OpenAPI file mcp Start the MCP server so an MCP client can interact with the LLM + studio [action] Connect this project to Kubb Studio and generate from the browser Use kubb --help for more information about a command. ``` @@ -33,12 +34,15 @@ Run `kubb` with no command and it runs `kubb generate`. | [`kubb generate`](./generate) | Run the code-generation pipeline from your `kubb.config.ts`. | | [`kubb validate`](./validate) | Validate a Swagger/OpenAPI document without running the pipeline. | | [`kubb mcp`](./mcp) | Start a Model Context Protocol server for LLM clients. | +| [`kubb studio`](./studio) | Connect the project to Kubb Studio and generate from the browser. | ## Environment variables The CLI reads these shared environment variables. -| Variable | Type | Used by | Description | -| ------------------------ | --------- | ------- | -------------------------------------------------------------------- | -| `KUBB_DISABLE_TELEMETRY` | `boolean` | all | Turn off anonymous usage telemetry. Set it to `1` or `true`. | -| `DO_NOT_TRACK` | `boolean` | all | Standard opt-out convention. Set it to `1` or `true`. | +| Variable | Type | Used by | Description | +| ------------------------ | --------- | -------- | --------------------------------------------------------------------------------- | +| `KUBB_DISABLE_TELEMETRY` | `boolean` | all | Turn off anonymous usage telemetry. Set it to `1` or `true`. | +| `DO_NOT_TRACK` | `boolean` | all | Standard opt-out convention. Set it to `1` or `true`. | +| `KUBB_HOME` | `string` | `studio` | Directory the CLI keeps its Studio state in. Defaults to `~/.kubb`. | +| `KUBB_AGENT_TOKEN` | `string` | `studio` | Connect with an existing agent token instead of approving this machine. | diff --git a/docs/5.x/reference/commands/studio.md b/docs/5.x/reference/commands/studio.md new file mode 100644 index 00000000..50d11042 --- /dev/null +++ b/docs/5.x/reference/commands/studio.md @@ -0,0 +1,88 @@ +--- +layout: doc +title: kubb studio +description: The studio command connects a project to Kubb Studio, so you can trigger generation from the browser while Kubb keeps running on your own machine. +outline: [2, 3] +--- + +# `kubb studio` + +Run `kubb studio` to connect this project to [Kubb Studio](https://kubb.studio). Kubb keeps running on your machine, reads the config and spec from disk, and streams progress and generated files back to the browser over a WebSocket. + +> [!WARNING] +> This feature is under active development. Use it with caution and expect breaking changes. + +```terminal +command: kubb studio +output: + - ✘ write generated files + - ✘ edit kubb.config.ts + - ✘ use a Studio spec + - ✘ run formatter, linter, postGenerate +``` + +## Usage + +Connect the current project. The first run asks you to approve it in Studio, and later runs connect straight away. + +```shell [Terminal] +kubb studio +``` + +## Actions + +The first positional argument picks what the command does. It defaults to `connect`. + +| Action | Description | +| --------- | ----------------------------------------------------------------------- | +| `connect` | Connect, then hold a session open and generate on request. | +| `login` | Connect this machine without opening a session. | +| `logout` | Disconnect this machine from Studio. | +| `status` | Show what this machine is connected as, plus the permissions saved for it. | + +```terminal +command: kubb studio status +output: + - Paired with https://kubb.studio as brave-otter +``` + +## Options + +| Option | Default | Description | +| ------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------- | +| `--config=`, `-c ` | | Path to a config file, such as `./kubb.staging.ts`. | +| `--url=` | `https://kubb.studio` | Base URL of the Studio instance to connect with. | +| `--allowWrite` | `false` | Write generated files to disk. Asked once per project when omitted. | +| `--allowConfigEdit` | `false` | Let Studio change plugin options in `kubb.config.ts`. Asked once per project. | +| `--allowInput` | `false` | Generate from a spec Studio sends instead of the one on disk. Asked once per project. | +| `--allowExec` | `false` | Run the formatter, the linter, and `output.postGenerate`. Asked once per project. | +| `--no-open` | | Do not open the approval page in a browser. | +| `--logLevel=`, `-l` | `info` | Set the verbosity. | + +> [!IMPORTANT] +> Flags are camelCase. `--allow-write` is not recognized, and the CLI ignores it without a warning, so the permission stays off. + +Approval is per Studio instance, so pointing `--url` at a different instance asks for approval again. The connection is read-only until you grant a permission: on the first connect the CLI asks a yes/no question for each one without a flag, then remembers the answer per project directory. Nothing is asked in CI or without a TTY, so an unattended run stays at whatever access it was given on the command line. + +## Environment variables + +| Variable | Description | +| ------------------ | ---------------------------------------------------------------------------------- | +| `KUBB_HOME` | Directory the CLI keeps its Studio state in. Defaults to `~/.kubb`. | +| `KUBB_AGENT_TOKEN` | Connect with an existing agent token instead of approving this machine. | + +## Examples + +```shell [Terminal] +kubb studio # connect read-only +kubb studio --allowWrite --allowExec # write files, run the formatter and linter +kubb studio login # connect without opening a session +kubb studio logout # disconnect this machine +kubb studio --url http://localhost:3000 # self-hosted Studio +``` + +## See also + +- [Kubb Studio guide](/docs/5.x/guide/integrations/studio): connect a project, run headless, and self-host +- [Commands](/docs/5.x/reference/commands/): every command the CLI exposes +- [Configuration](/docs/5.x/reference/configuration): the `kubb.config.ts` Studio reads