Skip to Content
vovk new

vovk new

Quick CLI Ref
npx vovk-cli new --help
Usage: vovk new|n [options] [components...]
 
Create new components. "vovk new [...components] [segmentName/]moduleName" to create a new module or "vovk
new segment [segmentName]" to create a new segment
 
Options:
  -o, --overwrite                         overwrite existing files
  --static                                (new segment only) if the segment is static
  --template, --templates <templates...>  (new module only) override config template; accepts an array of
                                          strings that correspond to the order of the components
  --out, --out-dir <dirname>              (new module only) override outDir in template file; relative to the
                                          root of the project
  --no-segment-update                     (new module only) do not update segment files when creating a new
                                          module
  --empty                                 (new module only) create an empty module
  --dry-run                               do not write files to disk
  --log-level <level>                     set the log level
  -h, --help                              display help for command

The vovk new command creates segments and modules (such as controllers, services, or custom modules). It uses the moduleTemplates option from the config and can be extended with your own templates. It combines two workflows in one: vovk new segment [segment_name] and vovk new [module] [module_name_singular].

vovk new segment

vovk new segment

Root Segment

npx vovk new segment

If you run vovk new segment without an argument, it creates a root segment at /src/app/api/[[…vovk]]/route.ts (formatted with Prettier ). The segmentName option of initSegment is an empty string and can be omitted. The generated file contains:

import { initSegment } from 'vovk';
 
const controllers = {};
 
export type Controllers = typeof controllers;
 
export const { GET, POST, PATCH, PUT, HEAD, OPTIONS, DELETE } = initSegment({
  emitSchema: true,
  controllers,
});

When you run vovk dev, the segment emits a schema at .vovk-schema/root.json.

The segment exposes an API at /api/….

Root segments can be used alongside nested segments of any depth.

Nested Segment

npx vovk new segment foo

Running vovk new segment foo creates /src/app/api/foo/[[…vovk]]/route.ts (formatted with Prettier). The generated file includes:

// ...
export const { GET, POST, PATCH, PUT, HEAD, OPTIONS, DELETE } = initSegment({
  segmentName: 'foo',
  emitSchema: true,
  controllers,
});

When you run vovk dev, the segment emits a schema at .vovk-schema/foo.json.

The segment exposes an API at /api/foo/….

vovk new segment foo/bar/baz creates a nested segment at /src/app/api/foo/bar/baz/[[…vovk]]/route.ts, available at /api/foo/bar/baz/…. Here, segmentName is "foo/bar/baz".

vovk new [module] [name]

vovk new module 
npx vovk new controller service foo/user

vovk new (with anything other than segment) creates new modules in /src/modules (formatted with Prettier).

Command structure:

  • npx vovk new — the command.
  • Components — the module types to create (controller, service, or a custom module).
  • Module name (singular) with optional segment prefix: foo/user creates a module in /src/modules/foo/user/ and updates the foo segment. Omit the segment to target the root:
npx vovk new controller service user

When you create a controller with vovk new, the script updates the controllers list in the segment file and modifies route.ts using AST .

Template paths are defined via moduleTemplates in the config:

vovk.config.mjs
/** @type {import('vovk-cli').VovkConfig} */
const config = {
  moduleTemplates: {
    controller: 'vovk-dto/module-templates/controller.ts.ejs',
    service: 'vovk-cli/module-templates/type/service.ts.ejs',
    state: './my-templates/state.ts.ejs',
    dto: './my-templates/dto.ts.ejs',
  },
};
 
export default config;

npx vovk new controller state dto user creates UserController.ts, UserService.ts, and UserDto.ts in /src/modules/user and updates the root segment.

Built-in Templates

The built-in templates cover standard CRUD operations for controllers and services, including methods like get, list, create, update, and delete.

vovk init sets up a Vovk.ts project with the corresponding templates defined in the config. More specifically:

For an illustration, there is what’s generated when vovk-cli/module-templates/arktype/controller.ts.ejs is used as a controller template, creating UserController.ts with npx vovk new controller user:

src/modules/user/UserController.ts
import { prefix, get, put, post, del, operation } from 'vovk';
import { type } from 'arktype';
import withArk from '../../lib/withArk';
 
@prefix('users')
export default class UserController {
  @operation({
    summary: 'Get users',
  })
  @get()
  static getUsers = withArk({
    handle() {
      return { message: 'TODO: get users' };
    },
  });
 
  @operation({
    summary: 'Get single user',
  })
  @get('{id}')
  static getSingleUser = withArk({
    params: type({ id: type('string') }),
    handle(_req, { id }) {
      return { message: 'TODO: get single user', id };
    },
  });
 
  @operation({
    summary: 'Update user',
  })
  @put('{id}')
  static updateUser = withArk({
    body: type({ todo: type('true') }),
    params: type({ id: type('string') }),
    async handle(req, { id }) {
      const body = await req.json();
 
      return { message: `TODO: update user`, id, body };
    },
  });
 
  @operation({
    summary: 'Create user',
  })
  @post()
  static createUser = withArk({
    body: type({ todo: type('true') }),
    async handle(req) {
      const body = await req.json();
 
      return { message: `TODO: create user`, body };
    },
  });
 
  @operation({
    summary: 'Delete user',
  })
  @del('{id}')
  static deleteUser = withArk({
    params: type({ id: type('string') }),
    handle(_req, params) {
      const { id } = params;
 
      return { message: `TODO: delete user`, id };
    },
  });
}

When controllers are created along with services, the controller template includes service imports and method calls.

Shortcuts

Controllers and services can be created with shortcuts:

npx vovk n c s user

Which is equivalent to:

npx vovk new controller service user

Custom Templates 🚧

Coming soon.

Roadmap

  • 📝 Document custom module templates and available variables.
Last updated on
vovk initOpenAPI Specification