bundle
/bundle
Obsługuje polecenie vovk bundle w Vovk.ts, które pakuje złożonego klienta TypeScript jako publikowalny pakiet npm bez zależności: bundle.build, tsdown, outputConfig, segmenty include i exclude oraz flagi openapi.
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 3
Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Obsługuje polecenie vovk bundle w Vovk.ts, które pakuje złożonego klienta TypeScript jako publikowalny pakiet npm bez zależności: bundle.build, tsdown, outputConfig, segmenty include i exclude oraz flagi openapi.
Wyzwalacze z opisu
Oryginalny opis (EN)
Vovk.ts `vovk bundle` CLI — packages composed TypeScript client as zero-dep publishable npm package. Covers `bundle.build` async fn, `tsdown@0.23.0` recipe, `outputConfig.origin` / `package` / `reExports` / `imports.validateOnClient: null`, `prebundleOutDir` / `outDir` / `keepPrebundleDir`, `--include`/`--exclude` segments, `--openapi-*` mixin flags. Use when user asks to \"publish my API client\", \"ship an SDK to npm\", \"build a publishable client package\", \"bundle the Vovk client\", \"generate a distributable npm SDK\", \"use tsdown with vovk\", or variations including why bundled packag
Jak działa
- bundle vs generate
- How bundling works
- bundle.build — required entry point
- bundle.outputConfig — what goes in package
- CLI flags
- What's bundled, what's omitted
- Bundled SDK + deriveTools
- Flows
- Gotchas
Podgląd SKILL.md
---
name: bundle
description: "Vovk.ts `vovk bundle` CLI — packages composed TypeScript client as zero-dep publishable npm package. Covers `bundle.build` async fn, `tsdown@0.23.0` recipe, `outputConfig.origin` / `package` / `reExports` / `imports.validateOnClient: null`, `prebundleOutDir` / `outDir` / `keepPrebundleDir`, `--include`/`--exclude` segments, `--openapi-*` mixin flags. Use when user asks to \"publish my API client\", \"ship an SDK to npm\", \"build a publishable client package\", \"bundle the Vovk client\", \"generate a distributable npm SDK\", \"use tsdown with vovk\", or variations including why bundled package omits `openapi`/`schema` entry points. Note: `vovk bundle` is **TypeScript-only**. For Python/PyPI publishing, hand off to **`python`** skill. For Rust/crates.io publishing, hand off to **`rust`** skill. Does NOT cover in-project client codegen (`@/client`) → **`rpc`** skill."
---
# Vovk.ts `vovk bundle`
`vovk bundle` packages composed TypeScript client as zero-dep npm package — pre-built JS + `.d.ts`, auto-gen `package.json`, auto-gen `README.md` w/ samples, ready for `npm publish`. Release step: `vovk generate` → in-project client for dev; `vovk bundle` → distributable SDK installed from registry.
**TypeScript-only.** Despite name, ships no Python/Rust clients. Those have own templates (`py` / `pySrc` / `rs` / `rsSrc`) and own publish flows — see **`python`** and **`rust`** skills.
## `bundle` vs `generate`
| Command | Purpose | Output | When |
|---|---|---|---|
| `vovk generate` | In-project TypeScript client + OpenAPI spec | `src/client/` (or `client/` without `src/app`), `.vovk-schema/` | Every build (`prebuild` hook), on schema changes during `vovk dev`. |
| `vovk bundle` | Publishable npm package — pre-built JS + `.d.ts` + `package.json` + `README.md` | `dist/` ready for `npm publish` | Ship SDK outside Next.js app. |
Don't run `vovk bundle` in normal dev; in-project client faster. Bundle when you need registry artifact.
## How bundling works
1. Vovk gens TypeScript client into `prebundleOutDir` (default `tmp_prebundle`) via `tsBase` template — uncompiled `.ts` source.
2. Vovk calls your `bundle.build({ entry, outDir, prebundleDir })` async fn. Plugs in any bundler (tsdown only tested one) to compile `entry` (the `tmp_prebundle/index.ts`) → JS + `.d.ts` under `outDir` (default `dist`).
3. Vovk emits `package.json` and `README.md` from `packageJson` and `readme` templates into `outDir`.
4. Vovk deletes `prebundleOutDir` unless `keepPrebundleDir: true` (handy for debugging prebundled source).
```sh
npx vovk bundle
npm publish dist
```
Published package consumed exactly like the in-project `@/client`:
```ts
import { UserRPC } from 'my-api-bundle';
await UserRPC.getUser({ params: { id: '123' } });
```
All TS-client features (call shape, `withDefaults`, type inference, `schema` access) survive bundle.
## `bundle.build` — required entry point
`bundle.build` is async fn. Vovk calls w/ absolute paths:
```ts
build: async ({ entry, outDir, prebundleDir }) => {
// entry — absolute path to the prebundled tmp_prebundle/index.ts
// outDir — absolute path where the bundler should emit JS + .d.ts
// prebundleDir — absolute path of the prebundle dir (rarely needed)
}
```
Vovk is bundler-agnostic — `esbuild`, `tsup`, `tsdown`, even `child_process` shell-out work. Only **tsdown** tested by Vovk's authors; docs warn: **pin `tsdown@0.23.0`** until newer versions confirmed compatible.
### Canonical `tsdown` recipe (pin 0.23.0)
```sh
npm install --save-dev tsdown@0.23.0
```
```ts filename="vovk.config.mjs"
/** @type {import('vovk').VovkConfig} */
const config = {
bundle: {
build: async ({ entry, outDir }) => {
const { build } = await import('tsdown');
// the code and the types build in two passes: one pass writes an extra chunk.js
for (const dts of [false, { emitDtsOnly: true }]) {
await build({
entry,
dts,
format: 'esm',
hash: false,
fixedExtension: true,
clean: !dts,
outDir,
platform: 'neutral',
outExtensions: () => ({ js: '.js', dts: '.d.ts' }),
outputOptions: { codeSplitting: false },
inputOptions: { resolve: { mainFields: ['module', 'main'] } },
deps: { alwaysBundle: ['!next/**'] },
});
}
},
outputConfig: {
origin: 'https://example.com',
package: {
main: './index.js',
types: './index.d.ts',
exports: { '.': { default: './index.js', types: './index.d.ts' } },
},
imports: { validateOnClient: null }, // shrinks the bundle considerably
},
},
};
export default config;
```
Resulting `dist/` layout:
```
dist/
├── package.json
├── README.md
├── index.js
└── index.d.ts
```
## `bundle.outputConfig` — what goes in package
`bundle.outputConfig` accepts same options as root-level `outputConfig` (bundle-specific overrides win). Key fields:
| Field | Purpose |
|---|---|
| `origin` *(required)* | Default API base URL baked into bundled client. Override at call time via `apiRoot`. |
| `package` | Overrides for generated `package.json`. Set `name`, `version`, `type`, `main`, `types`, `exports` here. Defaults pull from project root `package.json` where present. |
| `imports.validateOnClient: null` | Disables client-side AJV validation in bundle — usually big size win. |
| `imports.fetcher` | Custom fetcher path baked into bundle. |
| `reExports` | Extra named exports in generated `index.ts`. E.g. `{ doSomething: './src/utils' }` exposes helper alongside RPC modules. |
| `readme.banner` | String prepended to generated `README.md` (badges, logo HTML, status callouts). |
| `readme.installCommand` | Override install command in README (default: `npm install <package-name>`). For monorepo / private-registry / `pnpm` / `yarn`-first audiences. |
| `readme.description` | Replaces description block in README. Defaults to bundled `package.json` description. |
| `samples.apiRoot` | Base URL in generated README samples. Defaults to `outputConfig.origin`. Set to public-facing URL when `origin` points to staging/internal hostname. |
| `samples.headers` | Header map (e.g. `{ Authorization: 'Bearer YOUR_TOKEN' }`) in generated samples — shows consumers how to auth. |
Min viable `outputConfig` is `origin` + `package` block with `main`/`types`/`exports` matching bundler's output filenames.
### Root `bundle` keys (NOT under `outputConfig`)
These three live on root `VovkBundleConfig` (`config.bundle.*`), **not** nested under `outputConfig`:
| Field | Purpose |
|---|---|
| `requires` | Template dir overrides — `readme`, `packageJson`, or any custom template. Defaults to project root for both. |
| `includeSegments` / `excludeSegments` | Filter which Vovk segments contribute to bundle. Read from the root `bundle` config. |
## CLI flags
```
$ npx vovk bundle --help
Usage: vovk bundle|b [options]
--out, --out-dir <path> path to output directory for bundle
--prebundle-out-dir, --prebundle-out <path> path to output directory for prebundle
--keep-prebundle-dir do not delete prebundle directory after bundling
--include, --include-segments <segments...> include segments
--exclude, --exclude-segments <segments...> exclude segments
--schema, --schema-path <path> path to schema folder (default: .vovk-schema)
--config, --config-path <config> path to config file
--origin <url> set the origin URL for the generated client
--openapi, --openapi-spec <paths_or_urls...> use OpenAPI mixins for client generation
--openapi-module-name <names...> module name strategies, indexed against --openapi
--openapi-method-name <names...> method name strategies, indexed against --openapi
--openapi-root-url <urls...> root URLs, indexed against --openapi
--openapi-mixin-name <names...> mixin names, indexed against --openapi
--openapi-fallback <paths...> fallback files for --openapi URLs
--log-level <level> set the log level
```
`--openapi-*` family is positional — one entry per spec to `--openapi`, matching entry at same index to each subsidiary flag. Lets you bundle client combining your own segments with OpenAPI mixins w/o touching config file (handy for one-off CI bundles).
## What's bundled, what's omitted
**Included:** all RPC modules (with `@operation`-driven types), `schema` named export, type inference helpers, `withDefaults` method on each module.
**Omitted:**
- **`openapi` object** (would inflate bundle size). Consumers needing OpenAPI spec should hit runtime endpoint serving it (see **`openapi`** skill).
- Separate **`schema` module entry point** — bundle is single-entry by design. `schema` named export still importable from package root, `<RpcModule>.<method>.schema` still on every method:
```ts
import { schema, UserRPC } from 'my-api-bundle';
console.log(schema.segments[''].controllers.UserRPC.handlers.getUser.validation.params);
console.log(UserRPC.getUser.schema.validation.params);
```
## Bundled SDK + `deriveTools`
Bundled modules feed `deriveTools` identically to native ones — same call sig, same `@operation` metadata, same tool surface:
```ts
import { UserRPC } from 'my-api-bundle';
import { deriveTools } from 'vovk';
const tools = deriveTools({ modules: { UserRPC } });
```
See **`tools`** skill for full pipeline.
## Flows
### "Publish a TypeScript SDK for my Vovk API"
1. Add `bundle` to `vovk.config.mjs` w/ `build` fn (use tsdown recipe above) and `outputConfig` containing `origin` + `package` block.
2. `npx vovk bundle`.
3. `npm publish dist`.
### "Bundle a subset of segments as a public SDK"
Set `bundle.includeSegments` (or pass `--include` on CLI) to ship only public-facing segments. Under `bundle.outputConfig` the key is ignored and every segment ships. Useful when `admin`/`internal` segments live in same Vovk app but only `public` ships to consumers.
### "Bundle our API combined with a third-party OpenAPI spec"
Either configure mixins in `vovk.config.mjs` (see **`mixins`** skill) and run `npx vovk bundle`, or use CLI's `--openapi*` flags for one-off:
```sh
npx vovk bundle \
--openapi https://petstore3.swagger.io/api/v3/openapi.json \
--openapi-module-name PetstoreAPI \
--openapi-method-name auto \
--openapi-root-url https://petstore3.swagger.io/api/v3
```
### "My bundle is too large"
Disable client-side validation: `bundle.outputConfig.imports.validateOnClient: null`. Most apps consuming typed SDK trust their own input; AJV adds runtime weight often unneeded post-publish.
### "Debug the prebundled TypeScript before bundling"
Set `bundle.keepPrebundleDir: true` (or pass `--keep-prebundle-dir`). `tmp_prebundle` survives bundle run so you can inspect generated `index.ts` and module sources.
## Gotchas
- **`bundle` is TypeScript-only.** Don't reach for Python/Rust SDKs — those use `vovk generate` with `py`/`pySrc`/`rs`/`rsSrc` templates + language-native publish commands. See **`python`** / **`rust`** skills.
- **Pin `tsdown@0.23.0`.** Docs warn tsdown's API may break between minor versions; recipe above validated against 0.23.0. No floating range until upstream stability confirmed.
- **`origin` required.** Without it, bundled client has no default API base URL and consumers must pass `apiRoot` on every call. Bake it in — or use `withDefaults` post-import as one-off.
- **`NextResponse` type inference needs `next` package** at consumer install time (Next.js limitation, not Vovk's). For dynamic response headers in bundled controller, return plain `Response` w/ manual type casting.
- **`openapi` module isn't bundled** — consumers needing spec should fetch from runtime endpoint (see **`openapi`** skill's `OpenApiController` pattern). Deliberate size choice.
- **No segmented bundle yet** — bundled package is single-entry. Segmented bundling (one package per segment) is roadmap item; for now, run `vovk bundle` once per segment-subset via `includeSegments` if you need separate packages.
- **Don't bake secrets.** API tokens and signing keys must not ship in published package. Document consumers configure auth themselves (via `withDefaults` or custom fetcher).
- **CI placement.** Bundle in release workflow triggered by tag or manual dispatch, not every PR. Build step heavier than `vovk generate` and produces artifact you don't want piling up in main-branch CI.
- **`package.json` defaults inherit from project root.** Set `bundle.outputConfig.package.name` (and `version`) explicitly when project root's name isn't a good public package name — almost always the case for Next.js apps named after product, not SDK.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · finom/vovk | 100 | MIT |
| M-reza-kd/lead-flow-plugin | 100 | MIT |
| walkcast/walkcast | 84 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki ecde063a91e3 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 87python
Generuje typowany pakiet Python z API Vovk.ts przez vovk-python z TypedDict, walidacją po stronie klienta i publikacją na PyPI. - 95config
Pokazuje, jak skonfigurować Vovk.ts: plik vovk.config, każdy klucz i wartość domyślną oraz ustawienia tsconfig. - 90arch-tsdown-cli
Zakłada CLI w TypeScript na tsdown, z pnpm, Vitest i publikacją w npm przez Trusted Publisher. - 90arch-tsdown
Zakłada bibliotekę TypeScript na tsdown, z pnpm, Vitest i publikacją przez npm Trusted Publisher. - 100scaffold-cli
Tworzy szkielet CLI w TypeScript i pakietu npm z firmowym toolchainem, podwójnymi wyjściami tsdown, kontraktami CLI, changesetami i szablonami publikacji. - 100tsdown
Buduje biblioteki TypeScript i JavaScript przez tsdown, generuje deklaracje typów i pakuje je do wielu formatów.