#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.

#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

#Generated directory structure

my-app/
├── preload/
│ └── README.md # Project-level preload script placeholder description
├── public/
│ └── favicon.svg # Static asset copied into the frontend build
├── src/
│ ├── client/
│ │ ├── App.tsx # React app
│ │ ├── index.html # HTML shell
│ │ ├── main.tsx # Browser entry
│ │ └── styles.css
│ ├── config/
│ │ ├── default.ts #Default configuration (port: 3000)
│ │ ├── development.ts # Development environment coverage
│ │ ├── production.ts # Production environment coverage (port: 3001)
│ │ ├── local.example.ts # Enable local coverage after copying to local.ts
│ │ └── bootstrap.example.ts # Copy to bootstrap.ts and enable startup provider
│ ├── routes/
│ │ └── index.ts # Example routing
│ ├── services/
│ │ └── example.ts # Example service
│ ├── middlewares/
│ │ └── README.md # Custom middleware placeholder description
│ ├── plugins/
│ │ └── README.md # Custom plug-in placeholder description
│ ├── locales/
│ │ └── README.md # i18n language pack placeholder description
│ └── types/
│ └── generated/
│ └── .gitkeep # typegen output directory placeholder (TS project)
├── package.json
├── tsconfig.json
└── .gitignore

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.

If you need to pull remote configuration (such as Nacos/bootstrap database configuration) before the configuration is frozen, you can copy src/config/bootstrap.example.ts to src/config/bootstrap.ts and register the provider through defineBootstrapConfig(). When local coverage is required, src/config/local.example.ts can be copied to src/config/local.ts, which is excluded by .gitignore by default.

#vext dev — development mode

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

#Usage

vext dev [options]

#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

#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

# 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, src/types/generated/index.d.ts, .vext/manifest/services.json and .vext/manifest/routes.json first
• When --typecheck is enabled, execute tsc --noEmit after refreshing the generated / manifest
• Use esbuild for server compilation and frontend bundling
• 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/
• 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
.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]

#Options

#Example

# graceful stop
vext stop

# force stop
vext stop --force

#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]

#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]

#Options

#Example

vext status

#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 v0.3.26

# 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