Nuxt Boilerplate

A modern Nuxt 4 production-ready boilerplate with TypeScript, authentication, and full-stack development tools.

🚀 Features

• 🔧 Nuxt 4 with Vue 3 Composition API and TypeScript
• 🎨 Nuxt UI components with Tailwind CSS
• 🔐 Authentication with JWT sessions, bcrypt password hashing, and email verification system
• 🗄️ Prisma ORM with PostgreSQL and Docker setup
• 🌍 Internationalization (French/English) with auto-detection
• 🛡️ Security hardening with CORS, CSP, rate limiting, and flexible HTTP/HTTPS configuration
• 🧪 Testing with Vitest (unit) and Playwright (E2E)
• ✨ Code Quality with ESLint, Prettier, and conventional commits
• 🗂️ State Management with Pinia and cookie persistence
• 📱 SEO Optimized with structured meta tags
• 🐳 Docker support for development

⚡ Quick Start

Prerequisites

• Node.js ≥ 22.0.0
• pnpm ≥ 9.0.0
• Docker (for PostgreSQL)

Setup

1. Clone and install

   git clone <repository-url> my-project
   cd my-project
   pnpm install
   cp .env.example .env
   

2. Start database

   docker compose up -d          # Start PostgreSQL + Adminer
   pnpm prisma migrate dev       # Run database migrations
   

   Access Adminer (database UI) at http://localhost:8080 with your database credentials.

3. Run development server

   pnpm run dev
   

Visit http://localhost:3000 to see your app with authentication system and example Posts.

🛠️ Key Commands

pnpm run dev           # start dev server
pnpm run build         # build for production
pnpm run lint          # run ESLint + Prettier
pnpm test              # run unit + E2E tests
docker compose up -d   # start PostgreSQL + Adminer (localhost:8080)
pnpm prisma migrate dev # run DB migrations

📁 Project Structure

├── app/                      # Nuxt application
│   ├── components/           # Vue components (auto-imported)
│   ├── composables/          # Form composables, utilities
│   ├── pages/                # File-based routing
│   └── layouts/              # Layout components
├── shared/                   # Shared utilities (auto-imported)
│   ├── models/               # Zod schemas and type definitions
│   ├── types/                # API and shared types
│   └── utils/                # Utility functions
├── server/                   # Server-side code
│   ├── api/                  # API routes (auto-mapped)
│   ├── services/             # Business logic services
│   └── middleware/           # Server middleware
├── prisma/                   # Database schema and migrations
└── test/                     # Unit and E2E tests

🔧 Tech Stack

• Frontend: Nuxt 4, Vue 3, TypeScript, Nuxt UI, Tailwind CSS
• Backend: Nitro, H3, PostgreSQL, Prisma ORM
• Auth: JWT sessions, bcrypt, email verification, rate limiting
• Testing: Vitest (unit) + Playwright (E2E)
• Quality: ESLint, Prettier, Husky hooks

📚 Documentation

Detailed implementation guides in /docs/:

🎯 Implementation Patterns

• Form Patterns - Form composables and validation
• Component Architecture - Vue component patterns
• Database Patterns - Prisma usage and optimization
• Security Patterns - Authentication, HTTPS/HTTP security, CORS
• Testing Patterns - Unit and E2E testing strategies
• Pinia Patterns - State management with persistence
• Notification System - Toast system and notifications

🌟 System Features

• Email System - Handlebars templates and automated delivery
• Internationalization - Multi-language support
• SEO Patterns - SEO optimization and social media
• Auto-imports Configuration - Optimized auto-imports setup

🚀 Operations

• API Documentation - Auto-generated API documentation

🎛️ Environment Configuration

Copy .env.example to .env and configure:

# Database (required)
NUXT_DATABASE_URL="postgresql://postgres:P@ssw0rd@localhost:5432/database"

# Authentication (required)
NUXT_SESSION_PASSWORD="your-32-character-secret-key-here"

# Email System (required for email verification/password reset)
NUXT_EMAIL_HOST="smtp.gmail.com"
NUXT_EMAIL_PORT="587"
NUXT_EMAIL_USER="[email protected]"
NUXT_EMAIL_PASS="your-app-password"
NUXT_EMAIL_FROM="[email protected]"

# Production Configuration
NUXT_PUBLIC_SITE_URL="https://yourdomain.com"
# CORS is handled automatically by Nitro for API routes
# Use a reverse proxy (nginx/haproxy) for HTTPS in production

🚀 Getting Started Guide

1. Authentication System - Complete JWT auth with registration, login, email verification, password reset
2. Email System - Email verification and password reset with template rendering
3. Posts Example - Full CRUD implementation demonstrating the architecture
4. Form Patterns - Reusable form composables with validation (useLoginForm, usePostForm)
5. Auto-imports - No manual imports needed for shared utilities, composables, components

🤝 Contributing

1. Follow conventional commit format
2. Run tests before submitting: pnpm test
3. Ensure code quality: pnpm run lint

Built with ❤️ using Nuxt 4