vitesse-dependency-scripts/AUTO-UPDATE-README.md

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

# Auto Update Scripts

Automated scripts to help you manage dependencies in your pnpm catalog workspace.

---

## 🆕 Create New Project (NEW!)

**Want to start a fresh project with all dependencies pre-configured?**

```bash
node create-vitesse-project.js my-awesome-app
cd my-awesome-app
pnpm dev
```

This creates a new [Vitesse](https://github.com/antfu-collective/vitesse) project (Vite + Vue 3 template) with all your custom dependencies automatically configured! 

📖 [See full documentation](./CREATE-PROJECT-README.md)

---

## 🔄 Update Existing Project

## 🚀 Quick Start (Recommended)

### **Option 1: Complete Auto Update (One Command)**

Updates everything automatically - workspace file, package.json, and installs:

```bash
chmod +x auto-update-full.js
node auto-update-full.js
```

**What it does:**
1. ✅ Fetches latest versions from npm
2. ✅ Updates `pnpm-workspace.yaml` with versions
3. ✅ Updates `package.json` with catalog references
4. ✅ Runs `pnpm install` automatically
5. ✅ Creates backups before modifying files

**This is the easiest option!** Just run it and you're done.

---

## 📋 Alternative Option

### **Option 2: Update Workspace Only**

Only updates `pnpm-workspace.yaml` with latest versions:

```bash
node auto-update-catalog.js
```

Then you can manually update `package.json` with catalog references, or just use Option 1 which does everything.

---

## 📁 Files Overview

| File | Purpose | Best For |
|------|---------|----------|
| `create-vitesse-project.js` | 🆕 Create new Vitesse project | **New projects** |
| `auto-update-full.js` | ⭐ Complete automation | **Existing projects** |
| `auto-update-catalog.js` | Updates workspace only | Manual control |
| `install-missing-deps.sh` | Direct install (no catalog) | Quick testing |
| `CREATE-PROJECT-README.md` | New project guide | Learning |
| `AUTO-UPDATE-README.md` | Scripts documentation | Reference |
| `catalog-additions.yaml` | Copy-paste reference | Manual editing |
| `add-to-catalog.md` | Full documentation | Learning |

---

## 🎯 Which Script Should I Use?

### Use `auto-update-full.js` if:
- ✅ You want everything done automatically
- ✅ You're okay with the script modifying both files
- ✅ You want the latest versions installed immediately

### Use `auto-update-catalog.js` if:
- ✅ You want to review changes before updating package.json
- ✅ You want more control over the process
- ✅ You'll manually edit package.json later

### Use `install-missing-deps.sh` if:
- ✅ You DON'T want to use the catalog system
- ✅ You want dependencies directly in package.json
- ✅ You're just testing packages quickly

---

## 🔧 How It Works

### Step-by-Step Process:

1. **Fetch Versions**
   - Runs `pnpm view <package> version` for each package
   - Gets the latest stable version from npm

2. **Update pnpm-workspace.yaml**
   - Finds the correct catalog section (frontend, dev, build, types)
   - Adds package with version: `'package-name': ^X.Y.Z`
   - Skips packages that already exist

3. **Update package.json**
   - Adds catalog references: `"package-name": "catalog:frontend"`
   - Places them in `dependencies` or `devDependencies`

4. **Install**
   - Runs `pnpm install` to resolve and install everything

---

## 📦 Dependency Mapping

The scripts organize packages into these catalogs:

### **frontend** → `dependencies`
- @casl/ability, @casl/vue
- @vuelidate/core, @vuelidate/validators
- element-plus, axios
- chart.js, vue-chartjs
- And more UI/frontend packages

### **dev** → `devDependencies`
- @iconify-json/ic
- @iconify-json/mdi

### **build** → `devDependencies`
- sass, critters, cross-env
- unplugin-element-plus
- vite-plugin-pages
- vite-plugin-vue-component-preview

### **types** → `devDependencies`
- @types/luxon
- @types/node
- @types/prismjs

---

## 🛡️ Safety Features

All scripts create backups:

```
pnpm-workspace.yaml.backup.1697123456789
package.json.backup.1697123456789
```

If something goes wrong, restore with:
```bash
cp pnpm-workspace.yaml.backup.* pnpm-workspace.yaml
cp package.json.backup.* package.json
```

---

## 🔍 Verification

After running, check your files:

```bash
# Check workspace file
cat pnpm-workspace.yaml | grep -A 5 "frontend:"

# Check package.json
cat package.json | grep "catalog:"

# Verify installation
pnpm list element-plus
pnpm list axios
```

---

## ⚠️ Notes

1. **Node.js Required**: The `.js` scripts require Node.js (already available via pnpm)
2. **pnpm Required**: Uses `pnpm view` to fetch versions
3. **Internet Required**: Needs to connect to npm registry
4. **Beta Versions**: `vue-virtual-scroller` uses beta version (2.0.0-beta.8)
5. **Backend Packages**: The list includes `@nestjs/mapped-types` and `nestjs-paginate` which are typically backend packages - consider if you need these in the UI

---

## 🎨 Customization

To add/remove packages, edit the `DEPENDENCIES` object in the `.js` scripts:

```javascript
const DEPENDENCIES = {
  frontend: [
    'your-package-here',
    // ...
  ],
  // ...
};
```

---

## 🆘 Troubleshooting

### "Package not found"
Some packages might not exist or have different names. The script will use `'latest'` as fallback.

### "Catalog not found"
Make sure your `pnpm-workspace.yaml` has the catalog sections: `frontend:`, `dev:`, `build:`, `types:`

### "Permission denied"
Run: `chmod +x <script-name>` to make scripts executable

### "pnpm install failed"
There might be version conflicts. Check the error and manually adjust versions in `pnpm-workspace.yaml`

---

## 📞 Questions?

- See full docs in `add-to-catalog.md`
- See dependency list in `MISSING_DEPENDENCIES.md`
- Check catalog entries in `catalog-additions.yaml`