# Youwei Vue - Installation and Deployment Guide

## Overview

Youwei Vue is a modern web application built with Vue 3, TypeScript, and Vite. This document provides comprehensive instructions for installing, configuring, and deploying the application.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Environment Setup](#environment-setup)
3. [Installation](#installation)
4. [Development](#development)
5. [Building for Production](#building-for-production)
6. [Deployment](#deployment)
7. [Troubleshooting](#troubleshooting)

---

## Prerequisites

Before you begin, ensure your system meets the following requirements:

### System Requirements

| Component | Minimum Version |
|-----------|-----------------|
| Node.js   | ^20.19.0 or >=22.12.0 |
| npm       | 10.x or higher  |
| Git       | 2.x or higher   |

### Supported Operating Systems

- Windows 10/11
- macOS 10.15+
- Linux (Ubuntu 20.04+, CentOS 8+, Debian 10+)

### Recommended IDE

- [VS Code](https://code.visualstudio.com/) with [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) extension
- Disable Vetur extension if previously installed

---

## Environment Setup

### 1. Install Node.js

Download and install Node.js from the official website:

```bash
# Using nvm (recommended)
nvm install 20
nvm use 20

# Or download directly from
# https://nodejs.org/
```

Verify installation:

```bash
node --version  # Should show v20.19.0 or higher
npm --version   # Should show 10.x or higher
```

### 2. Install Git

```bash
# Windows: Download from https://git-scm.com/download/win
# macOS: brew install git
# Linux: sudo apt-get install git
```

---

## Installation

### 1. Clone the Repository

```bash
git clone <repository-url>
cd youwei-vue
```

### 2. Install Dependencies

```bash
npm install
```

This command installs all required dependencies including:
- Vue 3.5.29
- Vue Router 5.0.3
- Pinia 3.0.4
- TypeScript 5.9.3
- Vite 7.3.1
- ESLint & Oxlint for code quality

---

## Development

### Start Development Server

```bash
npm run dev
```

The development server will start at `http://localhost:5173` by default.

### Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Type-check and build for production |
| `npm run build-only` | Build without type checking |
| `npm run type-check` | Run TypeScript type checking |
| `npm run preview` | Preview production build locally |
| `npm run lint` | Run all linters (ESLint + Oxlint) |
| `npm run lint:eslint` | Run ESLint with auto-fix |
| `npm run lint:oxlint` | Run Oxlint with auto-fix |

### Development Features

- **Hot Module Replacement (HMR)**: Changes are reflected instantly
- **Vue DevTools**: Integrated via `vite-plugin-vue-devtools`
- **Path Aliases**: Use `@/` to reference `src/` directory
- **TypeScript Support**: Full type checking with `vue-tsc`

---

## Building for Production

### Production Build

```bash
npm run build
```

This command:
1. Runs TypeScript type checking
2. Compiles and minifies the application
3. Outputs to `dist/` directory

### Preview Production Build

```bash
npm run preview
```

This serves the production build locally for testing before deployment.

### Build Output Structure

```
dist/
├── assets/
│   ├── index-xxx.js
│   ├── index-xxx.css
│   └── ...
├── favicon.ico
├── index.html
└── logo.png
```

---

## Deployment

### Static Hosting

The `dist/` folder contains static files that can be deployed to any static hosting service.

#### Option 1: Nginx

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/youwei-vue/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

#### Option 2: Apache

```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
</IfModule>
```

#### Option 3: Cloud Platforms

- **Vercel**: Connect Git repository for automatic deployments
- **Netlify**: Drag and drop `dist/` folder or connect Git
- **AWS S3 + CloudFront**: Upload `dist/` contents to S3 bucket
- **GitHub Pages**: Use GitHub Actions for CI/CD

### Docker Deployment

Create a `Dockerfile`:

```dockerfile
# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

Build and run:

```bash
docker build -t youwei-vue .
docker run -p 80:80 youwei-vue
```

---

## Troubleshooting

### Common Issues

#### 1. Node Version Mismatch

**Error**: `engines.node` incompatible

**Solution**:
```bash
nvm install 20
nvm use 20
```

#### 2. Port Already in Use

**Error**: `Port 5173 is already in use`

**Solution**:
```bash
# Kill process on port 5173
npx kill-port 5173

# Or use a different port
npm run dev -- --port 3000
```

#### 3. TypeScript Errors

**Error**: Type checking fails

**Solution**:
```bash
# Run type check separately
npm run type-check

# Check for missing types
npm install --save-dev @types/node
```

#### 4. Build Failures

**Solution**:
```bash
# Clean and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build
```

### Browser Compatibility

- Chrome/Edge 88+
- Firefox 78+
- Safari 14+

For older browsers, consider adding polyfills to your Vite configuration.

---

## Additional Resources

- [Vue 3 Documentation](https://vuejs.org/)
- [Vite Documentation](https://vitejs.dev/)
- [TypeScript Documentation](https://www.typescriptlang.org/)
- [Pinia Documentation](https://pinia.vuejs.org/)

---

## Support

For issues and feature requests, please use the project's issue tracker.