vovk generate

Quick CLI Ref


$ npx vovk generate --help
 
Usage: vovk generate|g [options]
 
Generate RPC client from schema
 
Options:
  --composed-only                                              generate only composed client even if segmented client is enabled
  --out, --composed-out <path>                                 path to output directory for composed client
  --from, --composed-from <templates...>                       client template names for composed client
  --include, --composed-include-segments <segments...>         include segments in composed client
  --exclude, --composed-exclude-segments <segments...>         exclude segments in composed client
  --segmented-only                                             generate only segmented client even if composed client is enabled
  --segmented-out <path>                                       path to output directory for segmented client
  --segmented-from <templates...>                              client template names for segmented client
  --segmented-include-segments <segments...>                   include segments in segmented client
  --segmented-exclude-segments <segments...>                   exclude segments in segmented client
  --prettify                                                   prettify output files
  --schema, --schema-path <path>                               path to schema folder (default: ./.vovk-schema)
  --config, --config-path <config>                             path to config file
  --origin <url>                                               set the origin URL for the generated client
  --watch <s>                                                  watch for changes in schema or openapi spec and regenerate client; accepts a number
                                                               in seconds to throttle the watcher or make an HTTP request to the OpenAPI spec URL
  --openapi, --openapi-spec <openapi_path_or_urls...>          use OpenAPI schema for client generation
  --openapi-module-name, --openapi-get-module-name <names...>  module names corresponding to the index of --openapi option
  --openapi-method-name, --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
  --openapi-mixin-name <names...>                              mixin names corresponding to the index of --openapi option
  --openapi-fallback <paths...>                                save OpenAPI spec and use it as a fallback if URL is not available
  --log-level <level>                                          set the log level
  -h, --help                                                   display help for command

The command vovk generate generates client at node_modules/.vovk-client folder from the schema at .vovk-schema folder that in its turn was generated by Vovk Dev Watcher that is run by vovk dev command.


npx vovk generate
# or
npx vovk g

Its automatically added to the "generate" script in the package.json file when vovk init is run.


{
  "scripts": {
    // ...
    "generate": "vovk generate"
  }
}

You can specify the output directory with --out (shortcut for --client-out-dir) flag and prettify the output with --prettify flag.


npx vovk generate --out ./client --prettify

Vercel build

In order to build the client at Vercel, you need to add "vercel-build" script to the package.json with generate script.


{
  "scripts": {
    // ...
    "build": "next build",
    "generate": "vovk generate",
    "vercel-build": "npm run build && npm run generate"
  }
}

Custom templates (experimental)

Vovk.ts offers a way to generate a completely custom client library, including a client for a different programming language using EJS templates or just copying over any non-EJS files.

You can achieve this by specifying templates with --template (or --templates) flag with either path to a template file or one of the predefined values: ts, compiled, python, none. The none value is used to skip the client generation. It’s useful when you want to generate only the schema with --full-schema flag described below.


npx vovk generate --template ./path/to/template.js.ejs --template ./path/to/another-template.py.ejs --template ts

If --template receives a path to a file, it should be an EJS template with .ejs extension or any other file that’s going to be copied over to the output directory.

Please check the default templates to see how to create your own.

By the time being, there is the available variables passed to a EJS template:


const ejsData = {
  apiRoot, // API root made from config.origin and config.rootEntry
  fetcherClientImportPath, // Import path to the default fetcher or custom fetcher defined as config.fetcher
  schemaOutImportPath, // Import path to the schema output directory
  validateOnClientImportPath, // Import path to the validateOnClient file
  segments, // List of segments, an array of { routeFilePath: string; segmentName: string; segmentImportPath: string; }
  segmentsSchema, // Collection of schema: Record<string, import('vovk').VovkSchema>
};

—full-schema flag

The --full-schema flag generates a single .json file that combines all the schema objects into one.


npx vovk generate --full-schema

By default the file is named full-schema.json but you can specify a custom name with the flag.


npx vovk generate --full-schema=my-schema.json

To skip the client generation and generate only the full schema, use the --template none flag.


npx vovk generate --full-schema --template none

The signature of the full schema file is Record<string, import('vovk').VovkSchema>, where the key is the segment name and the value is the schema object for that segment.

You can also specify experimental_clientGenerateTemplateNames at config to provide a list of templates that are going to be used by vovk generate command. By default it’s value is ['ts', 'compiled'] but you can redefine it to generate the client from the other templates or provide less items, like ['ts'] to generate only an uncompiled TypeScript file.


const config = {
  // ...
  experimental_clientGenerateTemplateNames: [
    'ts',
    'compiled',
    'python',
    './my-client-templates/custom-template.js.ejs',
  ],
};

Python client (experimental)

Vovk.ts offers a way to generate a Python client library using a custom EJS template. You can achieve this by specifying python value with --template flag. It reads the schema from the full-schema.json to build a library with similar functionality to the TypeScript client.


npx vovk generate --template python --full-schema --out ./client

The command copies over **init.py** file, located at vovk-cli/client-templates/python .

The Python client is experimental and created as a proof of concept. It’s going to be improved in the future to provide better typing and nicer developer experience. Feel free to contribute.


from client import UserRPC, LanguageModelRPC, ServerError
from jsonschema.exceptions import ValidationError
import requests
 
if __name__ == "__main__":
    base_url = "http://localhost:3000/api"
 
    try:
        # 1) Non-streaming usage: returns a dict (parsed JSON) or text, etc.
        resp_data = UserRPC.postWithBodyQueryAndParams(
            base_url,
            query={'hey': 'query'},
            body={'hello': 'body'},
            params={'foo': 'bar'}
        )
        # resp_data will be either JSON (Python dict) or text, depending on the content type
        print("Non-streaming response:", resp_data)
 
        # 2) Streaming usage: if endpoint returns 'x-vovk-stream: true'
        #    we'll get a generator
        stream_data = LanguageModelRPC.getWithStreaming(
            base_url,
            query={'query': 'streamme'},
            body=None,
            params=None
        )
 
        # Check if it's a generator
        if hasattr(stream_data, '__iter__'):
            print("\nStreaming data:")
            for item in stream_data:
                print("Got item:", item)
        else:
            # It's not streaming, so it's just the final data
            print("\nGot a non-stream response for streaming endpoint:", stream_data)
 
    except ServerError as se:
        print("ServerError caught:", se)
        print("Status code:", se.status_code)
        print("Message:", se.server_message)
 
    except ValidationError as ve:
        print("Client-side validation error:", ve.message)
 
    except requests.HTTPError as he:
        print("HTTP error:", he)