npm package: @horizon-labs/vite-react-tailwind-boilerplate
Description: Modern Vite + React 19 + Tailwind CSS v4 + ShadCN UI boilerplate with TypeScript
Author: Jefferson
Latest version: 1.1.0

# Vite + React + Tailwind CSS v4 Boilerplate

> 🚀 **Production-Ready Boilerplate** - Modern, fast, and feature-complete starter template for React projects

## 📋 Tech Stack

- **⚡ Vite 6** - Lightning fast build tool with HMR
- **⚛️ React 19** - Latest React with concurrent features
- **🎨 Tailwind CSS v4** - Next-gen utility-first CSS framework
- **🔧 TypeScript** - Full type safety and excellent DX
- **🎯 ShadCN UI** - Beautiful, accessible UI components
- **🧭 React Router v7** - Client-side routing
- **📦 PNPM** - Fast, disk space efficient package manager

## 🚀 Quick Start

### 1. Create New Project
```bash
# Using npx (recommended)
npx @horizon-labs/vite-react-tailwind-boilerplate my-project

# Or clone manually
git clone <repo-url> my-project
cd my-project
pnpm install
```

### 2. Development
```bash
# Start dev server (http://localhost:5173)
pnpm dev

# Type checking
pnpm typecheck

# Linting
pnpm lint
```

### 3. Production
```bash
# Build for production
pnpm build

# Preview production build
pnpm preview
```

## 📁 Project Structure

```
src/
├── components/          # Reusable UI components
│   ├── ui/             # ShadCN UI components
│   ├── Navigation.tsx  # App navigation
│   └── ViteHome.tsx    # Home page component
├── pages/              # Route pages
│   ├── Home.tsx        # Home page
│   ├── About.tsx       # About page
│   └── Contact.tsx     # Contact page
├── hooks/              # Custom React hooks
├── lib/                # Utilities and helpers
├── index.css           # Global styles + Tailwind import
└── main.tsx            # App entry point
```

## 🎨 Features Included

### ✅ **Tailwind CSS v4 Setup**
- ✅ Configured with `@import "tailwindcss"`
- ✅ Vite plugin integration (`@tailwindcss/vite`)
- ✅ Custom utility classes
- ✅ Responsive design examples

### ✅ **ShadCN UI Components**
- ✅ Pre-installed component library
- ✅ Accessible, customizable components
- ✅ Dark mode support ready
- ✅ Form components (Button, Input, etc.)

### ✅ **React Router Setup**
- ✅ 3 example routes (Home, About, Contact)
- ✅ Navigation component with active states
- ✅ TypeScript route definitions

### ✅ **Development Experience**
- ✅ Hot Module Replacement (HMR)
- ✅ TypeScript path aliases (`@/*`)
- ✅ ESLint configuration
- ✅ Type checking script

## 🛠️ Available Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start development server |
| `pnpm build` | Build for production |
| `pnpm preview` | Preview production build |
| `pnpm typecheck` | Run TypeScript checks |
| `pnpm lint` | Run ESLint |

## 🎯 Usage Instructions

### Adding New Pages
1. Create component in `src/pages/`
2. Add route in `src/App.tsx`
3. Update navigation in `src/components/Navigation.tsx`

### Adding New Components
1. Create in `src/components/`
2. Use ShadCN UI components from `src/components/ui/`
3. Apply Tailwind classes for styling

### Customizing Styles
- Global styles: `src/index.css`
- Tailwind config: Auto-generated (v4 style)
- Component styles: Inline Tailwind classes

## 🔧 Configuration Files

| File | Purpose |
|------|---------|
| `vite.config.ts` | Vite configuration + Tailwind plugin |
| `tsconfig.json` | TypeScript configuration |
| `eslint.config.js` | ESLint rules |
| `components.json` | ShadCN UI configuration |

## 📦 Key Dependencies

### Production
- `react` + `react-dom` - Core React
- `tailwindcss` + `@tailwindcss/vite` - Styling
- `react-router` - Routing
- `@radix-ui/*` - ShadCN UI primitives

### Development
- `vite` - Build tool
- `typescript` - Type checking
- `eslint` - Code linting
- `@vitejs/plugin-react` - React support

## ⚡ Performance Features

- ✅ **Fast Refresh** - Instant component updates
- ✅ **Code Splitting** - Automatic route-based splitting
- ✅ **Tree Shaking** - Remove unused code
- ✅ **Modern JS** - ES2020+ output
- ✅ **Optimized Assets** - Automatic optimization

## 🚨 Important Notes

### Tailwind CSS v4
- Uses new `@import "tailwindcss"` syntax
- Vite plugin auto-detects components for CSS generation
- No separate config file needed

### Path Aliases
- `@/*` maps to `src/*`
- Configured in `tsconfig.json` and `vite.config.ts`

### TypeScript
- Strict mode enabled
- Path mapping configured
- All components typed

---

## 🤖 AI Assistant Instructions

**For AI assistants using this boilerplate:**

1. **Always run `pnpm typecheck`** after making changes
2. **Use existing patterns** - follow the established component structure
3. **Tailwind v4 syntax** - use `@import "tailwindcss"` not v3 directives
4. **ShadCN components** - prefer ui components over custom ones
5. **Path aliases** - use `@/` imports consistently

### Common Commands
```bash
# Start development
pnpm dev

# Check types (ALWAYS run after changes)
pnpm typecheck

# Full check before committing
pnpm typecheck && pnpm lint && pnpm build
```

---

**🎉 Ready to build amazing React apps!**