{"id":14969356,"url":"https://github.com/marcoturi/react-redux-boilerplate","last_synced_at":"2026-05-16T06:15:34.328Z","repository":{"id":217399884,"uuid":"743776114","full_name":"marcoturi/react-redux-boilerplate","owner":"marcoturi","description":"A meticulously crafted, extensible, and robust architecture for constructing production-grade React 19 applications 🚀","archived":false,"fork":false,"pushed_at":"2026-02-03T05:31:13.000Z","size":9982,"stargazers_count":97,"open_issues_count":10,"forks_count":15,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-03T16:43:41.060Z","etag":null,"topics":["cucumber","eslint","playwright","prettier","radix-ui","react","redux","semantic-release","shadcn-ui","tailwindcss","typescript","vite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcoturi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-16T00:52:27.000Z","updated_at":"2026-02-03T05:31:15.000Z","dependencies_parsed_at":"2025-12-15T21:18:28.083Z","dependency_job_id":null,"html_url":"https://github.com/marcoturi/react-redux-boilerplate","commit_stats":{"total_commits":794,"total_committers":3,"mean_commits":264.6666666666667,"dds":"0.27833753148614615","last_synced_commit":"690579bda839c03b3d41a991e77256ee4cbb54df"},"previous_names":["marcoturi/react-redux-boilerplate"],"tags_count":336,"template":true,"template_full_name":null,"purl":"pkg:github/marcoturi/react-redux-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoturi%2Freact-redux-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoturi%2Freact-redux-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoturi%2Freact-redux-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoturi%2Freact-redux-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcoturi","download_url":"https://codeload.github.com/marcoturi/react-redux-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoturi%2Freact-redux-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29229420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T12:03:03.049Z","status":"ssl_error","status_checked_at":"2026-02-08T12:02:56.077Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cucumber","eslint","playwright","prettier","radix-ui","react","redux","semantic-release","shadcn-ui","tailwindcss","typescript","vite"],"created_at":"2024-09-24T13:41:44.479Z","updated_at":"2026-04-01T16:53:35.888Z","avatar_url":"https://github.com/marcoturi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![React Redux Boilerplate](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/react_redux_boilerplate.jpg?raw=true)\n\n[![MIT License](https://img.shields.io/github/license/marcoturi/react-redux-boilerplate)](https://github.com/marcoturi/react-redux-boilerplate/blob/main/LICENSE) ![CodeQL](https://img.shields.io/github/actions/workflow/status/marcoturi/react-redux-boilerplate/codeql-analysis.yml?label=CodeQL) ![Release](https://img.shields.io/github/actions/workflow/status/marcoturi/react-redux-boilerplate/release.yml?label=Release)\n\nA production-ready, batteries-included starter template for building long-lived React applications. It provides opinionated guidelines for the key decisions every team faces at scale:\n\n- **Folder structure** -- [Vertical slice architecture](#folder-structure-and-code-organization) for maintainability and easy extraction into a monorepo.\n- **State management** -- [Redux Toolkit 2](#state-management-why-redux) for predictable, traceable state with clear separation of concerns.\n- **Release automation** -- [Semantic-release](#release-system) for hands-off versioning, changelogs, and tags.\n- **Code quality** -- [Biome](#format-and-style) for blazing-fast linting and formatting in a single tool.\n- **UI system** -- [Radix + shadcn/ui + Tailwind CSS 4](#ui-components-and-style-system) for accessible, headless, minimal-dependency components.\n- **Testing** -- [Vitest + Testing Library](#testing) for unit/integration, [Cucumber + Playwright](#testing) for E2E.\n- **Error tracking** -- [Sentry](#error-handling-and-analytics) with Redux state replay for production debugging.\n\n## Features\n\n| Category | Stack |\n|---|---|\n| Build | [Vite 7](https://vitejs.dev/) + [React 19](https://react.dev/) + [SWC](https://github.com/vitejs/vite-plugin-react-swc) + [pnpm](https://pnpm.io/) + [TypeScript 5.9](https://www.typescriptlang.org) |\n| State | [Redux Toolkit 2](https://redux-toolkit.js.org/) (includes RTK Query, Immer, Reselect) |\n| UI | [Radix](https://www.radix-ui.com/) + [shadcn/ui](https://ui.shadcn.com/) + [Tailwind CSS 4](https://tailwindcss.com/) |\n| Linting \u0026 formatting | [Biome](https://biomejs.dev/) |\n| Release | [Husky](https://github.com/typicode/husky) + [Commitlint](https://commitlint.js.org/) + [Semantic-release](https://github.com/semantic-release/semantic-release) |\n| API mocking | [MSW](https://mswjs.io/) (browser + test, powered by [@mswjs/data](https://github.com/mswjs/data)) |\n| Unit \u0026 integration tests | [Vitest 4](https://vitest.dev/) + [Testing Library](https://testing-library.com/) |\n| E2E tests | [Cucumber](https://cucumber.io/docs/installation/javascript/) + [Playwright](https://playwright.dev/) |\n| Monitoring | [Sentry](https://github.com/getsentry/sentry-javascript/tree/master/packages/react) |\n| Security | [CodeQL](https://github.com/github/codeql-action) analysis on every push/PR |\n| AI-Ready | [AGENTS.md](AGENTS.md) — architecture rules and coding conventions for AI assistants |\n\n## Getting Started\n\n### Prerequisites\n\n| Requirement | Version | Notes |\n|---|---|---|\n| Node.js | 24.x | Defined in `.nvmrc`. Use [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm): `fnm use` / `nvm use` |\n| pnpm | 10.x | `corepack enable` to activate the bundled version |\n\n### Quick start\n\n```bash\nnpx degit marcoturi/react-redux-boilerplate my-app\ncd my-app\n\npnpm install       # Install dependencies\npnpm create:env    # Create .env from .env.example\npnpm dev           # Start dev server at http://localhost:5173\n```\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `pnpm dev` | Start development server with HMR |\n| `pnpm build` | Type-check + production build (output in `dist/`) |\n| `pnpm preview` | Preview the production build locally |\n| `pnpm test` | Run unit and integration tests (Vitest) |\n| `pnpm test:coverage` | Run tests with V8 coverage report |\n| `pnpm e2e:local` | Run E2E tests (start dev server first in another terminal) |\n| `pnpm e2e:debug` | Run only `@only`-tagged E2E scenarios with `--fail-fast` |\n| `pnpm check` | Biome lint/format check + TypeScript type check |\n| `pnpm check:fix` | Auto-fix lint/format issues, then type check |\n| `pnpm format` | Format all files with Biome |\n| `pnpm lint` | Lint all files with Biome |\n| `pnpm type:check` | TypeScript type check only (`tsc --noEmit`) |\n| `pnpm update:interactive` | Update dependencies interactively |\n\n## Folder Structure and Code Organization\n\n\u003e **TL;DR** -- Embrace [vertical slice architecture](https://www.jimmybogard.com/vertical-slice-architecture/). Each feature owns its components, state, API calls, and tests.\n\n```\nsrc/\n├── main.tsx                  → App entry point\n├── AppProvider.tsx            → Providers (Suspense, Redux, Radix Theme, ErrorBoundary, Router)\n├── assets/                   → Static files (images, fonts, etc.)\n├── routes/                   → Route definitions + page components (lazy-loaded via React.lazy)\n│   ├── index.tsx             → Route tree\n│   ├── Home/\n│   └── Subscriptions/\n├── shared/\n│   ├── config/               → Environment variables, Sentry setup\n│   ├── helpers/              → Generic utilities (localStorage, style utils, etc.)\n│   └── store/                → Redux store setup, base RTK Query API, typed hooks\n├── UI/\n│   ├── Elements/             → Reusable UI components (shadcn/ui based)\n│   └── Layout/               → Page layouts, Header, global CSS\n├── features/                 → Feature slices\n│   └── \u003cfeature\u003e/\n│       ├── store/            → Redux slice, selectors, effects, types, specs\n│       ├── components/       → Feature-specific React components\n│       ├── hooks/            → Feature-specific React hooks\n│       └── services/         → Services consumed by Redux\n└── test/                     → MSW handlers, mock DB, test utilities\n```\n\nWhy vertical slices over alternatives like [Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/) or [Feature-Sliced Design](https://feature-sliced.design/)?\n\n1. **Less navigation** -- Feature code lives in one folder, not scattered across layers.\n2. **Easy extraction** -- A feature folder can move to a monorepo package with minimal refactoring (helped by `@/` path aliases).\n3. **Parallel development** -- Teams can work on different features without conflicts.\n4. **Simpler testing** -- Each feature can be tested in isolation.\n\n### FAQ\n\n**Q: What if the `features/` folder grows too large?**\nA: Group related features inside scope folders (e.g., `features/billing/invoices/`). Aim for no more than ~6 folders at the same level.\n\n**Q: I only have a Redux slice with no components. Where does it go?**\nA: Still in `features/`. It may grow components later, and a consistent location makes it easy to find.\n\n## State Management: Why Redux?\n\n\u003e **TL;DR** -- Redux keeps state changes predictable and traceable. Combined with Sentry, you get full replay of every user action in production.\n\nRedux Toolkit 2 enforces a clear separation of responsibilities:\n\n| Layer | Responsibility |\n|---|---|\n| **Components** | Dispatch actions, display data via selectors. Zero business logic. |\n| **Selectors \u0026 Reducers** | Business and domain logic. Pure functions -- easy to test and compose. |\n| **RTK Query / Thunks / Listener Middleware** | Side effects (API calls, async flows, cross-slice reactions). |\n\n![Redux flow](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/redux_architecture.gif?raw=true)\n\nNewer state management solutions often trade boilerplate for ambiguity about _where_ business logic belongs. Without a clear, project-defined location, domain logic gravitates into UI components -- making them large, hard to test, and hard to maintain.\n\nWith Redux, typed hooks (`useAppDispatch`, `useAppSelector`) and pure selectors keep components thin and logic centralized.\n\n## UI Components and Style System\n\n\u003e **TL;DR** -- Pick a headless UI library with few dependencies. Encapsulate it so you can replace it later.\n\n### Radix + shadcn/ui\n\n- **Minimal dependencies** -- Components are copied into your project, not installed as a black-box package.\n- **Separation of design and behavior** -- shadcn/ui provides unstyled primitives you own and customize.\n- **Accessible by default** -- All components adhere to [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/) patterns. See [this talk](https://www.youtube.com/watch?v=pcMYcjtWwVI) for details.\n\nComponents live in `src/UI/Elements/` and are managed via the [shadcn CLI](https://ui.shadcn.com/docs/cli) (`npx shadcn@latest add \u003ccomponent\u003e`).\n\n### Tailwind CSS 4\n\n[Tailwind CSS 4](https://tailwindcss.com/blog/tailwindcss-v4) is used via the `@tailwindcss/vite` plugin -- no PostCSS config needed. Key benefits:\n\n- **Utility-first** -- Consistent styling with zero CSS files to maintain.\n- **Design tokens** -- Theme defined as CSS variables in `src/UI/Layout/global.css` using `@theme inline`.\n- **Built-in responsive and a11y** -- First-class responsive utilities and accessibility helpers.\n- **Tree-shaken** -- Only used classes end up in the production bundle.\n\n## Testing\n\n### Unit and integration tests\n\nTests use **Vitest 4** with **Testing Library** and **jsdom**. Test files live next to the code they test with a `.spec.ts` / `.spec.tsx` suffix.\n\nAPI mocking uses **MSW** with `@mswjs/data` for a realistic, in-memory database that powers both development and tests.\n\n### E2E tests\n\nE2E tests use **Cucumber** (Gherkin syntax) with **Playwright** as the browser automation engine.\n\n```bash\n# First time setup\npnpm exec playwright install\n\n# Run (dev server must be running)\npnpm dev \u0026\npnpm e2e:local\n```\n\n### Build optimization\n\nProduction builds use vendor chunk splitting for optimal caching:\n\n| Chunk | Contents |\n|---|---|\n| `vendor-react` | React, React DOM, React Router, React Redux |\n| `vendor-redux` | Redux Toolkit (RTK Query, Immer, Reselect) |\n| `vendor-radix` | Radix UI primitives and themes |\n| `vendor-sentry` | Sentry SDK |\n| `vendor-ui` | CVA, clsx, tailwind-merge, Lucide icons |\n\nRoutes are **lazy-loaded** via `React.lazy()` for automatic code splitting.\n\n## Release System\n\n\u003e **TL;DR** -- Merge to `main` and everything else is automated.\n\nThe release pipeline is fully automated with [semantic-release](https://semantic-release.gitbook.io/semantic-release/):\n\n1. Developer merges a PR into `main`.\n2. CI runs tests and E2E.\n3. semantic-release analyzes commits, determines the version bump, generates the changelog, creates a GitHub release and git tag.\n\nNo manual version bumps. No manual changelog edits.\n\n### Toolkit\n\n| Tool | Purpose |\n|---|---|\n| [Commitlint](https://commitlint.js.org/) | Enforces [Conventional Commits](https://www.conventionalcommits.org/) format (`feat:`, `fix:`, `chore:`, etc.) |\n| [Husky](https://github.com/typicode/husky) | Runs commitlint + tests on pre-commit |\n| [Semantic-release](https://github.com/semantic-release/semantic-release) | Automates versioning, changelogs, GitHub releases, and git tags |\n\n### Why Conventional Commits?\n\n- **Automated changelogs** -- Commit messages drive what goes into `CHANGELOG.md`.\n- **Semantic versioning** -- `feat` = minor, `fix` = patch, `BREAKING CHANGE` = major.\n- **Readable history** -- Anyone can scan `git log` and understand the nature of each change at a glance.\n\n## Format and Style\n\n\u003e **TL;DR** -- One tool, one config. [Biome](https://biomejs.dev/) handles linting, formatting, and import sorting.\n\nBiome replaces the traditional ESLint + Prettier combo with a single, Rust-powered tool. It provides:\n\n- 300+ lint rules covering correctness, style, complexity, and suspicious patterns\n- Built-in formatter for TypeScript, JSX, JSON, and CSS\n- Automatic import sorting and `import type` enforcement\n- Sub-second execution on the entire codebase\n\nConfiguration lives in [`biome.json`](./biome.json). The pre-commit hook runs `biome check --staged` automatically.\n\n## Error Handling and Analytics\n\n\u003e **TL;DR** -- When Redux is used correctly, every user action is traceable in production.\n\n[Sentry](https://github.com/getsentry/sentry-javascript/tree/master/packages/react) is integrated with the Redux store enhancer, which means:\n\n- **In development** -- Redux DevTools shows every state transition in real time.\n- **In production** -- Sentry captures the full sequence of dispatched Redux actions leading up to an error, plus the application state at the moment of the crash.\n\n![Sentry redux actions](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/redux%20actions.png?raw=true)\n\nThis allows you to reproduce issues by replaying the exact action sequence, or even rehydrating the state snapshot:\n\n![Sentry redux state](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/redux%20state.png?raw=true)\n\n## Recommended Libraries\n\nThese are not included in the boilerplate but are recommended additions depending on your needs:\n\n| Need | Recommendation | Notes |\n|---|---|---|\n| Dates | [date-fns](https://github.com/date-fns/date-fns) | Modular, tree-shakeable. [Moment.js is in maintenance mode](https://momentjs.com/docs/#/-project-status/). |\n| Forms | [react-hook-form](https://github.com/react-hook-form/react-hook-form) | Zero dependencies, excellent performance and DX. |\n\n## Contributing\n\nContributions are welcome! To get started:\n\n1. Clone the repo and install dependencies (`pnpm install`)\n2. Create a branch: `git checkout -b feat/your-feature`\n3. Make your changes\n4. Verify: `pnpm check` (lint, format, types) and `pnpm test`\n5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (enforced by the pre-commit hook)\n6. Open a Pull Request\n\n\u003e This project includes an [`AGENTS.md`](./AGENTS.md) file with detailed instructions for AI coding agents.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoturi%2Freact-redux-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcoturi%2Freact-redux-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoturi%2Freact-redux-boilerplate/lists"}