Skip to Content
vovk bundle

TypeScript Bundle

Quick CLI Ref
$ npx vovk bundle@draft --help
 
Usage: vovk bundle|b [options]
 
Generate TypeScript RPC and bundle it
 
Options:
  --out, --out-dir <path>                              path to output directory for bundle
  --include, --include-segments <segments...>          include segments
  --exclude, --exclude-segments <segments...>          exclude segments
  --prebundle-out-dir, --prebundle-out <path>          path to output directory for prebundle
  --keep-prebundle-dir                                 do not delete prebundle directory after bundling
  --config <config>                                    path to config file
  --schema <path>                                      path to schema folder (default: .vovk-schema)
  --origin <url>                                       set the origin URL for the generated client
  --openapi, --openapi-spec <openapi_path_or_urls...>  use OpenAPI schema instead of Vovk schema
  --openapi-get-module-name <names...>                 module names corresponding to the index of --openapi option
  --openapi-get-method-name <names...>                 method names corresponding to the index of --openapi option
  --openapi-root-url <urls...>                         root URLs corresponding to the index of --openapi option
  -h, --help                                           display help for command

The TypeScript RPC library can be bundled and published to NPM with pre-filled package.json and README.md files with bundle command:

npx vovk bundle

Internally, the bundling is made executing the following steps:

  1. It generates a client into tmp_prebundle directory (configured with bundle.prebundleOutDir: string) using ts template.
  2. Uses tsdown API  to bundle the generated client into a few compiled files at dist directory.
  3. Generates package.json and README.md files from packageJson and readme templates.
  4. Deletes the tmp_prebundle directory (configured with bundle.keepPrebundleDir: boolean).

After the bundling, the package can be published to NPM:

npm publish dist

Configuring the bundle

The bundling can be configured by adding the bundle object in the config file:

vovk.config.mjs
/** @type {import('vovk').VovkConfig} */
const config = {
  bundle: {
    prebundleOutDir: 'tmp_prebundle', // default
    keepPrebundleDir: false, // default
    tsdownBuildOptions: {
      outDir: 'dist', // default
    },
    generatorConfig: {
      origin: 'https://example.com',
      requires: {
        readme: '.', // default
        packageJson: '.', // default
        myTemplate: './foo', // custom template
      },
      excludeSegments: [],
      includeSegments: [],
      package: {}, // modifies package.json content
      readme: {}, // modifies README.md content
      samples: {}, // modifies README.md samples content
      openAPIObject: {}, // modifies resulting OpenAPIObject
      imports: {
        fetcher: './src/my-fetcher',
      },
      reExports: {}, // modifies re-exports in the generated index.ts
    },
  },
};
export default config;

prebundleOutDir or --prebundle-out flag

The prebundleOutDir is the directory where the TypeScript client will be generated before bundling. It defaults to tmp_prebundle.

keepPrebundleDir or --keep-prebundle-dir flag

If set to true, the prebundleOutDir will not be deleted after bundling. This can be useful for debugging or other purposes. Defaults to false.

package

The package object allows you to define the content of the generated package.json and README.md (for document title, description and version). You can specify fields like name, version, description, etc. By default it uses the root package.json file properties, extended with package option of composed client.

tsdownBuildOptions

Any options that can be passed to tsdown  build function. The options are outlined in the tsdown documentation .

generatorConfig

The generatorConfig object accepts and overrides the same options as the generatorConfig of the root of the config file.

Troubleshooting

At some TypeScript module configuration cases you might get the following errors:

[UNLOADABLE_DEPENDENCY] Error: Could not load lib/internal/methods/object.ts - No such file or directory (os error 2).

or

[plugin rolldown-plugin-dts:generate]
RollupError: tmp_prebundle/index.ts(17,14): error TS2742: The inferred type of 'XxxRPC' cannot be named without a reference to '../node_modules/vovk/mjs/client/types'. This is likely not portable. A type annotation is necessary.

It is recommended to create a separate tsconfig.bundle.json file for tsdown, optionally extending the root tsconfig.json:

vovk.config.mjs
/** @type {import('vovk').VovkConfig} */
const config = {
  bundle: {
    tsdownBuildOptions: {
      tsconfig: './tsconfig.bundle.json',
    },
  },
};
export default config;

moduleResolution set to bundler fixes the first error, and paths set to the vovk/* module fixes the second error:

tsconfig.bundle.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "paths": {
      "@/*": ["./src/*"],
      "vovk/*": ["./node_modules/vovk/*"],
    },
  }
}

Roadmap

  • ✨ Segmented bundle - create separate bundles for each segment.
  • ✨ Watch mode - watch  for changes and re-bundle automatically.
  • ✨ Standalone CLI command for OpenAPI mixins to generate and bundle third-party APIs into TypeScript clients using --openapi* flags.
Last updated on
CLIvovk dev