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:

# 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

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

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

Installation

Recommended: Use npx (No global installation required)

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

Global Installation

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

# Or use pnpm
pnpm add -g vup-cli

# Or use yarn
yarn global add vup-cli

Verify Installation

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

Solution 1: Use npx (Recommended)

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

Solution 2: Reinstall

# 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

# 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

# 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.js
• VitePress
• Nest.js
• UniApp
• Capacitor
• WXT
• Electron
• Components
• CLI

3. Install Dependencies

# Install all dependencies
pnpm install

4. Add Packages (Optional)

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

# 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/iconfont - Iconfont icon component
• @vup/richeditor - Rich text editor
• @vup/nest-upload - NestJS upload module

5. Start Development

# 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

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
├── .vercel/                       # Vercel configuration
├── .vscode/                       # VSCode configuration
├── package.json                   # Root project configuration
├── pnpm-workspace.yaml           # pnpm workspace configuration
├── tsconfig.json                  # TypeScript configuration
├── tailwind.config.js             # Tailwind 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

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/                    # Nest.js backend
├── _shared/                       # Shared resources
│   ├── assets/                    # Shared static resources
│   └── styles/                    # Shared styles
└── Configuration files...

Development Workflow

Daily Development

1. Start Development Server

# 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

# 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

3. Code Formatting

# 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

4. Type Checking

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

# Check all applications
pnpm type-check

5. Build Project

# 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

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

# 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

Environment Variables

Create Environment Variable File

# Copy example file
cp .env.example .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

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

Add Applications to Existing Project

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

# 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

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

Command Options

• --path <path> - Specify project path (defaults to current directory)
• --force - Force overwrite existing application

Add Packages to Existing Project

# 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

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

Packages will be added to the packages/ directory.

Template Management

View Available Templates

# Using npx
npx vup-cli template --list

# Or using globally installed command
vup template --list

Update Templates

# Using npx
npx vup-cli template --update

# Or using globally installed command
vup template --update

Remove Templates

# Using npx
npx vup-cli template --remove

# Or using globally installed command
vup template --remove

Language Settings

Set Language

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

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

Dependency Installation Failed

If you encounter dependency installation issues, try:

# 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, you can manually update templates:

vup template --update

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
• 🎯 Explore Template Documentation - Learn detailed usage for different project types
• 📦 Check Package Documentation - Learn how to use reusable packages
• 🎨 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

• 📚 View Complete Documentation
• 💬 Submit Issue
• 🌟 Star the Project