https://github.com/suren-atoyan/react-pwa
Starter kit for modern web applications
https://github.com/suren-atoyan/react-pwa
boilerplate pwa react template
Last synced: 7 days ago
JSON representation
Starter kit for modern web applications
- Host: GitHub
- URL: https://github.com/suren-atoyan/react-pwa
- Owner: suren-atoyan
- License: mit
- Created: 2020-06-11T16:29:29.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-11T14:09:45.000Z (9 days ago)
- Last Synced: 2025-04-13T07:47:52.181Z (7 days ago)
- Topics: boilerplate, pwa, react, template
- Language: TypeScript
- Homepage: https://react-pwa.surenatoyan.com/
- Size: 3 MB
- Stars: 630
- Watchers: 14
- Forks: 149
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-vite - React-PWA - React v18, TypeScript, Vite, React Router v6, MUI v5, Recoil, PWA, Eslint, Prettier, Husky, lint-staged, https localhost and more. (Get Started / Templates)
- awesome-vite - React-PWA - React v18, TypeScript, Vite, React Router v6, MUI v5, Recoil, PWA, Eslint, Prettier, Husky, lint-staged, https localhost and more. (Get Started / Templates)
README
# React-PWA v3 🚀🎉⚡️
[](https://github.com/suren-atoyan/react-pwa/actions/workflows/analyses.yml)
[](https://github.com/suren-atoyan/react-pwa/actions/workflows/tests:e2e.yml)
## 🌟 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](https://vitejs.dev/) | v6 | Fast build tool based on ES modules, Rollup, and esbuild |
| [React](https://react.dev/) | v19 | Latest version with all modern features |
| [TypeScript](https://www.typescriptlang.org/) | Latest | Type-safe JavaScript for better development |
| [MUI](https://mui.com/) | v6 | Comprehensive UI framework with MUI |
### Key Features
- **Routing**: [React Router v7](https://reactrouter.com/) for flexible client-side routing
- **State Management**: [Jotai](https://jotai.org/) for simple, efficient state handling
- **Theming**: Customizable dark/light mode with MUI [theme system](https://mui.com/material-ui/customization/theming/)
- **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
```bash
# 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.
```jsx
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 ...;
}
```
### 🎨 Theming
The theme system is based on MUI Theme, supporting dark/light modes and customization.
```jsx
import { useThemeMode } from '@/theme';
function MyComponent() {
const { themeMode, toggle } = useThemeMode();
return Toggle Theme;
}
```
### 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:
```jsx
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:
```jsx
// In your component:
export default withErrorHandler(MyComponent);
// Or for the entire app:
export default withErrorHandler(App);
```
## 🧪 Testing
### Unit Tests
```bash
npm run test:unit
```
### E2E Tests
```bash
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](https://react-pwa.surenatoyan.com/)
## 📄 License
[MIT](./LICENSE)