A modern React application boilerplate built with the latest technologies and best practices. This boilerplate is designed for rapid development of Progressive Web Applications (PWA) with Parse Server as the backend.
- React 19.1.1 - Modern UI framework with latest features
- Material-UI (MUI) v7 - Comprehensive component library
- React Router v7 - Client-side routing
- Redux - Centralized state management
- Vite - Next-generation build tool and dev server
- Vitest - Modern testing framework
- Parse Platform - Backend-as-a-Service (can be adapted to other backends)
Before getting started, ensure you have the following installed:
# Clone this repository
$ git clone https://github.com/Blackburn-Labs/proem-ui.git your-project-name
# Navigate into the directory
cd your-project-name
# Install dependencies
npm install
# Note: Playwright browsers (~200MB) will be downloaded automatically during installation
# This only happens once and enables E2E testing out of the boxCreate a .env file in the root directory (see .env.example for template):
API_URL=your_api_urlnpm startYour application will be available at http://localhost:5173
After cloning, you'll want to disconnect from the original boilerplate repository and set up your own:
# Remove the original remote
git remote remove origin
# Initialize fresh git history (optional)
rm -rf .git
git init
git add .
git commit -m "Initial commit from Proem UI boilerplate"
# Add your own repository
git remote add origin your-repo-url
git push -u origin masterAlternative: Download ZIP
You can also simply download the boilerplate as a ZIP file from https://github.com/Blackburn-Labs/proem-ui using the "Download ZIP" button. This gives you a clean start without any git connection.
# Start development server
npm start
# Build for production
npm build
# Preview production build
npm preview
# Run unit tests
npm test
# Run tests in watch mode
npm test:watch
# Run tests with UI
npm test:ui
# Run tests with coverage
npm test:coverage
# Run E2E tests (browsers installed automatically via postinstall)
npm run test:e2e
# Run E2E tests in UI mode
npm run test:e2e:ui
# Lint and fix code
npm run lint/
├── /public/ # Static assets (icons, images, manifest)
├── /src/
│ ├── /components/ # Reusable app-wide UI components
│ │ ├── /layout/ # Layout components (AppBar, Footer, etc.)
│ │ └── /common/ # Common UI components (Button, Card, etc.)
│ ├── /domain/ # Domain models extending BasicDomain/BasicArray
│ │ └── README.md # Domain architecture documentation
│ ├── /features/ # Feature-specific components
│ │ └── /profile/ # Example: Profile feature components
│ │ ├── ProfileDetails.jsx
│ │ ├── ProfileList.jsx
│ │ └── ProfileCard.jsx
│ ├── /router/ # Routing configuration
│ ├── /screens/ # Full page components/views
│ │ ├── HomeScreen.jsx
│ │ └── AboutScreen.jsx
│ ├── /store/ # Redux reducers, actions, and selectors
│ │ └── README.md # Redux patterns documentation
│ ├── /theme/ # Global styles and theme configuration
│ ├── /utils/ # Utility functions and helpers
│ ├── App.jsx # Root application component
│ └── main.jsx # Application entry point
├── /tests/ # Test files
│ ├── /e2e/ # End-to-end tests
│ ├── setup.js # Test setup and configuration
│ └── README.md # Testing strategy guide
├── .env.example # Environment variables template
├── package.json # Project dependencies and scripts
└── vite.config.js # Vite configuration
Contains full-page views that represent the main states/routes of your application. Each screen typically corresponds to a route in your router configuration.
Example: HomeScreen.jsx, DashboardScreen.jsx, AboutScreen.jsx
Contains all UI components related to a specific feature or domain. Each feature gets its own subdirectory with all related components.
Example:
/src/features/profile/
├── ProfileDetails.jsx # Detailed profile view
├── ProfileList.jsx # List of profiles
├── ProfileCard.jsx # Individual profile card
└── ProfileForm.jsx # Profile editing form
Contains generic, reusable components used across multiple features and screens. These should be highly composable and not tied to specific business logic.
Example: Navigation bars, buttons, modals, cards, forms, etc.
-
Domain Models - All data models extend
BasicDomain(Parse.Object) orBasicArray -
Redux Store - Centralized state management with strict patterns
-
Testing Strategy - Focused on business logic, not implementation details
This boilerplate is designed to work with Parse Server, a powerful open-source backend. All Parse-specific code is marked with [PARSE] comments for easy identification and removal if you want to use a different backend.
Key Parse Integration Points:
- Domain models extend
Parse.Object(seesrc/domain/BasicDomain.js) - Redux actions use
Parse.Queryfor data fetching - Authentication via Parse User system
To adapt this boilerplate for a different backend:
- Search for
[PARSE]comments throughout the codebase - Replace Parse.Query calls with your API client
- Update domain models to use your data layer
- Modify authentication flow in store/auth.js
After cloning this boilerplate, follow these steps to make it your own:
Do a project-wide search and replace:
{{App Name}}→ Your application name{{domain}}→ Your domain/organization
Files to update:
package.json- Update name and repositoryindex.html- Update title and meta tagspublic/manifest.json- Update PWA manifest
Customize your application's look and feel:
- Edit
src/theme/theme.jsto match your brand colors and style
- Replace icons in
/public/directory - Update
public/manifest.jsonwith new icon paths - We recommend using RealFaviconGenerator for comprehensive favicon generation
- Replace
/public/logo-light.pngand/public/logo-dark.png - Update logo references in components (e.g.,
src/components/layout/AppBar.jsx)
- Replace this boilerplate
./README.mdwith documentation specific to your project - Include your project's purpose, features, and any custom setup instructions
- Update the technology stack section if you've added or removed dependencies
- Document any project-specific development workflows or conventions
This boilerplate follows a pragmatic testing philosophy that prioritizes developer velocity and actual bug prevention. See tests/README.md for detailed testing guidelines.
Testing Pyramid:
- ✅ Unit Tests - Test pure functions and utilities
- ✅ Integration Tests - Test Redux reducers, selectors, and domain models
- ✅ E2E Tests - Test critical user journeys (3-5 tests)
- ❌ UI Component Tests - We don't write these (see testing guide for why)
This application is configured as a Progressive Web App (PWA):
- Install and run offline
- App-like experience on mobile devices
- Automatic updates
- Fast loading with service workers
To customize PWA settings:
- Edit
public/manifest.json - Update icons in
/public/ - Configure service worker in
vite.config.js
- Use ESLint for code quality (run
npm run lint) - Follow React 19 best practices
- Use functional components with hooks
- Implement proper error boundaries
- Use Redux for global state
- Use local state for UI-only state
- Follow Redux patterns in store/README.md
- Keep components small and focused
- Use composition over inheritance
- Separate business logic from presentation
- Co-locate feature-specific components
Build Errors:
- Ensure Node.js version >= 22.18.0
- Clear
node_modulesand reinstall:rm -rf node_modules && npm install - Clear Vite cache:
rm -rf node_modules/.vite
Environment Variables Not Loading:
- Ensure
.envfile exists in project root - All Vite environment variables must start with
VITE_ - Restart dev server after changing
.env
Tests Failing:
- Run
npm run lintto check for code issues - Ensure all dependencies are installed
- Check test setup in
tests/setup.js
E2E Tests Not Working:
- Playwright browsers are installed automatically via
postinstallscript - If browsers are missing, run
npx playwright installmanually - Browsers are cached in
~/.cache/ms-playwright(macOS/Linux) or%USERPROFILE%\AppData\Local\ms-playwright(Windows)
This boilerplate currently uses Parse SDK ^6.2.0-alpha.3 instead of the latest stable version (6.1.1) to avoid CVE-2025-57324, a prototype pollution vulnerability affecting all versions ≤ 6.1.1.
The caret (^) version range ensures automatic upgrade to stable 6.2.0 when it's released by the Parse team.
Monitoring: Check Parse-SDK-JS releases for updates.
React & Modern JavaScript:
Redux:
Material-UI:
Parse Platform:
Testing:
When contributing to this project:
- Follow the testing guidelines in tests/README.md
- Run
npm run lintbefore committing - Write tests for business logic, not UI components
- Keep commits focused and well-documented
This project is open source and available under the MIT License.
Ready to build something amazing? Start by running npm start and begin customizing this boilerplate for your next project!