Skip to Content
Client Templates

Client Templates

Introduction

Vovk.ts renders client libraries from EJS  templates. To accommodate a wide range of use cases, Vovk.ts provides simple yet powerful template logic that meets the following requirements:

  1. Render multiple files from a single template definition. This means a “template” is a directory with one or more files, where files with the .ejs extension are rendered as EJS templates and other files are copied as-is. An index.ts.ejs file is rendered as index.ts, and an index.ts without the .ejs extension is copied as-is.
  2. Use existing templates as a base for other templates using the extends option. This allows you to create a new template that extends an existing one and overrides some of its options.
  3. Use existing templates as dependencies for other templates using the requires option. This allows you to create a new template that composes existing templates and renders them into the output directory.

Template definitions are configured in config under the clientTemplateDefs option. By default, this object includes built-in template definitions that become visible if you set emitConfig to true or, if emitConfig is an array, add clientTemplateDefs. You can then inspect .vovk-schema/_meta.json, which lists all available template definitions under config.

Example

To make the options in the next section concrete, let’s break down the built-in template definition for the Rust client. The primary definition is stored under the rs key, which is the template name used in the segmented client or composed client configuration.

By itself, it doesn’t contain files, so it omits templatePath. Instead, it extends the rsSrc definition that renders Rust source files to ./src (relative to outDir), the rsPkg definition that renders Cargo-related files to the root of outDir, and the rsReadme definition that renders README files to the root of outDir. The rs template definition also sets a composedClient option that overrides the default outDir to dist_rust, so it isn’t compiled into the node_modules/.vovk-client folder used by the composed TypeScript client.

The rsSrc definition uses templatePath to point to its template directory (lib.rs.ejs, http_request.rs, etc.). It requires the schemaJson template that renders schema.json, which combines the full schema from the .vovk-schema/ folder.

Take a look at the example copied from the project codebase. BuiltInTemplateName is an enum whose values match the built-in template keys:

const rsTemplateDemo = {
  [BuiltInTemplateName.schemaJson]: {
    templatePath: `vovk-cli/client-templates/${BuiltInTemplateName.schemaJson}/`,
  },
  [BuiltInTemplateName.rsSrc]: {
    templatePath: `vovk-rust/client-templates/${BuiltInTemplateName.rsSrc}/`,
    requires: {
      [BuiltInTemplateName.schemaJson]: './',
    },
  },
  [BuiltInTemplateName.rsPkg]: {
    templatePath: `vovk-rust/client-templates/${BuiltInTemplateName.rsPkg}/`,
  },
  [BuiltInTemplateName.rsReadme]: {
    templatePath: `vovk-rust/client-templates/${BuiltInTemplateName.rsReadme}/`,
  },
  [BuiltInTemplateName.rs]: {
    composedClient: {
      outDir: 'dist_rust',
    },
    requires: {
      [BuiltInTemplateName.rsSrc]: './src/',
      [BuiltInTemplateName.rsPkg]: './',
      [BuiltInTemplateName.rsReadme]: './',
    },
  },
};

(all paths end with a slash / for clarity, though it isn’t required)

This setup allows you to generate the full Cargo package with:

npx vovk generate --from rs --out ./dist_rust

Or generate only the source code with:

npx vovk generate --from rsSrc --out ./my_rust_project/src

Or only the README.md file with:

npx vovk generate --from rsReadme --out ./my_rust_project

Template Definitions

The available options:

extends?: string

Specifies the name of the built-in template this definition extends. Use extends to inherit and override options, such as segmentedConfig.outDir.

templatePath?: string

Path to the template directory, relative to the project root. If omitted, the template can still use requires to include files from other templates.

requires?: Record<string, string>

Other template definitions this template depends on. Keys are template names; values are target paths where those templates will be rendered, relative to the output directory root.

composedClient?: object

Options for the composed client that extend the root composedClient options in config. Use this to customize behavior for this template (e.g., outDir, excludeSegments, etc.).

segmentedClient?: object

Options for the segmented client that extend the root segmentedClient options in config. Use this to customize behavior for this template (e.g., outDir, excludeSegments, etc.).

outputConfig?: object

Overrides outputConfig in the root config. Use this to customize the generated client (e.g., origin, openAPIObject, etc.).

Built-in Templates

rs

Renders the Rust client package that includes both source code and Cargo files.

  • requires rsSrc and rsPkg templates.
  • Defines a composedClient option to set the output directory to dist_rust.
  • extends rsSrc and rsPkg templates.

py

Renders the Python client package that includes both source code and setup files.

  • requires pySrc and pyPkg templates.
  • Defines a composedClient option to set the output directory to dist_python.
  • extends pySrc and pyPkg templates.

ts

Used as the default template for the segmented client. Renders TypeScript code.

cjs

Used as one of the default templates (the other one is mjs) for the composed client. Renders CommonJS code.

  • templatePath is vovk-cli/client-templates/cjs/.
  • requires schemaCjs, openapiCjs, and mixins (the last one is used conditionally if OpenAPI Mixins are used).

mjs

Used as one of the default templates (the other one is cjs) for the composed client. Renders ES Module code.

  • templatePath is vovk-cli/client-templates/mjs/.
  • requires schemaCjs, openapiCjs, and mixins (the last one is used conditionally if OpenAPI Mixins are used).

schemaTs

Renders the schema.ts file that imports the schema of available segments from the .vovk-schema/ folder and re-exports it as a TypeScript object.

  • templatePath is vovk-cli/client-templates/schemaTs/.

schemaCjs

Renders the schema.cjs and schema.d.cts files that import the schema of available segments from the .vovk-schema/ folder and re-export it as a CommonJS module.

  • templatePath is vovk-cli/client-templates/schemaCjs/.

schemaJson

Renders the schema.json file that contains the full schema of all segment schemas combined from the .vovk-schema/ folder for the composed client, or of a single segment schema for the segmented client.

  • templatePath is vovk-cli/client-templates/schemaJson/.

openapiTs

Renders the openapi.ts file that re-exports the OpenAPI schema located in the openapi.json file (provided by the openapiJson template) in the same folder.

  • templatePath is vovk-cli/client-templates/openapiTs/.
  • requires openapiJson template to import the OpenAPI schema in the generated code.

openapiCjs

Renders the openapi.cjs and openapi.d.cts files that re-export the OpenAPI schema located in the openapi.json file (provided by the openapiJson template) in the same folder.

  • templatePath is vovk-cli/client-templates/openapiCjs/.
  • requires openapiJson template to import the OpenAPI schema in the generated code.

openapiJson

Renders the openapi.json file that contains the OpenAPI schema. Can be used separately if you need to provide the OpenAPI schema in your project.

  • templatePath is vovk-cli/client-templates/openapiJson/.

readme

Renders the README.md file that contains the generated TypeScript client documentation. It’s rendered from data provided in the package.json file, whose properties can be overridden in the bundle, composedClient, or segmentedClient options in the config file, at the root level or on the template definition level. Each method is documented as code, providing self-documented code examples for each RPC method that can be copied directly to your codebase.

  • templatePath is vovk-cli/client-templates/readme/.

packageJson

Renders the package.json file that makes the generated client ready to be published to NPM. It includes the name, version, description, and repository taken from the root package.json, and other package fields that can be overridden in the bundle, composedClient, or segmentedClient options in the config file, at the root level or on the template definition level.

  • templatePath is vovk-cli/client-templates/packageJson/.

mixins

Generates types and schema for OpenAPI Mixins when they are present.

  • templatePath is vovk-cli/client-templates/mixins/.

rsSrc

Renders Rust client source code files, such as lib.rs, http_request.rs, etc.

  • templatePath is vovk-rust/client-templates/rsSrc/.
  • requires schemaJson template to include the full schema in the generated code.

rsPkg

Renders Cargo.toml and README.md files for the Rust client.

  • templatePath is vovk-rust/client-templates/rsPkg/.
  • requires rsReadme template to include the README file in the package.

rsReadme

Renders the README.md file for the Rust client. Works similarly to the readme template.

  • templatePath is vovk-rust/client-templates/rsReadme/.
Last updated on
Multitenancy 🧪Packages