create-nextjs-pwa

Modern CLI generator for Next.js Progressive Web Applications with TypeScript, Tailwind CSS, and customizable features.

Features

• 🚀 Next.js 15 with App Router and TypeScript
• 📱 Progressive Web App capabilities (offline support, installable)
• 🎨 Tailwind CSS with customizable themes
• 🔷 Tab-based routing for native app feel
• 🎭 Multiple templates (Basic, Chatbot, E-commerce, Dashboard)
• ✨ Style modes (Grayscale/Modern)
• 🌈 Color themes (Blue, Green, Purple, Red, Gray)
• 🔌 Optional integrations (Supabase, Zustand, shadcn/ui)
• 🧪 Testing frameworks (Vitest, Jest, Cypress, Playwright)

Quick Start

Create a new project

# Using npx (recommended)
npx create-nextjs-pwa

# Or install globally
npm install -g create-nextjs-pwa
create-nextjs-pwa

Add features to existing project

After creating a project, enhance it with these add-on tools:

# Add sticky header
add-header

# Add Clerk authentication
add-auth-clerk

# Add dark mode toggle
add-darkmode

Installation

Global Installation

npm install -g create-nextjs-pwa

Local Development

git clone <repository-url>
cd project-scripts
npm install
npm start

Available Commands

1. create-nextjs-pwa

Main generator for creating new Next.js PWA projects.

Usage:

create-nextjs-pwa
# or
npm start  # when in project-scripts directory

Features:

• Interactive project setup wizard
• Multiple app templates:
  • 📱 Basic PWA
  • 🤖 AI Chatbot
  • 🛒 E-commerce
  • 📊 Dashboard
• Visual style options:
  • ⚫ Grayscale (clean & professional)
  • 🌈 Modern (vibrant & interactive)
• Color themes: Blue, Green, Purple, Red, Gray
• Optional dependencies:
  • Zustand for state management
  • Supabase integration
  • shadcn/ui components
• Testing framework setup
• Git initialization

2. add-header

Adds a sticky header component to existing V3 tab-based PWA projects.

Usage:

cd your-project
add-header

What it does:

• Creates src/components/Header.tsx
• Updates tab layout to include header
• Integrates with theme configuration
• Creates backup of original files

Requirements:

• Must be run from a Next.js project directory
• Project must use App Router (src/app)
• Project must have tab-based structure (src/app/(tabs))

3. add-auth-clerk

Integrates Clerk authentication into your Next.js PWA.

Usage:

cd your-project
add-auth-clerk

What it does:

• Installs @clerk/nextjs dependency
• Creates Clerk provider and middleware
• Generates authentication components
• Sets up environment variables template
• Creates protected route examples
• Optionally adds auth pages to tab navigation

After installation:

1. Create Clerk app at https://dashboard.clerk.com
2. Copy keys to .env.local
3. Run npm run dev
4. Test authentication

4. add-darkmode

Adds dark/light theme toggle with persistence to your PWA.

Usage:

cd your-project
add-darkmode

What it does:

• Installs next-themes dependency
• Creates theme provider component
• Generates dark mode toggle components
• Updates root layout with theme support
• Configures Tailwind for dark mode
• Updates existing components for dark mode support

Components created:

• src/providers/ThemeProvider.tsx
• src/components/ui/ThemeToggle.tsx
• src/components/ui/ThemeToggleMenu.tsx

Project Structure

Generated projects follow this structure:

your-pwa-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx              # Root layout
│   │   ├── page.tsx                # Redirects to /home
│   │   └── (tabs)/                 # Tab route group
│   │       ├── layout.tsx          # Tab layout with navigation
│   │       ├── home/page.tsx
│   │       ├── search/page.tsx
│   │       ├── favorites/page.tsx
│   │       ├── profile/page.tsx
│   │       └── settings/page.tsx
│   ├── components/
│   │   ├── TabNavigation.tsx       # Bottom tab navigation
│   │   ├── [Template components]   # Based on chosen template
│   │   └── ui/                     # shadcn/ui components (optional)
│   ├── config/
│   │   └── theme.ts                # Theme configuration
│   ├── store/                      # Zustand store (optional)
│   ├── lib/                        # Utilities, Supabase client (optional)
│   └── providers/                  # React providers (optional)
├── public/
│   ├── manifest.json               # PWA manifest
│   └── icon-*.png                  # App icons
├── next.config.js                  # Next.js + PWA config
└── tailwind.config.js              # Tailwind configuration

Templates

Basic PWA

Clean progressive web app with essential features only.

AI Chatbot

Chat interface optimized for conversational AI applications.

• Message bubbles
• Chat input with loading states
• Typing indicators

E-commerce

Shopping app with product catalog and cart functionality.

• Product cards with badges
• Shopping cart integration
• Category filtering

Dashboard

Admin dashboard with analytics and data visualization.

• Statistics cards
• Recent activity feed
• Quick actions panel

Configuration

Theme Configuration

Generated in src/config/theme.ts:

export const THEME = {
  primary: '#3B82F6',
  secondary: '#1E40AF',
  accent: '#60A5FA',
} as const;

export const STYLE = {
  mode: 'grayscale' as 'grayscale' | 'modern',
} as const;

Environment Variables

For Supabase integration, create .env.local:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url_here
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key_here

For Clerk authentication, add to .env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key_here
CLERK_SECRET_KEY=your_clerk_secret_key_here
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

Development Scripts

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests (if configured)
npm test

# Run specific add-on tools locally
npm run add-header
npm run add-auth-clerk
npm run add-darkmode

Testing Frameworks

Vitest

npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:ui       # UI mode
npm run test:coverage # Coverage report

Jest

npm test              # Run tests
npm run test:watch    # Watch mode

Cypress

npm run cypress:open  # Open Cypress UI
npm run cypress:run   # Run tests headless

Playwright

npm run test:e2e      # Run E2E tests
npm run test:e2e:ui   # UI mode

PWA Features

• Installable: Add to home screen on mobile/desktop
• Offline Support: Runtime caching for offline functionality
• Service Worker: Auto-generated with next-pwa
• Web Manifest: Configured with app name, icons, and theme
• Mobile Optimized: Responsive design with viewport settings

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Requirements

• Node.js 18.0.0 or higher
• npm 8.0.0 or higher

Troubleshooting

Dependencies failed to install

npm cache clean --force
npm install

shadcn/ui components not working

npx shadcn@latest init
npx shadcn@latest add button input card dialog

PWA not installing

• Ensure you're using HTTPS (required for PWA)
• Check that manifest.json is accessible
• Verify icons are present in /public/

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Archived Tools

Located in archived/ directory:

• add-bottomnav.js - Alternative bottom navigation implementation
• complete_nextjs_pwa_package.js - V1 generator (legacy)
• complete_nextjs_pwa_package_v2.js - V2 generator (legacy)

Documentation

Additional documentation available in docs/:

• README.md - Detailed feature documentation
• index.html - Interactive roadmap
• IMPROVEMENTS.md - Changelog and improvements
• tabbar-notes.md - Tab implementation notes

License

MIT License - see LICENSE file for details

Author

Your Name [email protected]

Links

• npm Package
• GitHub Repository
• Issue Tracker
• Next.js Documentation
• Tailwind CSS Documentation
• shadcn/ui Documentation

Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation
• Review troubleshooting section

Generated with create-nextjs-pwa 🚀