🚀 nextjs-boilerplate-kit

The ultimate CLI tool for generating modern, production-ready Next.js applications with enterprise-grade features, modular architecture, and best practices built-in.

✨ What Makes This Special?

nextjs-boilerplate-kit is not just another Next.js starter template. It's a modular, interactive CLI tool that lets you build exactly what you need, when you need it. Choose your authentication, payments, features, and more through an intuitive command-line interface.

🎯 Interactive Project Generation

npx nextjs-boilerplate-kit my-app
# ✨ Interactive prompts guide you through:
# 🔐 Authentication: NextAuth.js, Supabase, or None
# 👥 Role-Based Auth: Admin/User roles (if Supabase selected)
# 📁 ORM: Drizzle, Prisma, Mongoose, or None (hidden if Supabase selected)
# 💳 Payments: One-time, Subscriptions, or None  
# 📩 Email: Nodemailer for transactional emails
# 🌙 Dark Mode: Theme switching
# 📊 Dashboard: Analytics dashboard
# 📱 PWA: Progressive Web App features
# 📚 Storybook: Component development
# 🐳 Docker: Containerization
# 🔍 Sentry: Error monitoring

🚀 Quick Start

Prerequisites

• Node.js >= 20.0.0
• npm, yarn, or pnpm

Complete CLI Flow

Run the command and follow the interactive prompts:

npx nextjs-boilerplate-kit my-awesome-app

Here's the complete interactive flow you'll experience:

🌟 Welcome to nextjs-boilerplate-kit!
   Let's create your modern Next.js application

===============================
CORE APPLICATION CONFIGURATION
===============================

🔐 Choose your authentication provider:
❯ NextAuth.js - Complete auth with OAuth providers
  Supabase Auth - Real-time auth with database
  None - Add authentication later

👥 Enable Role-Based Authentication (Admin/User roles)? (if Supabase selected)
❯ Yes
  No

📁 Choose your ORM (Object-Relational Mapping): (hidden if Supabase selected)
❯ None - Add database operations later
  Drizzle - Lightweight, type-safe TypeScript ORM
  Prisma - Powerful database toolkit with introspection
  Mongoose - MongoDB object modeling with TypeScript

===============================
PAYMENT & COMMUNICATION
===============================

💳 Choose your Stripe integration:
❯ None - Add payments later
  One-time payments - Single payments and purchases
  Subscriptions - Recurring billing and subscriptions

📩 Include Email module (Nodemailer) for transactional emails?
❯ Yes
  No

===============================
UI & USER EXPERIENCE
===============================

🌙 Enable dark mode toggle in your app?
❯ Yes
  No

📊 Include a Dashboard page (graphs, tables, stats)?
❯ Yes
  No

📱 Include PWA (Progressive Web App) support?
❯ Yes
  No

===============================
DEVELOPMENT & DEPLOYMENT
===============================

📚 Include Storybook for UI component development?
❯ Yes
  No

🐳 Include Docker configuration for containerization?
❯ Yes
  No

🔍 Include Sentry for error monitoring and performance tracking?
❯ Yes
  No

🚀 Creating project in 'my-awesome-app'...

🎉 Project created successfully!

📋 Configuration Summary:
   🔐 Auth: NextAuth
   💳 Payments: None
   📩 Email: Enabled
   📊 Dashboard: Enabled
   📱 PWA: Enabled
   📚 Storybook: Enabled
   🐳 Docker: Enabled
   🔍 Sentry: Enabled
   📁 ORM: None
   🌙 Dark Mode: Enabled

🚀 Next Steps:
   cd my-awesome-app
   npm install
   cp .env.example .env.local
   # Configure environment variables in .env.local
   npm run dev

💡 Tip: Visit http://localhost:3000 to see your app!

Made with 💜 by CodeHuddle
Lets build the future together!⚡

Setup & Run

cd my-awesome-app
npm install
cp .env.example .env.local
npm run dev

🎉 That's it! Visit http://localhost:3000 to see your application.

🏗️ Architecture & Features

🔐 Modular Authentication System

Choose from multiple authentication providers, each with complete implementations:

| Provider | Features | Best For | |----------|----------|----------| | NextAuth.js | OAuth, credentials, session management | Full-featured apps with multiple providers | | Supabase | Real-time auth, database integration | Modern apps with real-time features | | Supabase + Roles | Role-based access control (Admin/User) | Enterprise applications | | None | No authentication | Simple apps or custom auth later |

Example CLI Flow:

🔐 Choose your authentication provider:
❯ NextAuth.js - Complete auth with OAuth providers
  Supabase Auth - Real-time auth with database  
  None - Add authentication later

📁 Smart Database ORM Integration

Intelligent ORM selection with modern test interfaces:

| ORM | Features | Use Case | |-----|----------|----------| | Drizzle | Lightweight, type-safe TypeScript ORM with zero runtime overhead | Fast, minimal database operations | | Prisma | Powerful database toolkit with introspection and migrations | Feature-rich applications with complex queries | | Mongoose | MongoDB object modeling with TypeScript support and schema validation | MongoDB applications with flexible schema design | | None | No database operations (auto-selected with Supabase Auth) | Simple apps or custom database setup later |

Smart Logic:

• Supabase Auth → Automatically selects None ORM (Supabase handles database)
• Other Auth → Shows ORM selection prompt
• Modern Test Pages with setup instructions and interactive CRUD operations

Features Included:

• Users-Only CRUD operations with React Query hooks
• API Routes for user management (/api/users)
• Modern Test Pages with setup instructions (/test-orm)
• Type-Safe Queries with full TypeScript support
• Database Schema definitions and migrations
• Setup Instructions for each ORM with proper commands

Example CLI Flow:

📁 Choose your ORM (Object-Relational Mapping): (hidden if Supabase selected)
❯ None - Add database operations later
  Drizzle - Lightweight, type-safe TypeScript ORM
  Prisma - Powerful database toolkit with introspection
  Mongoose - MongoDB object modeling with TypeScript

💳 Flexible Payment Integration

Integrated Stripe payments with complete flows:

| Integration | Features | Pages Included | |-------------|----------|----------------| | One-time Payments | Single payments, purchases | /test-payment, /payment/success, /payment/cancel | | Subscriptions | Recurring billing, subscription management | /test-subscription, /payment/success, /payment/cancel | | None | No payment integration | - |

Interactive Landing Page: When you select Stripe integration, your landing page automatically includes clickable links to test payment functionality.

📊 Optional Dashboard Module

Modern analytics dashboard with:

• KPI Cards with metrics and trends
• Interactive Charts using Recharts
• Activity Timeline for user actions
• Sales Table with data visualization
• Responsive Design with sidebar navigation

📱 Progressive Web App (PWA)

Complete PWA implementation:

• Web App Manifest for app-like experience
• Service Worker for offline functionality
• Install Prompt component for app installation
• Offline Support with caching strategies

📚 Storybook Integration

Component development environment:

• Pre-configured Storybook setup
• Component Stories for UI development
• Interactive Documentation for your design system
• Visual Testing capabilities

🐳 Docker Containerization

Production-ready containerization:

• Multi-stage Build for optimized images
• Development Environment with hot reloading
• Production Configuration for deployment
• Generic Templates - easily customizable

🔍 Sentry Error Monitoring

Comprehensive error tracking and performance monitoring:

• Error Tracking with automatic error capture
• Performance Monitoring for optimization insights
• Source Maps for detailed stack traces
• Session Replay for debugging user interactions
• Custom Configuration - easily customizable

🌙 Smart Dark Mode

Intelligent theme system:

• System Preference Detection
• localStorage Persistence
• Smooth Transitions with CSS variables
• Conditional Inclusion - only adds toggle if enabled

🛠️ Technology Stack

Core Framework

• Next.js 15 - Latest React framework with App Router
• React 19 - Latest React with concurrent features
• TypeScript - Full type safety
• Tailwind CSS v4 - Utility-first styling

UI & Components

• shadcn/ui - Beautiful, accessible components
• Radix UI - Low-level UI primitives
• Lucide React - Beautiful icon library
• Class Variance Authority - Component variants

State Management

• Zustand - Lightweight state management
• TanStack Query - Server state management
• React Hook Form - Performant forms
• Zod - TypeScript-first validation

Database & ORM

• Drizzle ORM - Lightweight, type-safe TypeScript ORM with zero runtime overhead
• Prisma - Powerful database toolkit with introspection and migrations
• Mongoose - MongoDB object modeling with TypeScript support and schema validation
• PostgreSQL - Primary database support for Drizzle and Prisma
• MongoDB - NoSQL database support for Mongoose
• Smart ORM Selection - Auto-selects None ORM when Supabase Auth is chosen
• Database Migrations - Schema versioning and updates
• Type-Safe Queries - Full TypeScript integration
• Modern Test Pages - Interactive database testing with setup instructions

Development Tools

• Vitest - Fast unit testing
• Playwright - E2E testing
• ESLint - Code linting
• Prettier - Code formatting
• Husky - Git hooks
• Commitizen - Conventional commits

Production Ready

• Bundle Analysis with @next/bundle-analyzer
• Docker configuration
• CI/CD templates
• SEO Optimization
• Performance Monitoring ready

📁 Project Structure

my-awesome-app/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── [locale]/          # Internationalization
│   │   │   ├── (auth)/        # Authentication routes
│   │   │   │   ├── sign-in/   # Sign in pages
│   │   │   │   ├── sign-up/   # Sign up pages
│   │   │   │   ├── dashboard/ # Dashboard (if enabled)
│   │   │   │   ├── admin/     # Admin routes (Supabase Roles)
│   │   │   │   └── user/      # User routes (Supabase Roles)
│   │   │   ├── test-payment/  # Stripe test pages
│   │   │   ├── test-subscription/ # Subscription test
│   │   │   └── test-email/    # Email testing
│   │   └── api/               # API routes
│   ├── components/            # Reusable components
│   │   ├── ui/               # shadcn/ui components
│   │   ├── auth/             # Authentication components
│   │   └── dashboard/        # Dashboard components
│   ├── lib/                  # Utility libraries
│   ├── hooks/                # Custom React hooks
│   ├── stores/               # Zustand stores
│   ├── types/                # TypeScript definitions
│   ├── validations/          # Zod schemas
│   └── locales/              # Translation files
├── public/                   # Static assets
├── tests/                    # Test files
├── .storybook/              # Storybook configuration
└── docs/                    # Documentation

🎯 Available Scripts

| Script | Description | |--------|-------------| | npm run dev | Start development server with Turbo | | npm run build | Build for production | | npm run start | Start production server | | npm run lint | Run ESLint | | npm run lint:fix | Fix ESLint errors | | npm run test | Run unit tests with Vitest | | npm run test:e2e | Run E2E tests with Playwright | | npm run storybook | Start Storybook development | | npm run generate:component | Generate new component | | npm run build-stats | Build with bundle analysis |

🌍 Internationalization

Built-in i18n support with next-intl:

• Multiple Languages - English, French, and more
• Locale-based Routing - /en/, /fr/ paths
• Dynamic Translations - Server and client components
• SEO-friendly - Proper meta tags per locale

🧪 Testing Strategy

Comprehensive testing setup:

Unit Testing (Vitest)

npm run test
# Fast unit tests with React Testing Library

E2E Testing (Playwright)

npm run test:e2e
# End-to-end testing across browsers

Component Testing (Storybook)

npm run storybook
# Visual component development and testing

🔧 Configuration Examples

Environment Variables

The CLI automatically generates .env.example with the right variables for your selected modules:

# Authentication (NextAuth.js)
NEXTAUTH_SECRET=your-secret-here
NEXTAUTH_URL=http://localhost:3000

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

# Email (Nodemailer)
SMTP_HOST="smtp_...

# Mongoose (MongoDB)
MONGODB_URI="mongodb://localhost:27017/nextjs-app"

🚀 Production Deployment

Vercel (Recommended)

# Deploy to Vercel
npx vercel

# Set environment variables in Vercel dashboard

Docker

# Build Docker image
docker build -t my-app .

# Run container
docker run -p 3000:3000 my-app

Other Platforms

• Netlify - Static site generation
• Railway - Full-stack deployment
• AWS - Container deployment
• DigitalOcean - App Platform

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

👥 Developers

Meet the team behind nextjs-boilerplate-kit:

🙏 Acknowledgments

• Next.js Team - For the amazing framework
• Vercel - For hosting and deployment
• shadcn/ui - For beautiful components
• Radix UI - For accessible primitives
• Tailwind CSS - For utility-first styling

💜 Made with ♥ by CodeHuddle
🚀 Happy coding • Join our amazing community!

⭐ Star us on GitHub • 📦 NPM Package • 🌐 Code Huddle