vitesse-dependency-scripts/CREATE-PROJECT-README.md

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

# Create New Vitesse Project

Automatically create a new [Vitesse](https://github.com/antfu-collective/vitesse) project with your custom dependencies pre-configured.

---

## 🚀 Quick Start

Create a new project with one command:

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

That's it! The script will:
1. ✅ Clone the Vitesse template
2. ✅ Add your custom dependencies to pnpm-workspace.yaml
3. ✅ Update package.json with catalog references
4. ✅ Run `pnpm install` automatically
5. ✅ Ready to start development!

---

## 📋 What Gets Added

### Frontend Dependencies (catalog:frontend)
- **Authorization**: @casl/ability, @casl/vue
- **Validation**: @vuelidate/core, @vuelidate/validators
- **UI Components**: element-plus, @fortawesome/fontawesome-svg-core
- **HTTP Client**: axios, vue-axios
- **Charts**: chart.js, vue-chartjs
- **Utilities**: luxon, prismjs, vuedraggable, vue-virtual-scroller
- **VueUse**: @vueuse/head, @vueuse/integrations
- **Image**: browser-image-compression
- **Others**: vue-demi, universal-cookie, virtual-scroller

### Dev Dependencies
- **Icons**: @iconify-json/ic, @iconify-json/mdi (catalog:dev)
- **Build Tools**: critters, cross-env, sass, ts-node (catalog:build)
- **Vite Plugins**: unplugin-element-plus, vite-plugin-pages, vite-plugin-vue-component-preview (catalog:build)
- **Types**: @types/luxon, @types/node, @types/prismjs (catalog:types)

---

## 🎯 What is Vitesse?

[Vitesse](https://github.com/antfu-collective/vitesse) is an opinionated Vite + Vue starter template created by Anthony Fu. It includes:

- ⚡️ **Vue 3 + Vite** - Lightning fast development
- 📁 **File-based routing** - Automatic route generation
- 📦 **Auto-import components** - No manual imports needed
- 🍍 **Pinia** - State management
- 📑 **Layouts system** - Multiple layout support
- 🎨 **UnoCSS** - Instant on-demand CSS
- 😃 **Icon sets** - Use any icon from Iconify
- 🌍 **i18n ready** - Internationalization built-in
- 🗒️ **Markdown support** - Write pages in Markdown
- 📲 **PWA** - Progressive Web App support
- 🦾 **TypeScript** - Full type safety
- ⚙️ **Testing** - Vitest + Cypress included

---

## 💡 Usage Examples

### Basic Usage

```bash
# Create a new project
node create-vitesse-project.js my-app

# Navigate to project
cd my-app

# Start development server
pnpm dev
```

### Different Project Names

```bash
# E-commerce app
node create-vitesse-project.js shop-frontend

# Dashboard
node create-vitesse-project.js admin-dashboard

# Landing page
node create-vitesse-project.js company-website
```

---

## 🔧 After Creation

Once your project is created, don't forget to:

### 1. Customize Your App
```bash
cd my-app
```

### 2. Update Project Info
- Change the title in `src/App.vue`
- Update `LICENSE` with your name
- Replace favicon in `public/`
- Clean up `README.md`

### 3. Start Development
```bash
pnpm dev
```

Visit http://localhost:3333 to see your app!

### 4. Build for Production
```bash
pnpm build
```

The production files will be in `dist/`

---

## 📦 Available Scripts

After project creation, these scripts are available:

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start development server at http://localhost:3333 |
| `pnpm build` | Build for production |
| `pnpm preview` | Preview production build |
| `pnpm test` | Run unit tests with Vitest |
| `pnpm test:e2e` | Run E2E tests with Cypress |
| `pnpm lint` | Lint and fix code |
| `pnpm typecheck` | Check TypeScript types |

---

## 🎨 Customizing Dependencies

Want to modify which dependencies get added? Edit the `CUSTOM_DEPENDENCIES` object in `create-vitesse-project.js`:

```javascript
const CUSTOM_DEPENDENCIES = {
  frontend: [
    'your-package-here',
    // ... more packages
  ],
  dev: [
    '@iconify-json/your-icons',
  ],
  // ... other catalogs
};
```

---

## 🔍 What Happens Behind the Scenes

1. **Clone Template**
   ```bash
   npx degit antfu-collective/vitesse my-app
   ```

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

3. **Update Workspace**
   - Modifies `pnpm-workspace.yaml`
   - Adds packages to appropriate catalogs (frontend, dev, build, types)
   - Preserves existing structure

4. **Update Package.json**
   - Adds catalog references like `"axios": "catalog:frontend"`
   - Maintains existing dependencies

5. **Install Everything**
   - Runs `pnpm install`
   - Resolves all catalog versions
   - Creates lock file

---

## 🆚 Comparison with Manual Setup

### Manual Way (20+ minutes)
1. Clone Vitesse template
2. Open pnpm-workspace.yaml
3. Look up latest version for each package
4. Add each version manually
5. Open package.json
6. Add each catalog reference
7. Run pnpm install
8. Fix any typos or errors

### Automated Way (2 minutes)
```bash
node create-vitesse-project.js my-app
cd my-app
pnpm dev
```

---

## 📚 Related Scripts

| Script | Purpose |
|--------|---------|
| `create-vitesse-project.js` | ⭐ Create new project from scratch |
| `auto-update-full.js` | Update existing project's catalog |
| `auto-update-catalog.js` | Update only workspace file |
| `install-missing-deps.sh` | Direct install (no catalog) |

---

## 🐛 Troubleshooting

### "Directory already exists"
```bash
# Use a different name or remove existing directory
rm -rf my-app
node create-vitesse-project.js my-app
```

### "degit not found"
The script will automatically use `npx degit`, no installation needed.

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

### Failed to fetch versions
The script will use `latest` as fallback. You can manually update versions later.

---

## 🌟 Tips

1. **Use Descriptive Names**: Choose project names that reflect your app's purpose
2. **Check Node Version**: Vitesse requires Node >=14.18
3. **Commit Early**: Initialize git and commit right after creation
4. **Explore the Template**: Vitesse has many built-in features worth exploring

---

## 📞 Need Help?

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

---

## ✨ Example Workflow

```bash
# 1. Create project
node create-vitesse-project.js my-store

# 2. Navigate to it
cd my-store

# 3. Start development
pnpm dev

# 4. Open browser to http://localhost:3333

# 5. Start coding! 🎉
```

That's it! You now have a fully configured Vitesse project with all your custom dependencies ready to go! 🚀