TypeScript Bundle
$ npx vovk bundle --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:
- It generates a client into
tmp_prebundle
directory (configured withconfig
) using ts template. - Uses tsdown APIΒ to bundle the generated client into a few compiled files at
dist
directory. - Generates
package.json
andREADME.md
files from packageJson and readme templates. - Deletes the
tmp_prebundle
directory.
After running the command, you will find the following files in the dist
directory:
- index.cjs
- index.d.cts
- index.mjs
- index.d.mts
- schema.cjs
- schema.d.cts
- package.json
- README.md
That can be published with:
npm publish dist
Configuring the Bundle
The bundling can be configured by adding the bundle
object in the config file:
/** @type {import('vovk').VovkConfig} */
const config = {
bundle: {
tsClientOutDir: 'tmp_prebundle', // default
dontDeleteTsClientOutDirAfter: false, // default
requires: {
readme: '.', // default
packageJson: '.', // default
myTemplate: './foo', // custom template
},
package: {}, // package.json content
readme: {}, // README.md content
tsdownBuildOptions: {
outDir: 'dist', // default
},
},
};
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
.
requires
The requires
object allows you to specify extra templates that will be rendered and copied to the dist
directory after bundling. The keys are the template names, and the values are the resulting paths, relative to the bundle output directory. It works the same way as the requires option in template definition.
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.
readme
The readme
object allows you to define the content of the generated README.md
. Currently only banner
value is supported. By default uses readme option of composed client.
tsdownBuildOptions
Any options that can be passed to tsdownΒ build
function. The options are outlined in the tsdown documentationΒ .
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
:
/** @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:
{
"compilerOptions": {
"moduleResolution": "bundler",
"paths": {
"@/*": ["./src/*"],
"vovk/*": ["./node_modules/vovk/*"],
},
}
}