React-PWA v3 🚀🎉⚡️

🌟 Overview

React-PWA is an opinionated starter kit for building Progressive Web Applications with React. Designed to streamline development, it combines essential libraries, components, utilities, and developer tools to accelerate your workflow.

💡 Motivation

Building a modern web application requires a robust setup, including routing, UI components, theming, error handling, a structured file system, testing tools, and performance optimizations. React-PWA provides a production-ready, minimal, and efficient environment for developers to focus on creating great applications.

✨ Tech Stack & Features

Core Technologies

Technology	Version	Description
Vite	v6	Fast build tool based on ES modules, Rollup, and esbuild
React	v19	Latest version with all modern features
TypeScript	Latest	Type-safe JavaScript for better development
MUI	v6	Comprehensive UI framework with MUI

Key Features

• Routing: React Router v7 for flexible client-side routing
• State Management: Jotai for simple, efficient state handling
• Theming: Customizable dark/light mode with MUI theme system
• Notifications: Alert system with MUI Toolpad integration
• PWA Support: Works offline and installs on any device
• Hotkeys: Built-in keyboard shortcuts for common actions
• Error Handling: Graceful error boundaries with custom fallbacks
• Performance: All green Lighthouse scores with optimized bundle size

Developer Tools

• Testing: Vitest for unit tests, Playwright for e2e tests
• CI/CD: GitHub Actions workflows for quality checks and testing
• Code Quality: ESLint, Prettier, TypeScript integration
• Git Hooks: Husky with lint-staged for pre-commit quality enforcement
• Local HTTPS: Built-in support for local HTTPS development

🚀 Getting Started

Quick Start

# Clone the repository
git clone /~https://github.com/suren-atoyan/react-pwa.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Available Scripts

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run prettier:check	Check formatting
npm run lint:check	Check linting
npm run ts:check	Check TypeScript
npm run test:unit	Run unit tests
npm run test:e2e	Run e2e tests
npm run test:e2e:ui	Run e2e tests in UI mode
npm run preview	Preview production build locally
npm run https-preview	Preview with HTTPS

📁 Project Structure

react-pwa/
├── ...
├── src/
│   ├── components/     # Reusable UI components
│   ├── config/         # Application configuration
│   ├── error-handling/ # Error management
│   ├── hooks/          # Custom hooks
│   ├── pages/          # Application pages/routes
│   ├── routes/         # Routing configuration
│   ├── sections/       # Self-contained application sections
│   ├── theme/          # Theme configuration
│   └── utils/          # Utility functions
└── ...

Component Organization

Each component follows this structure:

ComponentName/
├── index.ts          # Default exports the component
├── ComponentName.tsx # Pure component implementation
├── types.ts          # Component-related types (optional)
├── styled.ts         # Styled components (optional)
└── utils.ts          # Component-specific utilities (optional)

🔍 Key Features Explained

UI Framework

MUI ensures consistency, accessibility, and performance while remaining highly customizable to match your brand's design language.

import Box from '@mui/material/Box';
import Button from '@mui/material/Button';
import { styled } from '@mui/material/styles';

// styled components
const NewButton = styled(Button)(({ theme }) => ({
  marginRight: theme.spacing(1),
  color: theme.palette.text.disabled,
}));

// sx prop
function MyComponent() {
  return <Box sx={{ borderRadius: theme.shape.borderRadius }}>...</Box>;
}

🎨 Theming

The theme system is based on MUI Theme, supporting dark/light modes and customization.

import { useThemeMode } from '@/theme';

function MyComponent() {
  const { themeMode, toggle } = useThemeMode();
  
  return <Button onClick={toggle}>Toggle Theme</Button>;
}

State Management

Jotai provides simple atoms-based state management for cross-application state, complementing React's useState and data fetching libraries.

Notifications

Utilizes MUI Toolpad’s useNotification for handling alerts in an elegant, customizable way:

function MyComponent() {
  const notifications = useNotifications();

  function showNotification() {
    notifications.show('Operation successful!', {
      autoHideDuration: 5000,
    });
  }
}

🔑 Hotkeys

• Alt+s: Toggle theme mode
• Alt+t: Toggle sidebar
• Alt+/: Open hotkeys dialog

PWA Features

• Works offline with service worker caching
• Installable on mobile and desktop devices
• Automatic updates (configurable in vite.config.ts)

📱 Performance

• Bundle size: ~65KB for largest chunk
• Initial load: ~0.6s
• Cached loads: ~0.01s

Error Handling

The withErrorHandler HOC catches errors and displays friendly fallback UIs:

// In your component:
export default withErrorHandler(MyComponent);

// Or for the entire app:
export default withErrorHandler(App);

🧪 Testing

Unit Tests

npm run test:unit

E2E Tests

npm run test:e2e
# or with UI
npm run test:e2e:ui

🌐 Environment Variables

Place your environment variables in a .env file (prefixed with VITE_):

• Templates available in the env/ directory
• Access via import.meta.env.VITE_VARIABLE_NAME

❓ FAQ

Why use a UI library?

A UI library ensures consistency, accessibility, and development efficiency. Without one, teams would need to create and maintain basic components from scratch, leading to inconsistencies and wasted time.

Why Jotai for state management?

React applications have different state management needs:

• Component-level state: useState for local UI interactions
• Data-layer state: useQuery or Apollo for remote data
• Cross-application state: Jotai provides a minimal, elegant approach

What's the difference between components, sections, and pages?

• Components: Reusable UI elements (Button, List, etc.)
• Sections: Self-contained UI parts with their own logic (Navigation, Sidebar, etc.)
• Pages: Root route components representing application views

Why TypeScript?

TypeScript reduces runtime errors, improves code maintainability, and enhances developer experience with static typing and better IDE support.

Why use Prettier?

Prettier enforces consistent style across all contributors, reducing discussions in PR reviews and ensuring code quality.

🔗 Demo

Check out the live demo

📄 License

MIT