react-redux-boilerplate - GitLite

KO | EN

gitlite — search

#javascript #python #react #ai #machine-learning #rust #deep-learning #linux #docker #macos #windows #vue #security #mcp

react-redux-boilerplate

(★ 103)

A meticulously crafted, extensible, and robust architecture for constructing production-grade React 19 applications 🚀

파일 탐색기

최종 버전 다운로드 (.zip)

- - codeql-analysis.yml
  - release.yml
- commit-msg
- pre-commit
- install-state.gz
- - react_redux_boilerplate.jpg
  - redux actions.png
  - redux state.png
  - redux_architecture.gif
- - app.feature
  - subscription.feature
- - app.po.ts
  - subscription.po.ts
- - app.steps.ts
  - subscription.steps.ts
- - common-hooks.ts
  - config.ts
  - custom-world.ts
- tsconfig.e2e.json
- mockServiceWorker.js
- vitest.setup.ts
- - index.tsx
- - browser.ts
  - config.ts
  - db.ts
  - index.ts
- AppProvider.tsx
- main.tsx
- vite-env.d.ts
.editorconfig
.env.example
.gitignore
.nvmrc
.releaserc
AGENTS.md
biome.json
CHANGELOG.md
CLAUDE.md
commitlint.config.cjs
components.json
cucumber.mjs
index.html
LICENSE
package.json
pnpm-lock.yaml
README.md
renovate.json
tailwind.config.mjs
tsconfig.app.json
tsconfig.json
tsconfig.node.json
vite.config.mts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/marcoturi/react-redux-boilerplate

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd react-redux-boilerplate

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

pnpm install # Install dependencies

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

pnpm create:env # Create .env from .env.example

이 명령어를 터미널에 그대로 입력해 실행하세요.

pnpm dev # Start dev server at http://localhost:5173

개발/실행 서버를 켭니다.

pnpm exec playwright install

이 명령어를 터미널에 그대로 입력해 실행하세요.

pnpm dev &

개발/실행 서버를 켭니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![React Redux Boilerplate](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/react_redux_boilerplate.jpg?raw=true)

[![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)

A 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:

- **Folder structure** -- [Vertical slice architecture](#folder-structure-and-code-organization) for maintainability and easy extraction into a monorepo.
- **State management** -- [Redux Toolkit 2](#state-management-why-redux) for predictable, traceable state with clear separation of concerns.
- **Release automation** -- [Semantic-release](#release-system) for hands-off versioning, changelogs, and tags.
- **Code quality** -- [Biome](#format-and-style) for blazing-fast linting and formatting in a single tool.
- **UI system** -- [Radix + shadcn/ui + Tailwind CSS 4](#ui-components-and-style-system) for accessible, headless, minimal-dependency components.
- **Testing** -- [Vitest + Testing Library](#testing) for unit/integration, [Cucumber + Playwright](#testing) for E2E.
- **Error tracking** -- [Sentry](#error-handling-and-analytics) with Redux state replay for production debugging.

## Features

| Category | Stack |
|---|---|
| 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) |
| State | [Redux Toolkit 2](https://redux-toolkit.js.org/) (includes RTK Query, Immer, Reselect) |
| UI | [Radix](https://www.radix-ui.com/) + [shadcn/ui](https://ui.shadcn.com/) + [Tailwind CSS 4](https://tailwindcss.com/) |
| Linting & formatting | [Biome](https://biomejs.dev/) |
| Release | [Husky](https://github.com/typicode/husky) + [Commitlint](https://commitlint.js.org/) + [Semantic-release](https://github.com/semantic-release/semantic-release) |
| API mocking | [MSW](https://mswjs.io/) (browser + test, powered by [@mswjs/data](https://github.com/mswjs/data)) |
| Unit & integration tests | [Vitest 4](https://vitest.dev/) + [Testing Library](https://testing-library.com/) |
| E2E tests | [Cucumber](https://cucumber.io/docs/installation/javascript/) + [Playwright](https://playwright.dev/) |
| Monitoring | [Sentry](https://github.com/getsentry/sentry-javascript/tree/master/packages/react) |
| Security | [CodeQL](https://github.com/github/codeql-action) analysis on every push/PR |
| AI-Ready | [AGENTS.md](AGENTS.md) — architecture rules and coding conventions for AI assistants |

## Getting Started

### Prerequisites

| Requirement | Version | Notes |
|---|---|---|
| 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` |
| pnpm | 10.x | `corepack enable` to activate the bundled version |

### Quick start

```bash
npx degit marcoturi/react-redux-boilerplate my-app
cd my-app

pnpm install       # Install dependencies
pnpm create:env    # Create .env from .env.example
pnpm dev           # Start dev server at http://localhost:5173
```

### Commands

| Command | Description |
|---|---|
| `pnpm dev` | Start development server with HMR |
| `pnpm build` | Type-check + production build (output in `dist/`) |
| `pnpm preview` | Preview the production build locally |
| `pnpm test` | Run unit and integration tests (Vitest) |
| `pnpm test:coverage` | Run tests with V8 coverage report |
| `pnpm e2e:local` | Run E2E tests (start dev server first in another terminal) |
| `pnpm e2e:debug` | Run only `@only`-tagged E2E scenarios with `--fail-fast` |
| `pnpm check` | Biome lint/format check + TypeScript type check |
| `pnpm check:fix` | Auto-fix lint/format issues, then type check |
| `pnpm format` | Format all files with Biome |
| `pnpm lint` | Lint all files with Biome |
| `pnpm type:check` | TypeScript type check only (`tsc --noEmit`) |
| `pnpm update:interactive` | Update dependencies interactively |

## Folder Structure and Code Organization

> **TL;DR** -- Embrace [vertical slice architecture](https://www.jimmybogard.com/vertical-slice-architecture/). Each feature owns its components, state, API calls, and tests.

```
src/
├── main.tsx                  → App entry point
├── AppProvider.tsx            → Providers (Suspense, Redux, Radix Theme, ErrorBoundary, Router)
├── assets/                   → Static files (images, fonts, etc.)
├── routes/                   → Route definitions + page components (lazy-loaded via React.lazy)
│   ├── index.tsx             → Route tree
│   ├── Home/
│   └── Subscriptions/
├── shared/
│   ├── config/               → Environment variables, Sentry setup
│   ├── helpers/              → Generic utilities (localStorage, style utils, etc.)
│   └── store/                → Redux store setup, base RTK Query API, typed hooks
├── UI/
│   ├── Elements/             → Reusable UI components (shadcn/ui based)
│   └── Layout/               → Page layouts, Header, global CSS
├── features/                 → Feature slices
│   └── <feature>/
│       ├── store/            → Redux slice, selectors, effects, types, specs
│       ├── components/       → Feature-specific React components
│       ├── hooks/            → Feature-specific React hooks
│       └── services/         → Services consumed by Redux
└── test/                     → MSW handlers, mock DB, test utilities
```

Why vertical slices over alternatives like [Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/) or [Feature-Sliced Design](https://feature-sliced.design/)?

1. **Less navigation** -- Feature code lives in one folder, not scattered across layers.
2. **Easy extraction** -- A feature folder can move to a monorepo package with minimal refactoring (helped by `@/` path aliases).
3. **Parallel development** -- Teams can work on different features without conflicts.
4. **Simpler testing** -- Each feature can be tested in isolation.

### FAQ

**Q: What if the `features/` folder grows too large?**
A: Group related features inside scope folders (e.g., `features/billing/invoices/`). Aim for no more than ~6 folders at the same level.

**Q: I only have a Redux slice with no components. Where does it go?**
A: Still in `features/`. It may grow components later, and a consistent location makes it easy to find.

## State Management: Why Redux?

> **TL;DR** -- Redux keeps state changes predictable and traceable. Combined with Sentry, you get full replay of every user action in production.

Redux Toolkit 2 enforces a clear separation of responsibilities:

| Layer | Responsibility |
|---|---|
| **Components** | Dispatch actions, display data via selectors. Zero business logic. |
| **Selectors & Reducers** | Business and domain logic. Pure functions -- easy to test and compose. |
| **RTK Query / Thunks / Listener Middleware** | Side effects (API calls, async flows, cross-slice reactions). |

![Redux flow](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/redux_architecture.gif?raw=true)

Newer 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.

With Redux, typed hooks (`useAppDispatch`, `useAppSelector`) and pure selectors keep components thin and logic centralized.

## UI Components and Style System

> **TL;DR** -- Pick a headless UI library with few dependencies. Encapsulate it so you can replace it later.

### Radix + shadcn/ui

- **Minimal dependencies** -- Components are copied into your project, not installed as a black-box package.
- **Separation of design and behavior** -- shadcn/ui provides unstyled primitives you own and customize.
- **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.

Components live in `src/UI/Elements/` and are managed via the [shadcn CLI](https://ui.shadcn.com/docs/cli) (`npx shadcn@latest add <component>`).

### Tailwind CSS 4

[Tailwind CSS 4](https://tailwindcss.com/blog/tailwindcss-v4) is used via the `@tailwindcss/vite` plugin -- no PostCSS config needed. Key benefits:

- **Utility-first** -- Consistent styling with zero CSS files to maintain.
- **Design tokens** -- Theme defined as CSS variables in `src/UI/Layout/global.css` using `@theme inline`.
- **Built-in responsive and a11y** -- First-class responsive utilities and accessibility helpers.
- **Tree-shaken** -- Only used classes end up in the production bundle.

## Testing

### Unit and integration tests

Tests use **Vitest 4** with **Testing Library** and **jsdom**. Test files live next to the code they test with a `.spec.ts` / `.spec.tsx` suffix.

API mocking uses **MSW** with `@mswjs/data` for a realistic, in-memory database that powers both development and tests.

### E2E tests

E2E tests use **Cucumber** (Gherkin syntax) with **Playwright** as the browser automation engine.

```bash
# First time setup
pnpm exec playwright install

# Run (dev server must be running)
pnpm dev &
pnpm e2e:local
```

### Build optimization

Production builds use vendor chunk splitting for optimal caching:

| Chunk | Contents |
|---|---|
| `vendor-react` | React, React DOM, React Router, React Redux |
| `vendor-redux` | Redux Toolkit (RTK Query, Immer, Reselect) |
| `vendor-radix` | Radix UI primitives and themes |
| `vendor-sentry` | Sentry SDK |
| `vendor-ui` | CVA, clsx, tailwind-merge, Lucide icons |

Routes are **lazy-loaded** via `React.lazy()` for automatic code splitting.

## Release System

> **TL;DR** -- Merge to `main` and everything else is automated.

The release pipeline is fully automated with [semantic-release](https://semantic-release.gitbook.io/semantic-release/):

1. Developer merges a PR into `main`.
2. CI runs tests and E2E.
3. semantic-release analyzes commits, determines the version bump, generates the changelog, creates a GitHub release and git tag.

No manual version bumps. No manual changelog edits.

### Toolkit

| Tool | Purpose |
|---|---|
| [Commitlint](https://commitlint.js.org/) | Enforces [Conventional Commits](https://www.conventionalcommits.org/) format (`feat:`, `fix:`, `chore:`, etc.) |
| [Husky](https://github.com/typicode/husky) | Runs commitlint + tests on pre-commit |
| [Semantic-release](https://github.com/semantic-release/semantic-release) | Automates versioning, changelogs, GitHub releases, and git tags |

### Why Conventional Commits?

- **Automated changelogs** -- Commit messages drive what goes into `CHANGELOG.md`.
- **Semantic versioning** -- `feat` = minor, `fix` = patch, `BREAKING CHANGE` = major.
- **Readable history** -- Anyone can scan `git log` and understand the nature of each change at a glance.

## Format and Style

> **TL;DR** -- One tool, one config. [Biome](https://biomejs.dev/) handles linting, formatting, and import sorting.

Biome replaces the traditional ESLint + Prettier combo with a single, Rust-powered tool. It provides:

- 300+ lint rules covering correctness, style, complexity, and suspicious patterns
- Built-in formatter for TypeScript, JSX, JSON, and CSS
- Automatic import sorting and `import type` enforcement
- Sub-second execution on the entire codebase

Configuration lives in [`biome.json`](./biome.json). The pre-commit hook runs `biome check --staged` automatically.

## Error Handling and Analytics

> **TL;DR** -- When Redux is used correctly, every user action is traceable in production.

[Sentry](https://github.com/getsentry/sentry-javascript/tree/master/packages/react) is integrated with the Redux store enhancer, which means:

- **In development** -- Redux DevTools shows every state transition in real time.
- **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.

![Sentry redux actions](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/redux%20actions.png?raw=true)

This allows you to reproduce issues by replaying the exact action sequence, or even rehydrating the state snapshot:

![Sentry redux state](https://github.com/marcoturi/react-redux-boilerplate/blob/main/doc/images/redux%20state.png?raw=true)

## Recommended Libraries

These are not included in the boilerplate but are recommended additions depending on your needs:

| Need | Recommendation | Notes |
|---|---|---|
| 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/). |
| Forms | [react-hook-form](https://github.com/react-hook-form/react-hook-form) | Zero dependencies, excellent performance and DX. |

## Contributing

Contributions are welcome! To get started:

1. Clone the repo and install dependencies (`pnpm install`)
2. Create a branch: `git checkout -b feat/your-feature`
3. Make your changes
4. Verify: `pnpm check` (lint, format, types) and `pnpm test`
5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (enforced by the pre-commit hook)
6. Open a Pull Request

> This project includes an [`AGENTS.md`](./AGENTS.md) file with detailed instructions for AI coding agents.

## License

[MIT](./LICENSE)