vitesse-dependency-scripts/SCRIPTS-README.md

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

# 🛠️ Dependency Management Scripts

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

---

## 🎯 Quick Reference

### 🆕 Starting a New Project?

```bash
node create-vitesse-project.js my-app
```

Creates a new [Vitesse](https://github.com/antfu-collective/vitesse) project with all dependencies pre-configured.

📖 **[Full Guide →](./CREATE-PROJECT-README.md)**

---

### 🔄 Updating an Existing Project?

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

Adds missing dependencies to your current project's catalog and installs them.

📖 **[Full Guide →](./AUTO-UPDATE-README.md)**

---

## 📦 What Do These Scripts Do?

All scripts automatically manage these dependencies:

### 🎨 Frontend (22 packages)
- **Auth**: CASL ability & Vue integration
- **Forms**: Vuelidate validation
- **UI**: Element Plus, FontAwesome icons
- **Charts**: Chart.js with Vue wrapper
- **HTTP**: Axios with Vue integration
- **Utils**: Luxon (dates), Prismjs (syntax), Vuedraggable, Vue Virtual Scroller
- **And more...**

### 🔧 Dev Tools (13 packages)
- **Icons**: Material icons, Material Design icons
- **Build**: Sass, Critters, Cross-env, TS-Node
- **Vite Plugins**: Element Plus, Pages, Component Preview
- **Types**: Luxon, Node, Prismjs

---

## 🚀 All Available Scripts

| Script | Use Case | Command |
|--------|----------|---------|
| **create-vitesse-project.js** 🆕 | Create new project from scratch | `node create-vitesse-project.js my-app` |
| **auto-update-full.js** ⭐ | Update existing project (complete) | `node auto-update-full.js` |
| **auto-update-catalog.js** | Update workspace file only | `node auto-update-catalog.js` |
| **install-missing-deps.sh** | Direct install (bypass catalog) | `./install-missing-deps.sh` |

---

## 💡 Common Workflows

### Workflow 1: Brand New Project
```bash
# Create project with Vitesse template + your dependencies
node create-vitesse-project.js my-store

# Navigate and start
cd my-store
pnpm dev
```

### Workflow 2: Add Dependencies to Current Project
```bash
# Add dependencies to existing project
node auto-update-full.js

# Or if you want more control
node auto-update-catalog.js  # Update workspace
# Then manually edit package.json
pnpm install
```

### Workflow 3: Quick Test (No Catalog)
```bash
# Install directly without catalog system
./install-missing-deps.sh
```

---

## 📚 Documentation

- **[CREATE-PROJECT-README.md](./CREATE-PROJECT-README.md)** - Complete guide for creating new projects
- **[AUTO-UPDATE-README.md](./AUTO-UPDATE-README.md)** - Guide for updating existing projects
- **[MISSING_DEPENDENCIES.md](./MISSING_DEPENDENCIES.md)** - Full list of dependencies with descriptions
- **[add-to-catalog.md](./add-to-catalog.md)** - Manual catalog management guide

---

## 🎓 Understanding pnpm Catalogs

### What are Catalogs?

pnpm catalogs let you define package versions centrally in `pnpm-workspace.yaml`:

```yaml
catalogs:
  frontend:
    axios: ^1.7.9
    element-plus: ^2.11.2
```

Then reference them in `package.json`:

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

### Benefits

- ✅ **Version consistency** across multiple packages
- ✅ **Centralized management** - update once, apply everywhere
- ✅ **Better organization** - group related packages
- ✅ **Workspace support** - perfect for monorepos

---

## 🔧 Customization

### Adding Your Own Dependencies

Edit the `CUSTOM_DEPENDENCIES` object in any `.js` script:

```javascript
const CUSTOM_DEPENDENCIES = {
  frontend: [
    'your-package',
    'another-package',
  ],
  dev: [
    '@your/dev-tool',
  ],
};
```

### Changing Catalog Names

Modify the `CATALOG_TO_DEP_TYPE` mapping:

```javascript
const CATALOG_TO_DEP_TYPE = {
  frontend: 'dependencies',
  dev: 'devDependencies',
  yourCatalog: 'dependencies',  // Add custom catalog
};
```

---

## ⚙️ How It Works

### Technology Stack

All scripts use:
- **ES Modules** (import/export) - Compatible with `"type": "module"`
- **Node.js Built-ins** - `fs`, `child_process`, `path`
- **pnpm CLI** - For package version lookups and installation
- **No External Dependencies** - Pure Node.js, no npm packages needed

### Process Flow

1. **Fetch Latest Versions**
   ```bash
   pnpm view <package> version
   ```

2. **Parse & Update YAML**
   - Read `pnpm-workspace.yaml`
   - Find catalog sections
   - Add packages with versions
   - Preserve formatting

3. **Update package.json**
   - Read JSON
   - Add catalog references
   - Write back with formatting

4. **Install**
   ```bash
   pnpm install
   ```

---

## 🐛 Troubleshooting

### Script Errors

**"ReferenceError: require is not defined"**
- ✅ Fixed! Scripts now use ES modules (import/export)

**"Catalog not found"**
- Make sure your `pnpm-workspace.yaml` has the catalog sections
- Check catalog names match exactly (case-sensitive)

**"Failed to fetch version"**
- Script will use 'latest' as fallback
- Check your internet connection
- Some packages might not exist on npm

### Installation Issues

**"bad indentation" in YAML**
- ✅ Fixed! Scripts now properly handle YAML structure
- If it persists, restore from backup and try again

**"Package not found" during pnpm install**
- Some packages in the list might not exist or be renamed
- Edit the dependency list to remove problematic packages

---

## 📊 Project Structure

```
your-project/
├── create-vitesse-project.js      # 🆕 New project creator
├── auto-update-full.js            # ⭐ Complete updater
├── auto-update-catalog.js         # Workspace updater
├── install-missing-deps.sh        # Direct installer
├── CREATE-PROJECT-README.md       # New project docs
├── AUTO-UPDATE-README.md          # Update docs
├── SCRIPTS-README.md              # This file
├── MISSING_DEPENDENCIES.md        # Dependency list
├── add-to-catalog.md              # Manual guide
└── catalog-additions.yaml         # Reference file
```

---

## 🌟 Features

- ✅ **ES Module Support** - Works with `"type": "module"`
- ✅ **Automatic Version Fetching** - Gets latest from npm
- ✅ **YAML Safe Parsing** - Preserves structure and formatting
- ✅ **Backup Creation** - Never lose your work
- ✅ **Colored Output** - Easy to read console messages
- ✅ **Error Handling** - Graceful failures with helpful messages
- ✅ **Zero Dependencies** - Pure Node.js scripts

---

## 🎯 Best Practices

1. **Always Review Changes** - Check backup files before committing
2. **Commit Before Running** - Save your work first
3. **Test After Install** - Run `pnpm dev` to verify everything works
4. **Update Regularly** - Keep dependencies fresh
5. **Customize for Your Needs** - Edit dependency lists as needed

---

## 📞 Getting Help

### Quick Checks

1. Is Node.js >= 14.18 installed?
   ```bash
   node --version
   ```

2. Is pnpm installed?
   ```bash
   pnpm --version
   ```

3. Are you in the project root?
   ```bash
   ls -la  # Should see package.json and pnpm-workspace.yaml
   ```

### Resources

- [pnpm Catalogs Documentation](https://pnpm.io/catalogs)
- [Vitesse Template](https://github.com/antfu-collective/vitesse)
- [Vue 3 Documentation](https://vuejs.org/)
- [Vite Documentation](https://vitejs.dev/)

---

## 🎉 Ready to Go!

Pick your script and get started:

- 🆕 **New project?** → `node create-vitesse-project.js my-app`
- 🔄 **Update existing?** → `node auto-update-full.js`
- ⚡ **Quick test?** → `./install-missing-deps.sh`

Happy coding! 🚀