VUP

English

简体中文

English

简体中文

Appearance

Getting Started ​

This guide will help you quickly get started with VUP and create your first project.

Prerequisites ​

Before starting, please ensure you have the following installed:

  • Node.js (version 22.0.0 or higher)
  • pnpm (version 10.0.0 or higher)

Install Node.js ​

It's recommended to use nvm (Node Version Manager) to manage Node.js versions:

bash
# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 22
nvm install 22
nvm use 22

# Windows users can use nvm-windows
# Download: https://github.com/coreybutler/nvm-windows/releases

Or download directly from the Node.js website.

Install pnpm ​

bash
# Install using npm
npm install -g pnpm

# Or use Homebrew (macOS)
brew install pnpm

# Or use standalone installation script
curl -fsSL https://get.pnpm.io/install.sh | sh -

Verify Installation ​

You can check the versions with the following commands:

bash
node --version  # Should show v22.x.x or higher
pnpm --version  # Should show 10.x.x or higher

Installation ​

bash
# Use directly without installation
npx vup-cli --version
npx vup-cli init my-project

Global Installation ​

bash
# Install VUP CLI globally
npm install -g vup-cli

# Or use pnpm
pnpm add -g vup-cli

Verify Installation ​

bash
# If using npx
npx vup-cli --version

# If global installation successful
vup --version

Troubleshooting Installation Issues ​

If the vup command is not available after global installation, try the following solutions:

bash
# Use npx directly, no global installation needed
npx vup-cli init my-project
npx vup-cli add my-app

Solution 2: Reinstall ​

bash
# Uninstall and reinstall
npm uninstall -g vup-cli
npm install -g vup-cli

# Or use pnpm
pnpm remove -g vup-cli
pnpm add -g vup-cli

Note: With the latest version, bin links are created automatically during installation. If you still encounter issues, using npx is the most reliable approach.

Create New Project ​

1. Initialize Project ​

bash
# Using npx (recommended)
npx vup-cli init my-project

# Or using globally installed command
vup init my-project

# Enter project directory
cd my-project

2. Add Applications ​

bash
# Using npx (recommended)
npx vup-cli add my-vue-app
npx vup-cli add my-api

# Or using globally installed command
vup add my-vue-app
vup add my-api

You will be prompted to select the template type:

  • Vue SPA
  • Qiankun
  • Nuxt 4
  • VitePress
  • NestJS
  • UniApp
  • Capacitor
  • WXT
  • Electron
  • Components
  • Package
  • CLI

3. Install Dependencies ​

bash
# Install all dependencies
pnpm install

4. Add Packages (Optional) ​

If you need to use packages, you can use the vup use command:

bash
# Using npx (recommended)
npx vup-cli use my-package

# Or using globally installed command
vup use my-package

You will be prompted to select the package type:

  • @vup/ui - UI component library
  • @vup/ui-mobile - Mobile UI wrapper
  • @vup/http - Shared HTTP client utilities
  • @vup/mock - Shared mock handlers and bootstrap
  • @vup/pwa - Shared PWA preset and runtime helpers
  • @vup/iconfont - Iconfont icon component
  • @vup/richeditor - Rich text editor
  • @vup/nest-upload - NestJS upload module

For isolated capability demos (such as mock/pwa/qiankun/ui), refer to the vup example command instead of adding them as packages.

5. Add Examples (Optional) ​

If you need capability example projects, use vup example:

bash
# Using npx (recommended)
npx vup-cli example my-example

# Or using globally installed command
vup example my-example

Examples will be added under <projectRoot>/examples/<exampleName>.

6. Start Development ​

bash
# Start all applications
pnpm dev:all

# Or start specific application
pnpm --filter my-vue-app dev

The development server will start, and the port number will be displayed in the terminal. Preset ports (examples):

  • Vue application: http://localhost:9301
  • NestJS API: http://localhost:9310

Project Structure ​

VUP adopts a Monorepo architecture. The structure after creating a project is as follows:

Initial Project Structure ​

bash
vup init my-project

The basic structure after creation:

my-project/
├── apps/                          # Applications directory (initially empty)
├── _shared/                       # Shared resources
│   ├── assets/                    # Shared static resources
│   └── styles/                    # Shared styles
├── .github/                       # GitHub configuration
├── .husky/                        # Git hooks configuration
├── .vercelignore                  # Vercel ignore configuration
├── .vscode/                       # VSCode configuration
├── package.json                   # Root project configuration
├── pnpm-workspace.yaml           # pnpm workspace configuration
├── tsconfig.json                  # TypeScript configuration
├── .template.config.json          # Template configuration
├── eslint.config.js               # ESLint configuration
├── prettier.config.js             # Prettier configuration
├── postcss.config.js              # PostCSS configuration
├── vercel.json                    # Vercel deployment configuration
├── CHANGELOG.md                   # Changelog
└── README.md                      # Project documentation

After Adding Applications ​

bash
vup add my-vue-app    # Add application, system will prompt to select template type
vup add my-api        # Add application, system will prompt to select template type

Structure after adding applications:

my-project/
├── apps/                          # Applications directory
│   ├── my-vue-app/                # Vue SPA application
│   └── my-api/                    # NestJS backend
├── _shared/                       # Shared resources
│   ├── assets/                    # Shared static resources
│   └── styles/                    # Shared styles
└── Configuration files...

Development Workflow ​

Daily Development ​

1. Start Development Server ​

bash
# Start specific application
pnpm --filter <app-name> dev

# Example
pnpm --filter my-vue-app dev

Start the development server with hot module replacement (HMR).

2. Code Linting ​

bash
# Lint specific application
pnpm --filter <app-name> lint

# Auto-fix ESLint errors
pnpm --filter <app-name> lint:fix

# Lint all applications
pnpm lint:all

# Fix all applications
pnpm lint:fix:all

3. Code Formatting ​

bash
# Format specific application
pnpm --filter <app-name> format

# Check formatting
pnpm --filter <app-name> format:check

# Format all applications
pnpm format:all

# Check formatting for all applications
pnpm format:check:all

4. Type Checking ​

bash
# TypeScript type checking
pnpm --filter <app-name> type-check

# Check all applications
pnpm type-check:all

5. Build Project ​

bash
# Build specific application
pnpm --filter <app-name> build

# Build all applications
pnpm build:all

Built files are usually output to .output or dist directory (depending on the template type).

6. Preview Production Build ​

bash
# Preview specific application
pnpm --filter <app-name> preview

Preview the production build locally.

Batch Operations ​

VUP provides batch operation commands for managing multiple applications simultaneously:

bash
# Start all applications
pnpm dev:all

# Build all applications
pnpm build:all

# Lint all applications
pnpm lint:all

# Format all applications
pnpm format:all

# Type check all applications
pnpm type-check:all

Environment Variables ​

Create Environment Variable File ​

bash
# Copy example file
cp apps/<app-name>/.env.example apps/<app-name>/.env.local

Vite Environment Variable Rules ​

  • Client variables: Must start with VITE_
  • Server variables: Can be named arbitrarily (e.g., NODE_ENV)

Variable Priority (from high to low) ​

  1. .env.local (local environment, not committed to Git)
  2. .env.development (development environment)
  3. .env.production (production environment)
  4. .env (common environment)

Common Configuration Example ​

bash
# .env.local
VITE_APP_TITLE=My Application
VITE_APP_DESCRIPTION=Application description
VITE_API_BASE=http://localhost:3000/api
VITE_ENABLE_MOCK=true
VITE_ENABLE_DEVTOOLS=true

Add Applications to Existing Project ​

If you already have a project, you can add new applications:

bash
# Using npx (recommended)
npx vup-cli add my-app
npx vup-cli add my-app --path /custom/path
npx vup-cli add my-app --force
npx vup-cli add -l

# Or using globally installed command
vup add my-app
vup add my-app --path /custom/path
vup add my-app --force
vup add -l

Command Options ​

  • --path <path> - Specify project path (defaults to current directory)
  • --force - Force overwrite existing application
  • -l, --list - List available app templates

Add Packages to Existing Project ​

bash
# Using npx (recommended)
npx vup-cli use my-package
npx vup-cli use my-package --path /custom/path
npx vup-cli use my-package --force
npx vup-cli use -l

# Or using globally installed command
vup use my-package
vup use my-package --path /custom/path
vup use my-package --force
vup use -l

Packages will be added to the packages/ directory.

Add Examples to Existing Project ​

bash
# Using npx (recommended)
npx vup-cli example my-example
npx vup-cli example my-example --path /custom/path
npx vup-cli example my-example --force
npx vup-cli example -l

# Or using globally installed command
vup example my-example
vup example my-example --path /custom/path
vup example my-example --force
vup example -l

Examples will be added to the examples/ directory.

Language Settings ​

Set Language ​

bash
# Using npx
npx vup-cli language --current
npx vup-cli language --reset

# Or using globally installed command
vup language --current
vup language --reset

Language Support ​

VUP supports multiple languages:

  • English (en) - Default language
  • Chinese (zh) - Chinese language support

Common Issues ​

Port Conflict ​

If the default port is occupied, you can modify the port number in the application's configuration file:

typescript
// vite.config.js
export default defineConfig({
  server: {
    port: 9302, // Change to another port
  },
});

Dependency Installation Failed ​

If you encounter dependency installation issues, try:

bash
# Clear cache
pnpm store prune

# Delete node_modules and lock file, then reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

Template Download Failed ​

If template download fails, try checking network/proxy settings and rerun your command:

bash
vup add my-app

Windows Path Issues ​

On Windows, if you encounter path-related issues, ensure you use the correct path separators, or use Git Bash or WSL.

Next Steps ​

Now that you've successfully created your first VUP project, you can:

  • 📖 Learn What is VUP - Deep dive into VUP's core philosophy and features
  • 🤖 Learn AI Governance Model - Understand how .agent rules and skills keep AI delivery stable and auditable
  • 🎯 Explore Template Documentation - Learn detailed usage for different project types
  • 📦 Check Packages Overview - Learn how to incrementally add post-bootstrap capabilities with vup use
  • 🧪 Browse Examples Overview - Reference focused integration examples added with vup example
  • 🎨 Learn Theme System - Learn how to configure and use themes
  • 🛠️ Configure Development Tools - Improve development efficiency and code quality
  • 🚀 Set up Deployment - Learn how to deploy your applications
  • 📝 Manage Version and Changelog - Use release-it to manage version releases

Get Help ​

Copyright © 2025 VUP-CLI