@utavn/cli

CLI tooling for UtaVN — scaffold, develop, and build visual novel projects.

Install

pnpm add -D @utavn/cli

Requires Node.js >= 22.0.0.

Quick Start

# Scaffold a new project
npx utavn create my-game
cd my-game
pnpm install
pnpm dev

This generates a ready-to-run project with:

my-game/
├── main.ts                          # Bootstrap
├── utavn.config.ts                  # Project metadata
├── plugins/my-game/                 # Your game types
│   ├── index.ts                     # Barrel export
│   ├── characters.ts                # Character extends UtaVNCharacter
│   ├── player.ts                    # Player extends Character
│   └── gameState.ts                 # GameState extends UtaVNGameState
├── locations/home/location.ts       # Starter location
├── global/events/intro.ts           # Intro event
└── global/actions/wait.ts           # Wait action

All imports use the @game alias — no relative path mess:

import type { GameState } from '@game';
import { narrator } from '@game';

Commands

| Command | Description | |---------|-------------| | utavn create <name> | Scaffold a new project | | utavn dev [dir] | Start the Vite dev server | | utavn build [dir] | Build a single-file HTML for production | | utavn verify [dir] | Type-check the project (vue-tsc --noEmit) | | utavn editor [dir] | Launch the browser-based visual editor |

How it works

The CLI wraps Vite with pre-configured plugins for Vue, Tailwind CSS v4, and single-file HTML output. It automatically resolves the @game alias by scanning the plugins/ directory, so the tsconfig path and Vite alias stay in sync.

Documentation

Full docs and examples: gitlab.com/xchanbik-vn/utavn

License

MIT