bundle

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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. |

From finom/vovk, MIT.

More from finom/vovk