npm package: @loudpacks/create-nextjs-pwa
Description: Modern CLI generator for Next.js Progressive Web Applications with TypeScript, Tailwind CSS, and customizable features
Author: Your Name
Latest version: 1.2.2

# create-nextjs-pwa

Modern CLI generator for Next.js Progressive Web Applications with TypeScript, Tailwind CSS, and customizable features.

[![npm version](https://img.shields.io/npm/v/create-nextjs-pwa.svg)](https://www.npmjs.com/package/create-nextjs-pwa)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
# 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:

```bash
# Add sticky header
add-header

# Add Clerk authentication
add-auth-clerk

# Add dark mode toggle
add-darkmode
```

## Installation

### Global Installation

```bash
npm install -g create-nextjs-pwa
```

### Local Development

```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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`:

```typescript
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`:

```env
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`:

```env
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

```bash
# 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
```bash
npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:ui       # UI mode
npm run test:coverage # Coverage report
```

### Jest
```bash
npm test              # Run tests
npm run test:watch    # Watch mode
```

### Cypress
```bash
npm run cypress:open  # Open Cypress UI
npm run cypress:run   # Run tests headless
```

### Playwright
```bash
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
```bash
npm cache clean --force
npm install
```

### shadcn/ui components not working
```bash
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 <your.email@example.com>

## Links

- [npm Package](https://www.npmjs.com/package/create-nextjs-pwa)
- [GitHub Repository](https://github.com/your-username/create-nextjs-pwa)
- [Issue Tracker](https://github.com/your-username/create-nextjs-pwa/issues)
- [Next.js Documentation](https://nextjs.org/docs)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [shadcn/ui Documentation](https://ui.shadcn.com)

## Support

For issues and questions:
- Open an issue on GitHub
- Check existing documentation
- Review troubleshooting section

---

**Generated with create-nextjs-pwa** 🚀