#CLI commands

VextJS provides the vext command line tool, covering the complete life cycle of project creation, development, construction and deployment.

#Installation

The vext CLI is installed with the vextjs package, no additional installation is required:

npm install vextjs

After installation, it can be called in the following ways:

# via npx
npx vext <command>

# Via package.json scripts (recommended)
npm run dev # → vext dev
npm start # → vext start
npm run build # → vext build

#Command overview

#vext create — Create a project

Interactively create new VextJS projects and automatically generate project skeleton and configuration files. The default template is fullstack-react; API-only scaffolding remains available through --template api --frontend none. The full-stack starter opens with a server-rendered Vext launchpad that you can edit immediately, including a visible Vext Guide link and a local API documentation entry at /docs. Its default configuration enables OpenAPI, so that local entry is live after both vext dev and production vext start; API-only projects remain opt-in.

#Usage

npx vextjs create <project-name> [options]

#Options

#Example

# Create TypeScript full-stack project (default Native Adapter)
npx vextjs create my-app

#Specify Adapter
npx vextjs create my-app --adapter hono
npx vextjs create my-app --adapter fastify

# Create JavaScript full-stack project
npx vextjs create my-app --js

# Create API-only project
npx vextjs create my-api --template api --frontend none

# Skip dependency installation
npx vextjs create my-app --skip-install

The command accepts exactly one project name. Extra positional arguments fail before any target directory is created. If automatic dependency installation fails, create exits non-zero and keeps the generated files; run cd <project-name> followed by npm install to retry. Generated TypeScript full-stack projects include NodeNext-compatible mappings for the built-in @frontend, @pages, @components, @styles, and @assets aliases.

#Generated directory structure

my-app/
├── public/
│ ├── favicon.svg # Contrast-safe favicon variant of the V mark
│ └── vext-mark.svg # Transparent V mark used by the starter app shell
├── src/
│ ├── config/
│ │ ├── default.ts # Shared configuration (port: 3000)
│ │ ├── development.ts # Development profile
│ │ ├── production.ts # Production profile
│ │ ├── local.ts # Empty local override; ignored by Git
│ │ └── bootstrap.ts # Tracked startup entry with providers: []
│ ├── frontend/
│ │ ├── components/AppShell.tsx # Shared React shell
│ │ ├── locales/en-US.ts # Starter messages
│ │ ├── pages/ # React pages, layout, document, and error page
│ │ └── styles/index.css # Vext launchpad styles
│ ├── preload/ # Optional preload sources; create with the first real preload file
│ ├── routes/index.ts # URL handler and server data
│ ├── services/example.ts # Example service
│ └── types/
│   ├── generated/.gitkeep # Vext-managed typegen output root (TS projects)
│   ├── shared/
│   │ └── greeting.d.ts # Application-owned data contract shared by server and UI
│   └── frontend/
│     └── home.d.ts # Application-owned page/render contract
├── package.json
├── tsconfig.json
└── .gitignore

#Type directory boundaries

The tree above is the default TypeScript full-stack starter. Its src/types/** folders have separate owners:

In TypeScript projects, vext typegen writes only src/types/generated/**; it does not replace application-owned files in shared/** or frontend/**. JavaScript create/dev/typegen flows do not create that public TypeScript tree; their tooling declarations remain under .vext/types.

The scaffold does not reserve src/types/server/**. Keep a type that is private to one route or service next to that server owner; create src/types/server/services/** only when your application has a real shared backend service boundary. Runtime enum/constant values belong owner-near or under src/constants/services/**, not under src/types/**; see Project structure.

The starter deliberately does not create root or directory-level placeholder README.md files. Generated user source is English-first in both TypeScript and JavaScript, for full-stack and API-only templates; files under explicit locale directories are the only language-content exception. Conventional directories such as src/middlewares/, src/plugins/, src/locales/, and the canonical src/preload/ remain supported and are created when you add real source files. The legacy project-root preload/ directory is not scaffolded.

For the default fullstack starter, public/vext-mark.svg is a transparent navigation mark and public/favicon.svg is a contrast-safe favicon variant. They share the same V geometry; the app shell uses the former, and both are copied with the rest of public/ assets.

After creation is complete:

cd my-app
npm run dev

Visit http://localhost:3000 and you should see the React client. API routes are available at /api/hello and /api/health.

vext create directly generates src/config/local.ts as an empty VextConfigOverride and src/config/bootstrap.ts with providers: []. The defaults have no logger, provider, external connection, or other business side effect. local.ts is excluded by .gitignore and may be absent after clone; bootstrap.ts is tracked and can later register a provider through defineBootstrapConfig().

#vext dev — development mode

Start the project in development mode, supporting file monitoring and smart hot reloading.

#Usage

vext dev [options]

vext dev does not support positional arguments. Value options such as --root, --port, --host, --config, --poll-interval, --debounce, --startup-profile-json, and --port-conflict must be followed by a non-option value; numeric options require complete integers, so prefixes such as 3000x and 50x fail.

#Options

#Port conflict policy

• error: direct failure (default)
• prompt: Ask the parent process how to handle it in TTY environment
• kill: Try to kill the process occupying the port
• next: automatically selects the next available port

vext dev --port-conflict prompt
vext start --port-conflict next

#Start log tiering

By default, vext dev only prints the listening address and total startup time, and then prints the necessary results during cold restart / hot reload. vext dev --startup-profile will output a human-readable startup summary and detailed events; the summary is main/preflight, main/preload, pre-worker-bootstrap, compile, config, i18n, database, plugins, middleware, services, routes, openapi, listen, onReady Classification in other stages; unnamed empty windows that exceed the threshold will be entered into profile JSON in the form of gap.*.

--startup-profile-json <path> only writes JSON files and will not automatically print summary or details; if you need to output both at the same time, you can combine --startup-profile --startup-profile-json <path>.

If you need life cycle troubleshooting details, you can enable:

vext dev --verbose-lifecycle
VEXT_VERBOSE_LIFECYCLE=1 vext start

#Example

# Use default settings from configuration file
vext dev

#Specify port
vext dev --port 8080

#Specify address and port
vext dev --host 127.0.0.1 --port 8080

# Turn on 50ms anti-shake (merged into one reload when saving in quick succession)
vext dev --debounce 50

# Docker/NFS environment uses polling mode
vext dev --poll --poll-interval 2000

# Disable Soft Reload (all changes go to Cold Restart)
vext dev --no-hot

# Output the summary and detailed time consumption of the startup phase
vext dev --startup-profile

# Only write JSON, do not print summary/details
vext dev --startup-profile-json .vext/inspect/startup-profile.json

#Hot reload strategy

vext dev provides a three-layer hot reload strategy and automatically selects the optimal method:

See the Hot Reload chapter for details.

Frontend files under src/frontend/** and static assets under public/** trigger a frontend rebuild message. React pages, layouts, and shared components use Fast Refresh by default; they do not require a backend cold restart unless mixed with backend changes.

#package.json script

{
  "scripts": {
    "dev": "vext dev"
  }
}

#vext build — Build the project

Compile TypeScript source code into JavaScript to generate a production-usable dist/ directory; tool products such as typegen and route manifest will be refreshed before building. When frontend is enabled, vext build also bundles the browser client into dist/client/.

#Usage

vext build [options]

#Options

The CLI flag remains opt-in for an existing project. New TypeScript starters set their generated package.json build script to vext build --typecheck, so npm run build includes semantic checking by default. JavaScript starters use vext build without invoking TypeScript.

Production CLI builds minify backend output by default. Use --no-minify for readable local output, or set VEXT_BUILD_MINIFY=false when the opt-out is controlled by the environment. Frontend production minification still follows frontend.build.minify.

#Example

# Build project
vext build

# Refresh generated / manifest and then perform type checking and build again
vext build --typecheck

# Clean old dist and build
vext build --clean

#Specify output directory
vext build --outdir build

# Keep readable output for a local inspection
vext build --no-minify

# Upload frontend static assets after building
vext build --upload-assets

# Print the frontend upload plan only
vext build --upload-assets --deploy-dry-run

# Start after building
vext build && vext start

#Build behavior

• Refresh .vext/types/*.generated.d.ts, .vext/manifest/services.json, and .vext/manifest/routes.json first; TypeScript projects also refresh src/types/generated/index.d.ts
• When --typecheck is enabled, execute the project-local tsc --noEmit after refreshing generated products; missing local TypeScript fails with an actionable error and never falls back to network resolution
• Use esbuild for server compilation and frontend bundling
• Positional arguments are not supported; value options such as --outdir and --config require a non-option value
• The output directory defaults to dist/
• Maintain source code directory structure
• .js and .js.map files are generated by default; declaration files will not be generated in dist/
• Repeated builds automatically remove stale backend outputs left by deleted or renamed server source files; --clean clears the entire output directory first
• Destructive cleanup fails closed when the resolved output is the project root, source root, or their parent; frontend output, asset directory, naming patterns, and server outfile must also remain inside their declared build boundary
• When frontend is enabled, dist/client/index.html, manifest.json, deploy-manifest.json, size-report.json, static assets, and client contract artifacts are generated
• When --upload-assets is used, Vext reads dist/client/deploy-manifest.json and uploads only changed static assets by sha256 and frontend.deploy.upload.stateFile

#package.json script

{
  "scripts": {
    "build": "vext build",
    "prepublishOnly": "vext build"
  }
}

vext deploy assets [options]

# Use the upload target from configuration
vext deploy assets

# Plan only
vext deploy assets --dry-run

# Override this upload target directory and key prefix
vext deploy assets --target-dir .deploy/cdn --prefix my-app/v1

vext typegen [options]

.vext/types/services.generated.d.ts
.vext/types/app-extensions.generated.d.ts
src/types/generated/index.d.ts # TypeScript projects only; Vext-managed
.vext/manifest/services.json

vext typegen
vext typegen --check
vext typegen --write-manifest
vext typegen --services --root ./examples/hello-world

vext doctor <target> [options]

vext doctor routes
vext doctor routes --write-inspect
vext doctor routes --write-inspect --write-manifest --json

vext start [options]

#Build first, then start
vext build
vext start

#Specify port
vext start --port 8080

# Automatically switch to the next available port when there is a port conflict
vext start --port-conflict next

# Check the production cold-start phase time consumption
vext start --startup-profile
vext start --startup-profile-json .vext/inspect/start-profile.json

# Load the production profile and override the port
vext start --port 8080

# Load a custom config profile (src/config/sg-sit.ts needs to exist)
vext start --config sg-sit

# The following two methods are equivalent
vext
vext start

// src/config/production.ts
export default {
  cluster: {
    enabled: true,
    workers: "auto", // Automatically detect the number of CPU cores
  },
};

VEXT_CLUSTER=1 vext start

{
  "scripts": {
    "build": "vext build",
    "start": "vext start",
    "start:sg-sit": "vext start --config sg-sit",
    "start:us-uat": "vext start --config us-uat",
    "deploy:assets:sg-sit": "vext deploy assets --config sg-sit --dry-run"
  }
}

#vext stop — stop the service

Stop a running Cluster mode service. Send a stop signal by reading the PID file.

#Usage

vext stop [options]

vext stop does not support positional arguments. --pid-file must be followed by a non-option path value.

#Options

#Example

# graceful stop
vext stop

# Specify PID file
vext stop --pid-file /var/run/myapp.pid

#vext reload — rolling restart

Triggers a zero-downtime rolling restart in Cluster mode. Restart Worker processes one by one to ensure that the service is always available.

#Usage

vext reload [options]

vext reload does not support positional arguments. --pid-file must be followed by a non-option path value.

#Options

#Example

# Rolling restart after deploying new version
vext build
vext reload

#Rolling restart process

1. Send the SIGUSR2 signal to the Master process
2. Master restarts Workers one by one:
   a. Start a new Worker
   b. Wait for the new Worker to be ready
   c. Gracefully shut down the old Worker
   d. Repeat until all Workers are updated
3. There is always a Worker to process requests throughout the entire process, with zero downtime.

#vext status — View running status

View the service running status in Cluster mode, including information about the Master process and each Worker process.

#Usage

vext status [options]

vext status does not support positional arguments. Value options such as --pid-file, --port, and --host must be followed by a non-option value.

#Options

#Example

vext status
vext status --port 8080

#Output example

VextJS Cluster Status

Master PID: 12345
Workers: 4/4 running
Uptime: 2d 5h 32m

  PID State CPU Memory Requests
  12346 online 2.1% 48 MB 125,432
  12347 online 1.8% 52 MB 124,891
  12348 online 2.3% 47 MB 126,003
  12349 online 1.9% 50 MB 125,720

#Global options

All commands support the following global options:

# View version
vext --version
# Output: vextjs v2.0.0

# View help
vext --help

#Recommended package.json script

{
  "name": "my-app",
  "type": "module",
  "scripts": {
    "dev": "vext dev",
    "build": "vext build",
    "start": "vext start",
    "stop": "vext stop",
    "reload": "vext reload",
    "status": "vext status",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:cov": "vitest run --coverage",
    "typecheck": "tsc --noEmit"
  }
}

#FAQ

#vext start reports error "dist/ not found"

You need to execute vext build first to compile the TypeScript code. vext start loads compiled JavaScript files from dist/.

If frontend is enabled, vext start also requires dist/client/index.html.

#Should I use vext dev or vext start when developing?

Daily development uses vext dev, which directly loads TypeScript files under src/ and supports hot reloading without manual compilation. vext start is used in production environments.

#How to specify Node.js version?

VextJS requires Node.js >= 20.19.0. It is recommended to create a .node-version or .nvmrc file in the project root directory to specify the version:

echo "22" > .node-version

#vext stop / vext reload / vext status not working?

These three commands are only available in Cluster mode. Make sure cluster.enabled: true is enabled in the configuration or the VEXT_CLUSTER=1 environment variable is used, and the service is started via vext start.

#Next step

• Learn the details of the three-layer strategy of Hot Reload
• Configure the Frontend guide
• Learn the complete configuration of Cluster multi-process
• View options such as ports and logs in Configuration
• Explore the conventions of Project Structure