vitesse-dependency-scripts/README.md

Automated toolkit for managing dependencies with pnpm catalogs in Vue/Vite projects

# 🛠️ Dependency Management Scripts

[![npm version](https://img.shields.io/npm/v/vitesse-dependency-scripts.svg)](https://www.npmjs.com/package/vitesse-dependency-scripts)
[![npm downloads](https://img.shields.io/npm/dm/vitesse-dependency-scripts.svg)](https://www.npmjs.com/package/vitesse-dependency-scripts)
[![license](https://img.shields.io/npm/l/vitesse-dependency-scripts.svg)](./LICENSE)
[![node version](https://img.shields.io/node/v/vitesse-dependency-scripts.svg)](https://nodejs.org)

Automated toolkit for managing dependencies with pnpm catalogs in Vue/Vite projects.

> 📖 **New here?** Check out [QUICK-START.md](./QUICK-START.md) for a one-page cheat sheet!

---

## 📦 Installation

### Using npx (⚡ Zero Installation - EASIEST!)

No installation needed! Run directly with npx:

```bash
# Create a new project instantly
npx vitesse-dependency-scripts my-awesome-app

# That's it! No global install required
```

### From npm (⭐ Recommended for Multiple Projects)

Install globally via npm:

```bash
npm install -g vitesse-dependency-scripts
```

Or using pnpm:

```bash
pnpm add -g vitesse-dependency-scripts
```

That's it! Now use from anywhere:

```bash
vitesse-create my-awesome-app
vitesse-update
vitesse-update-catalog
```

### From Git (Clone & Use)

```bash
# Clone the repository
git clone https://github.com/victorktchong/vitesse-dependency-scripts.git dependency-scripts
cd dependency-scripts

# Make scripts executable
chmod +x *.js *.sh

# Ready to use!
pnpm create my-new-project
```

### Alternative: Link Locally

```bash
# Clone and link globally
git clone https://github.com/victorktchong/vitesse-dependency-scripts.git dependency-scripts
cd dependency-scripts
pnpm link --global

# Now use from anywhere
vitesse-create my-awesome-app
vitesse-update
```

---

## 🚀 Quick Start

### ⚡ Create Project Instantly (RECOMMENDED!)

Create a new project with latest dependencies in **ONE command**:

```bash
# If installed via npm (recommended)
vitesse-create my-awesome-app

# Or using node directly (if cloned from git)
node create-project-instant.js my-awesome-app

# Or using pnpm scripts (if cloned from git)
pnpm create my-awesome-app
```

**This combines everything:**
- ✅ Clones Vitesse template
- ✅ Fetches latest versions from npm
- ✅ Updates workspace catalogs
- ✅ Updates package.json
- ✅ Installs dependencies
- ✅ Ready to code immediately!

### 🆕 Create a New Project (Basic)

```bash
# If installed via npm
vitesse-create my-awesome-app

# Or if cloned from git
node create-vitesse-project.js my-awesome-app
# Or: pnpm create:basic my-awesome-app
```

### 🔄 Update Current Project

```bash
# If installed via npm
vitesse-update

# Or if cloned from git
node auto-update-full.js
# Or: pnpm update
```

---

## 📁 What's Inside

| File | Description |
|------|-------------|
| **📜 Scripts** | |
| `create-project-instant.js` | ⚡ **ALL-IN-ONE**: Create + Update + Install (RECOMMENDED) |
| `create-vitesse-project.js` | Create new Vitesse project with all dependencies |
| `auto-update-full.js` | Update existing project's catalog and package.json |
| `auto-update-catalog.js` | Update only pnpm-workspace.yaml |
| `install-missing-deps.sh` | Direct install (bypasses catalog system) |
| **📖 Documentation** | |
| `README.md` | This file - quick reference |
| `QUICK-START.md` | ⚡ **One-page cheat sheet** - Fastest way to get started! |
| `WHICH-SCRIPT.md` | 🤔 **Which script should I use?** - Decision guide |
| `INSTANT-CREATE-README.md` | ⚡ Guide for instant project creation (NEW!) |
| `SCRIPTS-README.md` | Complete scripts documentation |
| `CREATE-PROJECT-README.md` | Guide for creating new projects |
| `AUTO-UPDATE-README.md` | Guide for updating existing projects |
| `MISSING_DEPENDENCIES.md` | Full list of managed dependencies |
| `add-to-catalog.md` | Manual catalog management guide |
| **📋 Reference** | |
| `catalog-additions.yaml` | Copy-paste YAML entries |

---

## 💡 Common Use Cases

### Scenario 1: Starting Fresh (⚡ Instant Way - RECOMMENDED)
```bash
# From project root
cd dependency-scripts
node create-project-instant.js my-new-project

# Project will be created in parent directory with LATEST versions
cd ../my-new-project
pnpm dev
```

### Scenario 1b: Starting Fresh (Basic Way)
```bash
# From project root
cd dependency-scripts
node create-vitesse-project.js my-new-project

# Project will be created in parent directory
cd ../my-new-project
pnpm dev
```

### Scenario 2: Adding Dependencies to This Project
```bash
# From project root
cd dependency-scripts
node auto-update-full.js

# Returns to parent directory and updates it
cd ..
pnpm dev
```

### Scenario 3: Quick Test Install
```bash
cd dependency-scripts
./install-missing-deps.sh
```

---

## 📦 Managed Dependencies

These scripts automatically manage **35+ packages**:

### Frontend (22 packages)
- **Auth**: @casl/ability, @casl/vue
- **Forms**: @vuelidate/core, @vuelidate/validators  
- **UI**: element-plus, @fortawesome/fontawesome-svg-core
- **HTTP**: axios, vue-axios
- **Charts**: chart.js, vue-chartjs
- **Utils**: luxon, prismjs, vuedraggable, vue-virtual-scroller
- And more...

### Dev Tools (13 packages)
- **Icons**: @iconify-json/ic, @iconify-json/mdi
- **Build**: sass, critters, cross-env, ts-node
- **Vite Plugins**: unplugin-element-plus, vite-plugin-pages
- **Types**: @types/luxon, @types/node, @types/prismjs

---

## 🎯 Which Script to Use?

```
┌─────────────────────────────────────────┐
│  Do you have an existing project?      │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
       YES                 NO
        │                   │
        ▼                   ▼
┌───────────────┐   ┌─────────────────────┐
│ auto-update-  │   │ create-vitesse-     │
│ full.js       │   │ project.js          │
│               │   │                     │
│ Updates your  │   │ Creates new project │
│ current       │   │ from Vitesse        │
│ project       │   │ template            │
└───────────────┘   └─────────────────────┘
```

---

## 📚 Full Documentation

- **[WHICH-SCRIPT.md](./WHICH-SCRIPT.md)** - 🤔 Which script should I use? (Decision guide)
- **[INSTANT-CREATE-README.md](./INSTANT-CREATE-README.md)** - ⚡ Instant project creation guide (NEW!)
- **[SCRIPTS-README.md](./SCRIPTS-README.md)** - Complete overview of all scripts
- **[CREATE-PROJECT-README.md](./CREATE-PROJECT-README.md)** - Detailed new project guide
- **[AUTO-UPDATE-README.md](./AUTO-UPDATE-README.md)** - Detailed update guide
- **[MISSING_DEPENDENCIES.md](./MISSING_DEPENDENCIES.md)** - All dependencies explained

---

## ⚡ Quick Command Reference

### Using npx (No Installation Required)

```bash
# ⭐ Create new project INSTANTLY with latest deps
npx vitesse-dependency-scripts my-app

# Always runs the latest version from npm
npx vitesse-dependency-scripts@latest my-app
```

### If Installed via npm (Recommended)

```bash
# ⭐ Create new project INSTANTLY with latest deps
vitesse-create my-app

# Update existing project (complete)
vitesse-update

# Update workspace catalog only
vitesse-update-catalog
```

### If Cloned from Git

```bash
# Create new project INSTANTLY
pnpm create my-app
# or: node create-project-instant.js my-app

# Create new project (basic)
pnpm create:basic my-app
# or: node create-vitesse-project.js my-app

# Update current project (complete)
pnpm update
# or: node auto-update-full.js

# Update workspace only
pnpm update:catalog
# or: node auto-update-catalog.js

# Direct install (no catalog)
pnpm install:direct
# or: ./install-missing-deps.sh
```

---

## 🔧 Requirements

- **Node.js** >= 14.18
- **pnpm** (install with `npm install -g pnpm`)
- **Internet connection** (for fetching package versions)
- **Git** (for cloning repositories)

### First Time Setup

After cloning this repository:

```bash
# Make scripts executable
chmod +x *.js *.sh

# Verify installation
node create-project-instant.js --help
```

---

## ✨ Features

- ✅ **Automatic version fetching** from npm
- ✅ **ES Module support** (works with `"type": "module"`)
- ✅ **Safe YAML parsing** (preserves structure)
- ✅ **Backup creation** (never lose your work)
- ✅ **Zero external dependencies** (pure Node.js)
- ✅ **Colored console output** (easy to read)
- ✅ **Error handling** (graceful failures)

---

## 🎓 Learn More

### About pnpm Catalogs
These scripts use [pnpm catalogs](https://pnpm.io/catalogs) for centralized version management:

```yaml
# pnpm-workspace.yaml
catalogs:
  frontend:
    axios: ^1.7.9
    element-plus: ^2.11.2
```

```json
// package.json
{
  "dependencies": {
    "axios": "catalog:frontend",
    "element-plus": "catalog:frontend"
  }
}
```

### About Vitesse
[Vitesse](https://github.com/antfu-collective/vitesse) is an opinionated Vite + Vue 3 starter template with:
- File-based routing
- Auto-import components
- UnoCSS
- TypeScript
- PWA support
- And much more!

---

## 🆘 Troubleshooting

### Script won't run
```bash
# Make sure you're in the dependency-scripts folder
cd dependency-scripts

# Make scripts executable (if needed)
chmod +x *.js *.sh
```

### "Cannot find module"
```bash
# Scripts use ES modules, make sure parent package.json has:
# "type": "module"
```

### "pnpm not found"
```bash
npm install -g pnpm
```

---

## 🤝 Contributing

Found a bug or want to add a feature?

1. Edit the scripts in this folder
2. Test your changes
3. Update the relevant documentation
4. Share with the team!

---

## 📞 Questions?

**Not sure which script to use?** → [WHICH-SCRIPT.md](./WHICH-SCRIPT.md) 🤔

Check the detailed documentation:
- [INSTANT-CREATE-README.md](./INSTANT-CREATE-README.md) for instant project creation ⚡
- [SCRIPTS-README.md](./SCRIPTS-README.md) for complete reference
- [CREATE-PROJECT-README.md](./CREATE-PROJECT-README.md) for new projects
- [AUTO-UPDATE-README.md](./AUTO-UPDATE-README.md) for updates

---

**Ready to get started?** 🚀

### Option 1: Use npx (Zero Installation! ⚡)

```bash
# Create your project immediately - no installation needed!
npx vitesse-dependency-scripts my-awesome-app
```

**That's it!** One command creates your project with the latest versions of all dependencies! ⚡

### Option 2: Install from npm

```bash
# Install globally
npm install -g vitesse-dependency-scripts

# Create your first project
vitesse-create my-awesome-app
```

### Option 3: Install from Git

```bash
git clone https://github.com/victorktchong/vitesse-dependency-scripts.git dependency-scripts
cd dependency-scripts
./setup.sh
pnpm create my-awesome-app
```

---

## 🌐 Using from Git

Once you've cloned this repository, you can:

1. **Use locally**: Run scripts from the `dependency-scripts` folder
2. **Link globally**: Use `pnpm link --global` to access commands anywhere
3. **Share**: Others can clone and use immediately with zero setup

### Example Workflow

```bash
# Team member clones the repo
git clone <your-repo-url> dependency-scripts
cd dependency-scripts

# Immediately create a new project
pnpm create awesome-project

# Or update an existing project
cd ../existing-project
../dependency-scripts/auto-update-full.js
```