bulletproof-react-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bulletproof React architecture

Bulletproof React架构

Source: bulletproof-react by Alan Alickovic, MIT licensed. The upstream repo is now a monorepo with three app variants:

apps/react-vite/

apps/nextjs-app/

apps/nextjs-pages/

. This skill follows the

react-vite

version as primary. See NOTICE.md for the license and adaptation note.

来源：Alan Alickovic 开发的 bulletproof-react，采用MIT许可证。上游仓库现已成为包含三个应用变体的单体仓库：

apps/react-vite/

、

apps/nextjs-app/

、

apps/nextjs-pages/

。本技能主要遵循

react-vite

版本。有关许可证和适配说明，请查看 NOTICE.md。

Vocabulary

术语定义

Use these terms exactly. Don't substitute "module," "service," or "component" where the repo means "feature."

Feature: a self-contained folder under
```
src/features/
```
, holding everything specific to one piece of product functionality: its own
```
api/
```
,
```
components/
```
,
```
hooks/
```
,
```
stores/
```
,
```
types/
```
.
Shared code: anything in the top-level
```
components/
```
,
```
hooks/
```
,
```
lib/
```
,
```
types/
```
,
```
utils/
```
. Usable from any feature or from the app layer. Never depends on a feature.
App layer:
```
src/app/
```
, meaning routes, root component, providers, router config. The only layer allowed to compose multiple features together.

请严格使用以下术语，不要用“module（模块）”、“service（服务）”或“component（组件）”替代仓库中所指的“feature（功能）”。

Feature（功能）：
```
src/features/
```
下的独立文件夹，包含某一项产品功能的所有相关内容：专属的
```
api/
```
、
```
components/
```
、
```
hooks/
```
、
```
stores/
```
、
```
types/
```
。
Shared code（共享代码）：顶层
```
components/
```
、
```
hooks/
```
、
```
lib/
```
、
```
types/
```
、
```
utils/
```
中的所有内容。可被任意功能或应用层使用，绝不依赖于某个功能。
App layer（应用层）：
```
src/app/
```
，包含路由、根组件、提供者、路由配置。是唯一允许组合多个功能的层级。

Rules of thumb

经验法则

A scannable summary. Each one is expanded in the reference files linked below.

Rule	What it means
No cross-feature imports	`features/comments` importing from `features/discussions` is always a bug. Promote to shared code.
Code flows one direction	shared → features → app. Never the reverse. Nothing in shared imports from a feature or app.
Match state to category first	Component, app, server cache, form, and URL state are five different problems with five different tools.

以下是便于快速浏览的总结，每条规则的详细说明可查看下方链接的参考文件。

规则	含义
禁止跨功能导入	`features/comments` 导入 `features/discussions` 的内容永远是错误的。应将共享逻辑提升至共享代码层。
代码单向流动	共享代码 → 功能 → 应用层。绝不反向流动。共享代码中不得导入任何功能或应用层的内容。
先匹配状态分类	组件状态、应用状态、服务器缓存状态、表单状态和URL状态是五种不同的问题，需使用五种不同的工具处理。

Before you apply this

应用前提

This pays off when the app has multiple features, multiple contributors, or a timeline longer than a few months. It does not pay off on a five-file prototype, a one-off script, or a throwaway component.

Check scale before reaching for structure:

One feature, a handful of files? Keep
```
src/
```
flat. The full feature-folder skeleton for one component and one fetch call is the failure mode this skill exists to prevent, not the goal.
Already have a working pattern in this codebase? Match it. Two competing conventions cost more than either one's imperfections.
Unsure whether a rule applies? Ask what breaks without it. If nothing breaks, skip it.

The reference files below aren't a checklist. Each solves one problem. Read the one that matches the problem in front of you.

当应用包含多个功能、有多位贡献者，或项目周期超过数月时，本规范才能发挥价值。对于仅含五个文件的原型、一次性脚本或临时组件，本规范并不适用。

在采用本结构前，请先评估项目规模：

仅一个功能、少量文件？ 保持
```
src/
```
目录扁平化。为单个组件和一次请求调用搭建完整的功能文件夹框架，正是本技能要避免的错误做法，而非目标。
代码库已有可行的模式？ 遵循现有模式。两种相互冲突的规范造成的成本，远高于任一规范自身的缺陷。
不确定某条规则是否适用？ 思考如果不遵循这条规则会出现什么问题。如果没有问题，就跳过它。

下方的参考文件并非检查清单，每个文件只解决一个问题。阅读与当前问题匹配的文件即可。

When this skill doesn't apply

不适用场景

Skip it for non-structural work: fixing a bug, writing a single function, styling a component. If the question isn't "where does this go" or "how should this be organized," you don't need it.

This skill assumes you apply judgment about scale. If you catch yourself building every subfolder from the project-structure file just because it's listed, stop and ask whether this feature actually needs all of them.

非结构相关的工作无需使用本规范：修复Bug、编写单个函数、为组件添加样式。如果问题不是“这个应该放在哪里”或“应该如何组织这个”，则不需要本规范。

本技能要求你根据规模做出判断。如果你发现自己只是因为参考文件中列出了所有子文件夹，就为某个功能搭建完整的框架，请停下来思考该功能是否真的需要所有这些文件夹。

Gotchas

常见误区

The mistakes the agent makes most often:

Using
react-router-dom
. The upstream repo moved to
```
react-router
```
v7 (library mode). Import from
```
react-router
```
, not
```
react-router-dom
```
.
Creating a store for state that never leaves one component. That's component state, not application state. Start with
```
useState
```
. Promote to a store only when another component actually needs the same value.
Building the full feature skeleton for a small feature. A feature with one component and one fetch call doesn't need
```
api/
```
,
```
components/
```
,
```
hooks/
```
,
```
stores/
```
,
```
types/
```
. Just
```
api/
```
and
```
components/
```
is fine. You can add folders later when they earn their keep.
Putting server cache state in Zustand, Redux, or any general-purpose store. Server data belongs in TanStack Query's cache, not in a hand-rolled store. The caching, invalidation, and refetching logic a query client gives you for free is the whole reason it exists.
Barrel files (index.ts that re-exports everything). They break tree shaking in Vite. Import directly from the file you need.
Cross-feature imports. Worth repeating:
```
features/comments
```
reaching into
```
features/discussions
```
is never the right call. If two features share logic, promote it to shared code.
Flagging a single
api/
file as over-engineering. One endpoint in
```
features/x/api/
```
is how the API layer starts, not a violation. The over-engineering check targets empty
```
stores/
```
, single-use
```
hooks/
```
, and single-type
```
types/
```
folders, or truly one-off inline fetches outside a feature entirely - not a lone
```
api/
```
file already living inside a real feature folder.
Reaching for
useEffect
to transform data or handle user events. If something can be calculated from existing props or state, calculate it during rendering. If logic runs because the user did something, put it in the event handler. Effects are for synchronizing with external systems only. See reference/effects.md.

Agent最常犯的错误：

使用
react-router-dom
：上游仓库已迁移至
```
react-router
```
v7（库模式）。请从
```
react-router
```
导入，而非
```
react-router-dom
```
。
为仅存在于单个组件中的状态创建store：这属于组件状态，而非应用状态。先使用
```
useState
```
，只有当其他组件确实需要相同值时，再升级为store。
为小型功能搭建完整的功能框架：仅包含一个组件和一次请求调用的功能，不需要
```
api/
```
、
```
components/
```
、
```
hooks/
```
、
```
stores/
```
、
```
types/
```
全部文件夹。只需保留
```
api/
```
和
```
components/
```
即可。当需要时，你可以再添加其他文件夹。
将服务器缓存状态存入Zustand、Redux或任何通用store：服务器数据应存入TanStack Query的缓存，而非手动构建的store。查询客户端提供的缓存、失效和重新获取逻辑是其核心价值所在。
桶文件（重新导出所有内容的index.ts）：它们会破坏Vite的摇树优化。直接从所需文件导入即可。
跨功能导入：再次强调：
```
features/comments
```
导入
```
features/discussions
```
的内容永远不是正确的做法。如果两个功能共享逻辑，应将其提升至共享代码层。
将单个
api/
文件标记为过度设计：
```
features/x/api/
```
中的一个端点是API层的起点，而非违规。过度设计检查针对的是空的
```
stores/
```
、仅使用一次的
```
hooks/
```
、仅包含单个类型的
```
types/
```
文件夹，或者完全位于功能之外的真正一次性内联请求——而非已经存在于真实功能文件夹中的单个
```
api/
```
文件。
使用
useEffect
处理数据转换或用户事件：如果某些内容可以从现有props或state计算得出，应在渲染期间计算。如果逻辑因用户操作而触发，应将其放入事件处理程序中。Effects仅用于与外部系统同步。详情请查看 reference/effects.md。