Skip to Content
Config

vovk.config.{js,cjs,mjs}

The config file is used to define options for the CLI, update template definitions, and customize other settings. In some cases, it’s optional, since the CLI can use default options or flags, but for more advanced usage, it’s recommended to create a config file.

Valid Config File Names

The config can be implemented either as a CJS module or as an ESM module. It supports the following extensions: .js, .cjs, .mjs, and can be stored at the root of the project as well as in 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 is executed, it checks if the project is a module and if the .config folder exists to create the proper file name.

Config Options

The config options extend the VovkConfig type from the vovk package and can be used to define the following options:

emitConfig: boolean | string[]

Indicates whether the config options should be emitted as the .vovk-schema/_meta.json file. If set to true, it will emit all options. If set to an array of strings, it will emit only the specified options. Default is ["libs", "generatorConfig"].

clientTemplateDefs: object

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

composedClient: object

Redefines config options for the composed client, such as outDir, fromTemplates, excludeSegments, etc.

segmentedClient: object

Redefines config options for the segmented client, such as outDir, fromTemplates, excludeSegments, etc.

bundle: object

Redefines config options for the bundle, such as excludeSegments, tsdown build options , etc.

modulesDir = 'src/modules'

Indicates the directory where the module files are located. Used to generate modules with the vovk new command and to watch for changes in the modules when vovk dev is running.

schemaOutDir = '.vovk-schema'

The directory where the schema will be generated. Defaults to .vovk-schema.

rootEntry = 'api'

The root entry point for the API routes. By default, it’s api, meaning that the API routes will be served from the /api path and the segments (route.ts files) are located in the ./src/app/api folder (the src/ directory is optional). If you want to serve the API from the root of the domain, set it to an empty string ''. In this case, the segments will be located in the ./src/app folder.

rootSegmentModulesDirName = ''

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

logLevel = 'info'

Defines the log level  for the CLI. The values are "debug", "info", "warn", "error". By default, it’s "info". Set it to "debug" to see underlying operations, such as file watching information.

devHttps = false

Progressive Web Apps  require the HTTPS protocol to be used both in development and production. To enable HTTPS in development, you can use the --experimental-https flag with the next dev command and enable HTTPS mode for vovk dev by setting devHttps to true or providing the --https flag to the command.

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

If you don’t want to set the HTTPS mode enabled by default, you can create another NPM script that includes the flags:

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

moduleTemplates: object

Record of module template names and their paths. Used by the vovk new command to define templates for services, controllers, or any other kind of module.

/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 create a new module at modulesDir with vovk new state thing command.

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

libs: object

The libs object is a conventional way to define configuration for libraries used by the client or any other configuration that you want to expose to the client. For example, it can be used to 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 will be emitted to the .vovk-schema/_meta.json file 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); // 'en'

generatorConfig

The generatorConfig object is used to customize the generated client code by changing imports, origin, or adding OpenAPI mixins.

origin: string | null

The origin for the client, used to generate the client with proper URLs. Defaults to '', meaning that the client will use relative URLs. If you want 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 controls the README.md generation to include the package name, version, description, and other fields, and also changes the generated code samples to include the proper package name.

By default, the names of Python and Rust packages are generated from the name field by converting it from kebab-case to snake_case. The package object also includes py_name and rs_name fields that can be used to override the package names respectively.

readme: VovkReadmeConfig

Used to customize the generated README.md file. It can contain a banner field that will be added to the top of the file, an installCommand field to customize the installation command, and a description field to override the package description that by default is taken from the package.description field.

samples: VovkSamplesConfig

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

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

Customizes the generated OpenAPI schema. It can contain info, servers, and other fields that will be merged with the automatically generated schema.

reExports: Record<string, string>

Used to re-export variables from other modules. The key is the name of the variables to be re-exported, and the value is the module path. The names are compiled into the re-export curly braces, and the paths are resolved to match the output directory. This feature is useful when you want to re-export something besides the generated RPC modules from the client (including the bundled package).

/vovk.config.mjs
const config = {
  // ...
  generatorConfig: {
    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, the top-level generatorConfig.reExports are applied to the root segment code.

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

imports: { fetcher, validateOnClient, createRPC }

Used to customize the imports of fetcher, validateOnClient, and createRPC functions. See Imports for more details.

segments

Used to configure each segment individually. It has the same properties as generatorConfig (such as origin, package, readme, samples, openAPIObject, reExports, imports) but also additional fields. Note that imports.createRPC is applicable to the top-level generatorConfig only. The additional fields are:

rootEntry: string | null

Overrides the entry point for the segment. Used for multitenancy to override the root entry from api to something else.

segmentNameOverride: string | null

Overrides the name of the segment used in the generated code. Used for multitenancy to override the path where the segment is served from.

openAPIMixin: VovkOpenAPIMixin

Turns the segment into an OpenAPI mixin, mixing the generated client with third-party APIs. See the OpenAPI mixins page for more details.

Last updated on
Rust RPC 🧪CLI