Skip to Content
Config

vovk.config.{js,cjs,mjs}

The configuration file defines options for the CLI, updates template definitions, and customizes other settings. In many cases, it’s optional because the CLI can rely on defaults or flags. For more advanced use, creating a config file is recommended.

Valid Config File Names

The config can be authored as either a CJS or ESM module. It supports the following extensions: .js, .cjs, .mjs, and can live either at the project root or inside the .config  folder. In other words, the following paths are valid:

  • vovk.config.js
  • vovk.config.cjs
  • vovk.config.mjs
  • .config/vovk.config.js
  • .config/vovk.config.cjs
  • .config/vovk.config.mjs

When vovk init runs, it checks whether the project uses ES modules and whether the .config folder exists to choose the appropriate filename.

Config Options

The configuration extends the VovkConfig type from the vovk package and exposes the following options:

emitConfig: boolean | string[]

Controls whether to emit config options to .vovk-schema/_meta.json. If true, emits all options. If set to an array of strings, emits only the listed options. Default: ["libs"].

clientTemplateDefs: object

Extends template definitions with custom entries that can be used as the fromTemplates field in the composed client or segmented client.

composedClient: object

Overrides configuration for the composed client, such as outDir, fromTemplates, excludeSegments, and more.

segmentedClient: object

Overrides configuration for the segmented client, such as outDir, fromTemplates, excludeSegments, and more.

bundle: object

Overrides options for the bundle, including excludeSegments and tsdown build options .

modulesDir = 'src/modules'

Path to the directory containing module files. Used by vovk new to generate modules and by vovk dev to watch for module changes.

schemaOutDir = '.vovk-schema'

Directory where the schema is generated. Default: .vovk-schema.

rootEntry = 'api'

The root entry point for API routes. By default it is api, so routes are served under /api, and segment route.ts files live in ./src/app/api (the src/ directory is optional). To serve the API from the domain root, set it to an empty string ''. In that case, segments are located in ./src/app.

rootSegmentModulesDirName = ''

Used exclusively by vovk new when multiple segments are present. If set to a non-empty string, root-segment modules are created inside a folder with this name. For example, if it’s "root", then running vovk new controller user will create src/modules/root/user/UserController.ts instead of src/modules/user/UserController.ts (the root of modulesDir).

logLevel = 'info'

Sets the log level  for the CLI. Accepted values: "debug", "info", "warn", "error". Default: "info". Use "debug" to see underlying operations (e.g., file watching).

devHttps = false

Progressive Web Apps  require HTTPS in both development and production. To enable HTTPS in development, pass --experimental-https to next dev and enable HTTPS mode for vovk dev by setting devHttps: true or passing the --https flag.

/vovk.config.mjs
const config = {
  // ...
  devHttps: true,
};
 
export default config;

If you prefer not to enable HTTPS by default, create a separate NPM script with the necessary flags:

/package.json
"scripts": {
    "dev-https": "vovk dev --https --next-dev -- --experimental-https",
    "dev": "vovk dev --next-dev",
}

moduleTemplates: object

A record of module template names mapped to their paths. Used by vovk new to define templates for services, controllers, or any other module type.

/vovk.config.mjs
/** @type {import('vovk').VovkConfig} */
const config = {
  // ...
  moduleTemplates: {
    state: './module-templates/state.ts.ejs',
    // you can add your own templates here
  },
};

You can then generate a module in modulesDir:

npx vovk new state thing # creates src/modules/thing/ThingState.ts
npx vovk new state segment/thing # creates src/modules/segment/thing/ThingState.ts

libs: object

A conventional place to define configuration for libraries used by the client—or any configuration you want exposed to the client. For example, it can define localization for vovk-ajv.

/vovk.config.mjs
/** @type {import('vovk').VovkConfig} */
const config = {
  // ...
  libs: {
    /** @type {import('vovk-ajv').VovkAjvConfig} */
    ajv: {
      options: {
        strict: false,
      },
      localize: 'de',
    },
  },
};
 
export default config;

If "libs" is present in emitConfig, it is emitted to .vovk-schema/_meta.json and can be accessed in multiple ways:

import { schema, UserRPC } from 'vovk-client';
 
console.log(schema.meta.config.libs.ajv.options.strict); // false
console.log(UserRPC.updateUser.fullSchema.meta.config.libs.ajv.localize); // 'de'

outputConfig

The outputConfig object customizes the generated client code by changing imports, origin, or adding OpenAPI Mixins.

origin: string | null

Base origin used to generate client URLs. Defaults to '' (relative URLs). To use absolute URLs, set it to your domain, e.g., https://example.com.

package: VovkPackageJson

Used to generate package.json (for the TypeScript client), Cargo.toml (for the Rust client), or pyproject.toml (for the Python client). It also influences README.md generation (name, version, description, etc.) and updates code samples to use the proper package name.

By default, Python and Rust package names are derived from package.name by converting kebab-case to snake_case. You can override them using the py_name and rs_name fields, respectively.

readme: VovkReadmeConfig

Customizes the generated README.md. Supports a banner appended to the top, an installCommand, and a description that overrides package.description.

samples: VovkSamplesConfig

Customizes generated code samples in README.md files and in Scalar  OpenAPI documentation. Allows the snippet function to explicitly render apiRoot and headers fields.

openAPIObject: Partial<import('openapi3-ts/oas31').OpenAPIObject>

Augments the generated OpenAPI schema. You can provide info, servers, and other fields; they are merged with the auto-generated schema.

reExports: Record<string, string>

Re-exports variables from other modules. Keys list the identifiers to re-export; values are module paths. Identifiers are placed inside curly braces, and paths are resolved relative to the output directory. This is useful when you want to re-export additional items alongside generated RPC modules (including the bundled package).

/vovk.config.mjs
const config = {
  // ...
  outputConfig: {
    reExports: {
      'type MyType': './src/types',
      'MyClass, myFunction': './src/utils',
      'MyComponent as RenamedComponent': './src/components',
      'default as MyDefault': './src/defaultExport',
    },
  },
};

Will be compiled to:

export { type MyType } from './src/types';
export { MyClass, myFunction } from './src/utils';
export { MyComponent as RenamedComponent } from './src/components';
export { default as MyDefault } from './src/defaultExport';
import { type MyType, MyClass, myFunction, RenamedComponent, MyDefault } from 'vovk-client';

When the segmented client is used, top-level outputConfig.reExports are applied to the root segment code.

import { type MyType, MyClass, myFunction, RenamedComponent, MyDefault } from '@/client/root';

imports: { fetcher, validateOnClient, createRPC }

Customizes the imports for fetcher, validateOnClient, and createRPC. See Imports for details.

segments

Configures each segment individually. It accepts the same properties as outputConfig (such as origin, package, readme, samples, openAPIObject, reExports, imports) and adds a few more. Note: imports.createRPC is only applicable at the top-level outputConfig.

rootEntry: string | null

Overrides the entry point for the segment. Useful for multitenancy to change the root entry from api to something else.

segmentNameOverride: string | null

Overrides the segment name used in generated code. Useful for multitenancy to change the served path.

openAPIMixin: VovkOpenAPIMixin

Turns the segment into an OpenAPI Mixin, combining the generated client with third-party APIs. See OpenAPI Mixins for details.

Last updated on
Rust RPC 🧪CLI