vitesse-dependency-scripts/add-to-catalog.md

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

# Add Missing Dependencies to Catalog

## Option 1: Add to Catalog (Recommended for Workspace)

This is the proper way to add dependencies when using pnpm catalogs. It ensures version consistency across your workspace.

### Step 1: Update `pnpm-workspace.yaml`

Add these lines to the appropriate catalog sections:

#### Under `frontend:` catalog (production dependencies):
```yaml
  frontend:
    '@unhead/vue': ^2.0.2
    '@unocss/reset': ^66.1.0-beta.7
    '@vueuse/core': ^13.0.0
    nprogress: ^0.2.0
    pinia: ^3.0.1
    vue: ^3.5.13
    vue-i18n: ^11.1.2
    vue-router: ^4.5.0
    # Add new frontend dependencies below:
    '@casl/ability': ^6.7.3
    '@casl/vue': ^2.2.2
    '@fortawesome/fontawesome-svg-core': ^6.7.2
    '@vuelidate/core': ^2.0.3
    '@vuelidate/validators': ^2.0.4
    '@vueuse/head': ^1.3.1
    '@vueuse/integrations': ^9.13.0
    axios: ^1.7.9
    'browser-image-compression': ^2.0.2
    'chart.js': ^4.4.9
    'element-plus': ^2.11.2
    luxon: ^3.5.0
    prismjs: ^1.30.0
    'universal-cookie': ^4.0.4
    'virtual-scroller': ^1.13.1
    'vue-axios': ^3.5.2
    'vue-chartjs': ^5.3.2
    'vue-demi': ^0.13.11
    vuedraggable: ^4.1.0
    'vue-virtual-scroller': 2.0.0-beta.8
```

#### Under `dev:` catalog (icon packages):
```yaml
  dev:
    # ... existing dev dependencies ...
    '@iconify-json/ic': ^1.2.2
    '@iconify-json/mdi': ^1.2.3
```

#### Under `build:` catalog (build tools):
```yaml
  build:
    # ... existing build dependencies ...
    critters: ^0.0.16
    'cross-env': ^7.0.3
    sass: ^1.85.0
    'ts-node': ^10.9.2
    'unplugin-element-plus': ^0.8.0
    'vite-plugin-pages': ^0.29.1
    'vite-plugin-vue-component-preview': ^1.1.7
```

#### Under `types:` catalog (TypeScript types):
```yaml
  types:
    '@types/markdown-it-link-attributes': ^3.0.5
    '@types/nprogress': ^0.2.3
    # Add new type definitions below:
    '@types/luxon': ^3.4.2
    '@types/node': ^24.0.10
    '@types/prismjs': ^1.26.5
```

### Step 2: Update `package.json` to use catalog references

In your `package.json`, add these entries:

#### Under `dependencies:`:
```json
{
  "dependencies": {
    "@casl/ability": "catalog:frontend",
    "@casl/vue": "catalog:frontend",
    "@fortawesome/fontawesome-svg-core": "catalog:frontend",
    "@vuelidate/core": "catalog:frontend",
    "@vuelidate/validators": "catalog:frontend",
    "@vueuse/head": "catalog:frontend",
    "@vueuse/integrations": "catalog:frontend",
    "axios": "catalog:frontend",
    "browser-image-compression": "catalog:frontend",
    "chart.js": "catalog:frontend",
    "element-plus": "catalog:frontend",
    "luxon": "catalog:frontend",
    "prismjs": "catalog:frontend",
    "universal-cookie": "catalog:frontend",
    "virtual-scroller": "catalog:frontend",
    "vue-axios": "catalog:frontend",
    "vue-chartjs": "catalog:frontend",
    "vue-demi": "catalog:frontend",
    "vuedraggable": "catalog:frontend",
    "vue-virtual-scroller": "catalog:frontend"
  }
}
```

#### Under `devDependencies:`:
```json
{
  "devDependencies": {
    "@iconify-json/ic": "catalog:dev",
    "@iconify-json/mdi": "catalog:dev",
    "@types/luxon": "catalog:types",
    "@types/node": "catalog:types",
    "@types/prismjs": "catalog:types",
    "critters": "catalog:build",
    "cross-env": "catalog:build",
    "sass": "catalog:build",
    "ts-node": "catalog:build",
    "unplugin-element-plus": "catalog:build",
    "vite-plugin-pages": "catalog:build",
    "vite-plugin-vue-component-preview": "catalog:build"
  }
}
```

### Step 3: Install dependencies

After updating both files, run:

```bash
pnpm install
```

---

## Option 2: Quick Install Without Catalog (Direct Install)

If you want to quickly add dependencies without catalog management:

```bash
# Use the existing install-missing-deps.sh script
./install-missing-deps.sh
```

This will add dependencies directly to `package.json` with specific versions (not using catalog).

---

## Which Option to Choose?

### Use **Option 1 (Catalog)** if:
- ✅ You want consistent versioning across workspace packages
- ✅ You're managing a monorepo or multi-package workspace
- ✅ You want centralized dependency management
- ✅ You're following your existing project pattern

### Use **Option 2 (Direct)** if:
- ✅ You want to quickly test dependencies
- ✅ This is a single-package project
- ✅ You don't need workspace-wide version consistency

---

## Note on Special Packages

Some packages need special handling:

- **`@nestjs/mapped-types`** - This is typically a backend dependency. Are you sure you need it in the frontend?
- **`nestjs-paginate`** - Also a backend dependency. Consider if this is needed in the UI.
- **`vue-virtual-scroller`** - Version `2.0.0-beta.8` is still in beta. Consider if you want the latest stable instead.