A serverless, progressive, responsive starter user interface (UI) with React at the core of the technology stack.
This project is licensed under the MIT License - see LICENSE file for details.
For detailed guides and reference materials, see the Project Documentation.
If you do not wish to check out the repository and run the starter kit locally, you may view the latest release of the React Starter Kit at https://react-starter.leanstacks.net/. Please see the Authentication section below for instructions to sign in.
NOTE: This app does not collect any data and does not use cookies.
This project's API integration uses the simulated REST endpoints made available by JSON Placeholder.
There are some limitations to the JSON Placeholder APIs. The primary limitation is that the API is stateless. You may create (post), update (put), and delete items within the JSON Placeholder collections; however, the collections are not actually mutated and persisted by JSON Placeholder. Within the starter kit, we update the TanStack Query caches upon successful mutation to simulate a stateful back end.
When using the application, you may sign in with any of the JSON Placeholder Users. Simply enter the Username value from any user in the API and use any value for the Password. For example, try username Kamren or Samantha and password abc123.
- Type-safe development with TypeScript strict mode enabled across the entire codebase
- Modular component architecture with separation of concerns: common shared components, hooks, utilities, and page-specific components with co-located tests
- React Router DOM for declarative, nested routing with lazy-loaded code splitting and
Suspenseboundary integration - Context API + custom hooks for global state management (authentication, settings, notifications, API configuration)
- Efficient re-renders with React hooks best practices, memoization where appropriate, and optimized context selectors
- shadcn/ui base component library with full customization via Tailwind CSS variants and CVA (Class Variance Authority)
- Pre-built common components including Header, Layout, Dialog, Dropdown, Menu, Accordion, Tabs, Card, Badge, and more
- Icon system with Font Awesome and Lucide icons for consistent iconography across the application
- Accessible, semantic HTML components following WAI-ARIA guidelines for inclusive user experiences
- Composition-based component patterns encouraging reusability and maintainability over implementation inheritance
- React Hook Form for performant, flexible form handling with minimal re-renders
- Zod schema validation providing compile-time type safety and runtime validation
- Custom field components integrating with shadcn/ui for consistent styled form inputs
- Error handling and display with user-friendly validation messages and field-level feedback
- Form state persistence via browser storage utilities for seamless user experience
- Axios HTTP client with centralized configuration, request/response interceptors, and error handling
- TanStack Query (React Query) for declarative data fetching, caching, synchronization, and background updates
- Custom API hooks (e.g.,
useGetCurrentUser,useGetSettings) encapsulating common API operations - Optimistic updates with automatic cache invalidation and rollback on errors
- Request deduplication preventing duplicate API calls for the same resource
- Error boundaries and fallback UI for graceful error handling throughout the application
- Tailwind CSS utility-first CSS framework for rapid UI development and consistent design system
- CSS custom properties for dynamic theming, supporting light/dark mode and custom color schemes
- CVA (Class Variance Authority) for managing component styles and variants in a type-safe manner
- Responsive design utilities ensuring mobile-first, adaptive layouts across all screen sizes
- React Spring animations library for smooth, physics-based transitions and interactive elements
- React i18next framework for multi-language support with lazy-loaded language files
- Dynamic language switching without page reload
- Translation management with namespace support for organized locale files
- TanStack Table for powerful, headless table/datagrid components with sorting, filtering, and pagination
- Recharts composable charting library for data visualization and analytics
- Modal dialogs and dropdowns with context-aware positioning and keyboard navigation
- Toast notifications system for non-intrusive user feedback (success, error, warning, info states)
- Loading and skeleton UI with
Suspenseboundaries for streaming updates and better perceived performance
- Environment-based configuration using
.envfiles withVITE_prefixed variables for frontend access - Type-safe config initialization with Zod schema validation at application startup
- Runtime configuration switching without redeployment (e.g., API endpoints, feature flags)
- Development vs. production config separation with sensible defaults and override capabilities
- Vitest as the core unit testing framework with V8 code coverage support
- React Testing Library for user-centric component testing (prefer testing behaviors over implementation)
- Mock Service Worker (MSW) for seamless API mocking in both tests and Storybook
- Co-located test files (
.test.ts,.test.tsx) adjacent to source for easy maintenance and discovery - 80% minimum code coverage requirement ensuring testability and reliability
- Test utilities and helpers (
test-utils.tsx) for consistent test setup and common operations - ESLint static analysis with TypeScript-aware rules for code consistency
- Prettier automatic code formatting ensuring uniform style across contributions
- AWS CDK infrastructure-as-code framework for provisioning and managing cloud resources
- CloudFront distribution for global CDN delivery with S3 bucket integration
- Automated deployments via AWS CDK with separate environment configurations (dev/qa/prd)
- Environment-based tagging of AWS resources for cost allocation and governance
- GitHub Actions CI/CD workflows for continuous integration, code quality checks, and automated deployments
- Storybook UI for isolated component development, documentation, and visual testing
- Inline code comments explaining complex logic and architectural decisions
- Project documentation guides covering configuration, infrastructure, shadcn/ui setup, and more
- Type definitions and JSDoc comments for better IDE intellisense and developer handoff
- Consistent file organization following established patterns enabling developers to navigate and extend the codebase confidently
- GitHub Copilot instructions (
copilot-instructions.md) providing comprehensive guidance for agentic AI coding - Project-specific coding standards documented for AI assistants including TypeScript conventions, React patterns, and testing practices
- Architecture and file organization guidance enabling AI agents to generate consistent, maintainable code
- Tool restrictions and best practices defined for AI-assisted code generation, refactoring, and documentation
- Seamless AI integration with VS Code for leveraging GitHub Copilot and other AI agents within your development workflow
This project was bootstrapped with the Vite React TypeScript template.
The application production technology stack includes:
- React - core web user interface library
- React Router Dom - declarative component routing
- shadcn/ui - common component library
- TanStack Query - asynchronous state management, caching, and data fetching
- Axios - http client
- React Hook Form - form management, validation, error handling, custom fields, etc.
- TailwindCSS - utility first CSS framework
- React Spring - animations
- Font Awesome + Lucide - iconography
- Google Fonts - typography
- React i18next - internationalization
- Zod - schema based validation
- Lodash - utility functions
- DayJS - date and time utility functions
- TanStack Table - advanced tables and datagrids
- Recharts - composable charting library for React
The application development technology stack includes:
- Vite - front end build tooling
- Vitest - core unit test framework
- React Testing Library - user-centric UI component testing
- Mock Service Worker - API mocking
- Storybook - UI component visualization and documentation
- TypeScript - the TypeScript language
The infrastructure technology stack includes:
- AWS CDK - framework for provisioning AWS cloud infrastructure
- Zod - schema based validation
- Jest: unit test framework
This repository uses trunk-based development. The latest code is located on the main branch. The main branch is always ready for deployment.
Features are developed on branches named feature/NNNNN-feature-name or NNNNN-feature-name which are created from the main branch. The feature name used in the branch contains an issue identifier or a short name, e.g. feature/123-do-something.
Releases are created on branches named release/MM.mm.pp which are created from the main branch. The release name follows the semantic versioning specification.
Hotfixes are created on branches named release/MM.mm.pp which are created from the appropriate release/MM.mm.pp branch.
A pull request must be opened requesting merge from any branch back to main. GitHub actions perform continuous integration, CI, checks against the PR source branch. At least one code review approval is required to complete the pull request.
See also: Feature flags
This project uses GitHub Issues.
The project includes configuration files for the Prettier and EditorConfig code formatters. This allows all project contributors to share the same code formatting rules.
Adjust the configuration as desired.
It is strongly recommended that you install Node Version Manager, nvm. Node Version Manager simplifies working on multiple projects with different versions of Node.js.
Open the repository in a browser. Follow the instructions to clone the repository to your local machine.
Open a terminal window and navigate to the project base directory. Issue the following command to install the version of Node and NPM used by the application:
# If you already have this version of Node, simply switch to it...
nvm use
# If you do NOT have this version of Node, install it...
nvm installNode Version Manager inspects the .nvmrc file in the project base directory and uses or installs the specified version of Node and the Node Package Manager, npm.
To install the project dependencies, issue the following commands at a terminal prompt in the project base directory:
# Switch to the project node version...
nvm use
# Install project dependencies
npm installThe installation is now complete! You may open the project in your favorite source code editor (we recommend Visual Studio Code).
We recommend the following VS Code extensions:
- Prettier - Code formatter (required)
- Tailwind CSS IntelliSense (required)
- GitHub Copilot (recommended)
- ESLint (recommended)
- Indent Rainbow (optional)
- GitLens (optional)
- Dotenv Official +Vault (optional)
- GitHub Actions (optional)
Install the Prettier extension to ensure that all project participants' contributions are formatted using the same rules. The extension leverages project-specific rules found in the .prettierrc file in the project base directory.
The Tailwind CSS IntelliSense extension is a must-have companion in all projects using Tailwind. The extension ensures that Tailwind CSS classes are named and ordered correctly and flags any conflicting classes.
See the Configuration Guide in the project docs for detailed information about application and infrastructure configuration.
Many of the scripts leverage the Vite CLI or the Vitest CLI. Read more about them in their respective official guides.
In the project base directory, the following commands are available to run.
Runs the app in the development mode. Open http://localhost:5173 to view it in the browser.
The page will reload when source files are saved.
Executes the unit tests once. See the Vitest documentation about running tests for more information.
Executes the unit tests once, producing a code coverage report.
Launches the test runner in the interactive watch mode.
Executes the test runner in CI mode and produces a coverage report. With CI mode enabled, the test runner executes all tests one time silently and prints a summary report to the console. A code coverage report is printed to the console immediately following the test summary.
A detailed test coverage report is created in the ./coverage directory. Additional report formats, for example a JSON summary report, are produced which may be injested by external reporting tools.
NOTE: This is the command which should be utilized by CI/CD platforms.
Executes the tests and opens the Vitest UI to view and interact with the unit tests.
Builds the app for production to the dist folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
See the official guide for more information about building for production and deploying a static site.
Runs the Prettier static code analysis and fixes problems identified to comply with Prettier formatting rules. See .prettierrc and .prettierignore.
Runs the Prettier static code analysis and prints the results to the console.
Runs the eslint static code analysis and prints the results to the console.
Runs the eslint static code analysis and updates source code to fix problems.
Starts the Storybook UI. Open http://localhost:6006 to view it in the browser.
Build a static version the Storybook UI which may be deployed to a CDN or HTTP server.