🚀 Create React SPA

The ultimate React SPA scaffolder with authentication, state management, UI libraries, PWA support, and modern tooling

A powerful CLI tool that creates production-ready React applications in seconds with TypeScript, Vite, and your choice of modern libraries and features.

✨ Features

• 🎨 Multiple UI Libraries: Tailwind CSS, Material-UI, Chakra UI, Ant Design, shadcn/ui
• 🔐 Complete Authentication System: Auth.js with reCAPTCHA, OTP verification, and password reset
• 🛡️ Security Features: reCAPTCHA protection, email verification, rate-limited API calls
• 📧 Email Integration: OTP verification and password reset via email
• 📱 PWA Support: Offline-first with service workers and app manifest
• 🌙 Dark Mode: Built-in theme toggle with system detection
• 🔧 Middleware: Route protection and authentication middleware
• 🐳 Docker Ready: Multi-stage Dockerfile with Nginx for production
• 🚀 CI/CD: GitHub Actions workflows for testing and deployment
• 🧪 Testing Setup: Vitest with React Testing Library
• 🔄 State Management: Redux Toolkit, Zustand, Recoil, or Context
• 📦 Package Manager Choice: npm, yarn, or pnpm support
• ⚡ Modern Tooling: TypeScript, ESLint, Vite, and hot reload

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm, yarn, or pnpm

Usage

Create a new React project with a single command:

npx react-spa-gen

That's it! The scaffolder will guide you through an interactive setup to configure your perfect React application.

🎯 Interactive Setup

The scaffolder will guide you through these options:

🚀 Create React SPA
======================
✨ Create modern React applications with TypeScript and Vite!

📝 Project name: my-awesome-app

🎨 Include Tailwind CSS? (Y/n): y
🎨 Customize Tailwind colors? (Y/n): y
🎨 Configure your Tailwind color palette:
Primary color (hex): #3b82f6
Secondary color (hex): #6b7280
Tertiary color (hex): #f3f4f6
Accent color (hex): #10b981

🎨 Choose your UI library:
1. Material-UI (MUI)
2. Chakra UI
3. Ant Design
4. shadcn/ui (Radix + Tailwind)
5. None (vanilla CSS)
Choose (1-5): 4

📱 Include PWA setup (manifest, service worker)? (Y/n): y

🔐 Include Auth.js authentication setup? (Y/n): y
🛡️ Include middleware directory setup? (Y/n): y

🔄 Include GitHub Actions workflows (test/build/automerge)? (Y/n): y
🐳 Include Docker setup? (Y/n): y
🌙 Include advanced theming (dark/light mode toggle)? (Y/n): y
🧪 Include testing setup (Vitest)? (Y/n): y
📦 Package manager (npm/yarn/pnpm): npm
⬇️ Install dependencies automatically? (Y/n): y
🔧 Initialize Git repository? (Y/n): y

📁 Generated Project Structure

my-awesome-app/
├── src/
│   ├── components/
│   │   ├── ui/
│   │   │   └── ThemeToggle.tsx      # Dark/light mode toggle
│   │   └── ThemeProvider.tsx        # Theme context provider
│   ├── pages/
│   │   ├── auth/                    # Authentication pages
│   │   │   ├── signin.tsx           # Sign-in form
│   │   │   ├── signup.tsx           # Registration with reCAPTCHA
│   │   │   ├── verify-otp.tsx       # OTP email verification
│   │   │   ├── forgot-password.tsx  # Password reset request
│   │   │   └── reset-password.tsx   # New password form
│   │   ├── Home.tsx                 # Home page component
│   │   └── About.tsx                # About page component
│   ├── hooks/
│   │   └── use-api.ts               # Rate-limited API client
│   ├── App.tsx                      # Main app component
│   ├── main.tsx                     # App entry point
│   └── index.css                    # Global styles
├── lib/
│   ├── auth.config.ts               # Auth.js configuration
│   └── auth.ts                      # Auth.js setup
├── public/
│   ├── vite.svg                     # Vite logo
│   ├── pwa-192x192.png             # PWA icon (if PWA enabled)
│   └── pwa-512x512.png             # PWA icon (if PWA enabled)
├── .github/
│   └── workflows/                   # CI/CD workflows (if enabled)
│       ├── ci.yml                   # Continuous integration
│       └── cd.yml                   # Continuous deployment
├── middleware.ts                    # Auth middleware (if enabled)
├── package.json                     # Dependencies and scripts
├── vite.config.ts                   # Vite configuration
├── index.html                       # HTML entry point
├── .env.example                     # Environment variables template
├── tailwind.config.js               # Tailwind configuration (if enabled)
├── postcss.config.js                # PostCSS configuration (if enabled)
├── Dockerfile                       # Docker configuration (if enabled)
├── nginx.conf                       # Nginx config (if Docker enabled)
├── .gitignore                      # Git ignore rules
└── README.md                        # Project documentation

🎨 UI Library Options

1. Tailwind CSS

• Utility-first CSS framework
• Dark mode support
• Responsive design utilities
• Custom color palette configuration
• Personalized design system

Color Customization

When you choose to include Tailwind CSS, the scaffolder offers color customization:

• Primary color: Main brand color for buttons, links, and highlights
• Secondary color: Supporting color for backgrounds and borders
• Tertiary color: Light backgrounds and subtle elements
• Accent color: Call-to-action elements and success states

Colors are automatically configured in your tailwind.config.js:

theme: {
  extend: {
    colors: {
      primary: '#3b82f6',    // Custom primary color
      secondary: '#6b7280',  // Custom secondary color  
      tertiary: '#f3f4f6',   // Custom tertiary color
      accent: '#10b981',     // Custom accent color
    },
  },
}

Use your custom colors in components:

<button className="bg-primary text-white hover:bg-primary/90">
  Primary Button
</button>
<div className="bg-tertiary border border-secondary">
  Custom themed content
</div>

2. Material-UI (MUI)

• Google's Material Design
• Rich component library
• Theme customization
• Accessibility built-in

3. Chakra UI

• Simple and modular
• Great developer experience
• Accessible components
• Easy theming

4. Ant Design

• Enterprise-grade UI
• Comprehensive components
• Design language
• TypeScript support

5. shadcn/ui

• Modern component library
• Copy-paste components
• Radix UI + Tailwind
• Highly customizable

🔐 Complete Authentication System

The scaffolder includes a production-ready authentication system with Auth.js, featuring:

🛡️ Security Features

• reCAPTCHA Protection: Registration forms include Google reCAPTCHA verification
• Email Verification: OTP-based email verification for new registrations
• Password Reset: Secure token-based password reset via email
• Rate Limiting: API requests are rate-limited (100 requests per minute)
• Session Management: Secure session handling with Auth.js
• Route Protection: Middleware for protecting authenticated routes

📧 Authentication Pages

Sign-In Page (/auth/signin)

• Email/password login form with validation
• "Forgot password?" link
• Responsive design with your chosen UI library
• OAuth integration can be added manually if needed

Sign-Up Page (/auth/signup)

• Registration form with form validation
• reCAPTCHA verification required
• Redirects to OTP verification after successful registration
• Supports all UI libraries with consistent styling

OTP Verification (/auth/verify-otp)

• 6-digit OTP input with custom styling
• Automatic email retrieval from session
• 60-second resend cooldown with countdown timer
• Success redirect to sign-in page

Forgot Password (/auth/forgot-password)

• Email input for password reset request
• Success confirmation with email sent message
• Link back to sign-in page

Reset Password (/auth/reset-password)

• New password form with confirmation
• Token validation from email link
• Password strength requirements (8+ characters)
• Success redirect to sign-in

🌐 OAuth Integration

OAuth providers (Google, GitHub, etc.) can be manually configured by users:

• Add OAuth provider dependencies
• Configure environment variables for client ID/secret
• Update Auth.js configuration
• Add OAuth buttons to sign-in forms

🔧 API Integration

Rate-Limited API Client (useApi hook)

const { performPostRequest, loading, error } = useApi()

// Protected request with automatic token handling
const response = await performPostRequest('/api/users', {
  body: userData,
  protected: true, // Requires authentication
  headers: { 'Custom-Header': 'value' }
})

Available Methods

• performGetRequest(endpoint, config) - GET with query params
• performPostRequest(endpoint, config) - POST with body data
• performPutRequest(endpoint, config) - PUT with body data
• performDeleteRequest(endpoint, config) - DELETE with query params

Request Configuration

{
  headers?: Record<string, string>     // Custom headers
  body?: any                          // Request body (POST/PUT)
  protected?: boolean                 // Requires auth token (default: false)
  queryParams?: Record<string, string> // URL query parameters
}

⚙️ Environment Setup

The scaffolder generates a complete .env.example file:

# Auth.js Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

# reCAPTCHA (required for registration)
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your-recaptcha-site-key
RECAPTCHA_SECRET_KEY=your-recaptcha-secret-key

# Email SMTP (for OTP and password reset)
[email protected]
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your-app-password

# OAuth Providers (add manually if needed)
# GOOGLE_CLIENT_ID=your-google-client-id
# GOOGLE_CLIENT_SECRET=your-google-client-secret
# GITHUB_CLIENT_ID=your-github-client-id
# GITHUB_CLIENT_SECRET=your-github-client-secret

🚀 Backend API Endpoints

Your backend should implement these endpoints:

POST /api/auth/register          # User registration with reCAPTCHA
POST /api/auth/verify-otp        # Email verification
POST /api/auth/resend-otp        # Resend verification code
POST /api/auth/forgot-password   # Password reset request
POST /api/auth/reset-password    # Password reset with token

🔐 Legacy Authentication Options

Auth0 Integration

// Pre-configured Auth0 setup
import { useAuth0 } from '@auth0/auth0-react';

const { loginWithRedirect, logout, user, isAuthenticated } = useAuth0();

Firebase Auth

// Firebase authentication ready
import { auth } from './firebase-config';
import { signInWithEmailAndPassword } from 'firebase/auth';

Custom Authentication

• Form-based login/register
• JWT token handling
• Protected routes
• User session management

📱 PWA Features

When PWA is enabled, your app includes:

• ✅ Web App Manifest - Install prompt and app-like experience
• ✅ Service Worker - Offline functionality and caching
• ✅ Background Sync - Handle offline actions
• ✅ Push Notifications - Engage users (when configured)
• ✅ App Icons - Custom PWA icons for all devices

🌙 Theming Support

Built-in Dark Mode

import ThemeToggle from '@/components/ui/ThemeToggle';

// Use anywhere in your app
<ThemeToggle />

Theme Provider

// Automatically wraps your app
<ThemeProvider>
  <App />
</ThemeProvider>

Features

• System theme detection
• Manual toggle
• Theme persistence
• Smooth transitions

🐳 Docker Support

Development

# Build the image
docker build -t my-awesome-app .

# Run the container
docker run -p 3000:80 my-awesome-app

Production

# Using docker-compose
docker-compose up

Features

• Multi-stage build (Node.js + Nginx)
• Production optimized
• Security headers
• Gzip compression
• SPA routing support

🚀 GitHub Actions CI/CD

Continuous Integration (ci.yml)

• Multi-node testing (Node 18.x, 20.x)
• Lint and type checking
• Run tests
• Build verification

Continuous Deployment (cd.yml)

• Auto-deploy to Vercel
• Production builds
• Environment management

Setup

1. Add these secrets to your GitHub repository:
   • VERCEL_TOKEN
   • ORG_ID
   • PROJECT_ID

🧪 Testing

Running Tests

npm run test          # Run tests in watch mode
npm run test:ui       # Run tests with UI

Test Structure

import { render, screen } from '@testing-library/react';
import { BrowserRouter } from 'react-router-dom';
import Home from './Home';

test('renders home page', () => {
  render(
    <BrowserRouter>
      <Home />
    </BrowserRouter>
  );
  
  expect(screen.getByText(/welcome/i)).toBeInTheDocument();
});

📜 Available Scripts

Every generated project includes these scripts:

npm run dev           # Start development server
npm run build         # Build for production
npm run preview       # Preview production build
npm run lint          # Run ESLint
npm run test          # Run tests (if testing enabled)
npm run test:ui       # Run tests with UI (if testing enabled)

🔧 Customization

Vite Configuration

// vite.config.ts - Customize as needed
export default defineConfig({
  plugins: [
    react(),
    // PWA plugin (if enabled)
    VitePWA({ /* PWA config */ })
  ],
  // Your custom configuration
});

Package.json

All dependencies are included based on your choices:

• React 18 with TypeScript
• Vite 4 for fast builds
• ESLint for code quality
• Chosen UI library dependencies
• Testing libraries (if enabled)
• PWA plugin (if enabled)

🌟 Examples

Basic App

npx react-spa-gen
# Choose: Tailwind + No PWA + No Docker + Basic features

Full-Featured App

npx react-spa-gen
# Choose: All features enabled for production-ready app

Enterprise App

npx react-spa-gen
# Choose: Material-UI + Auth0 + Docker + CI/CD + Testing

💡 Tips & Best Practices

1. Choose the Right UI Library

• Tailwind: Maximum customization and control
• Material-UI: Consistent Google design system
• Chakra UI: Balance of simplicity and features
• Ant Design: Enterprise applications
• shadcn/ui: Modern, copy-paste components

2. PWA Considerations

• Enable PWA for mobile-first applications
• Configure push notifications separately
• Test offline functionality thoroughly

3. Authentication Setup

• Auth0: Production-ready, handles complexity
• Firebase: Google ecosystem integration
• Custom: Full control but more setup required

4. Docker for Production

• Always enable for production deployments
• Configure environment variables properly
• Use docker-compose for multi-service setups

🐛 Troubleshooting

Node.js Version Issues

# Check your Node.js version
node --version

# Should be 18.0.0 or higher
# Update using nvm:
nvm install 18
nvm use 18

Port Already in Use

# If port 3000 is busy, Vite will automatically use 3001
# Or specify a different port:
npm run dev -- --port 3005

Permission Issues

# If you get permission errors with global install:
npm install -g react-spa-gen --force

# Or use npx instead (recommended):
npx react-spa-gen

Build Errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Or with yarn:
rm -rf node_modules yarn.lock
yarn install

📚 Learn More

• React Documentation
• TypeScript Handbook
• Vite Guide
• Tailwind CSS
• PWA Documentation
• Auth0 React SDK

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• React Team for the amazing framework
• Vite Team for the fast build tool
• All UI library maintainers for their excellent work
• Open source community for inspiration and feedback

📞 Support & Contact

• 📧 Email: [email protected]
• 🐛 Issues: Report bugs or request features
• 💬 Questions: Feel free to reach out for help

Made with ❤️ for the React community

Happy coding! 🚀