implement-rfc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement React Router RFC

实现 React Router RFC

Implement the RFC from the following GitHub discussion: $ARGUMENTS

基于以下GitHub讨论实现RFC：$ARGUMENTS

Branching

分支规范

RFC implementations should start from a clean working tree. If there are uncommitted changes, stop and ask me to resolve them before continuing.

If you are already on a named branch that is at the same HEAD as
```
main
```
, use that branch.

Otherwise, create a branch from

main

using the format

{author}/rfc-{semantic-name}

git branch {author}/rfc-{semantic-name} main
git checkout {author}/rfc-{semantic-name}

RFC 实现应基于干净的工作树启动。如果存在未提交的更改，请停止并让我先解决这些更改再继续。

如果你当前所在的命名分支与
```
main
```
的 HEAD 一致，则使用该分支。

否则，基于

main

创建分支，分支名格式为

{author}/rfc-{语义名称}

：

git branch {author}/rfc-{semantic-name} main
git checkout {author}/rfc-{semantic-name}

Workflow

工作流程

1. Fetch and Understand the RFC

1. 获取并理解RFC内容

Use

WebFetch

to read the discussion URL. If a GitHub discussion number is given instead of a URL, construct:

https://github.com/remix-run/react-router/discussions/<number>

Extract:

Problem being solved: what pain point does this RFC address?
Proposed API: exact function signatures, hook names, types, option shapes
Affected modes: Declarative / Data / Framework / RSC Data / RSC Framework
Breaking changes: does this change or remove existing public API?
Open questions: anything explicitly marked as unresolved, "TBD", or asked as a question in the proposal
Status: are there linked tracking issues? Look for links to other github issues and read them to see if there is additional context.
sh
```
gh issue view <number> --repo remix-run/react-router
```

使用

WebFetch

读取讨论链接。如果提供的是GitHub讨论编号而非链接，请拼接为：

https://github.com/remix-run/react-router/discussions/<编号>

提取以下信息：

要解决的问题：该RFC旨在解决什么痛点？
提案API：确切的函数签名、hook名称、类型、选项结构
受影响的模式：声明式 / 数据 / 框架 / RSC 数据 / RSC 框架
破坏性变更：是否修改或移除了现有的公共API？
待解决问题：提案中明确标记为未解决、“TBD”或作为问题提出的内容
状态：是否有相关的跟踪issue？查找指向其他GitHub issue的链接并阅读，确认是否有额外上下文。
sh
```
gh issue view <number> --repo remix-run/react-router
```

2. Evaluate Community Feedback

2. 评估社区反馈

Fetch all comments from the discussion:

Use

WebFetch

https://github.com/remix-run/react-router/discussions/<number>

and scroll through the full thread. Look for:

Concerns or objections raised by community members or maintainers
Alternative proposals or API shape suggestions
Edge cases raised that the proposal does not address
Positive signals — repeated praise for a specific approach signals it's the right direction
Maintainer responses — Ryan Florence, Michael Jackson, or other core team members clarifying intent

Summarize the community sentiment into:

Points of consensus (safe to proceed)
Points of contention (need resolution before implementing)
Unanswered questions from the original proposal

获取讨论中的所有评论：

使用

WebFetch

访问

https://github.com/remix-run/react-router/discussions/<编号>

，浏览完整讨论线程。重点关注：

社区成员或维护者提出的担忧或反对意见
替代方案或API结构建议
提案未覆盖的边界情况
积极信号——对某一方案的多次认可表明该方向是正确的
维护者回复——Ryan Florence、Michael Jackson或其他核心团队成员对意图的澄清

将社区反馈总结为以下几类：

共识点（可安全推进）
争议点（需在实现前解决）
原提案中未答复的问题

3. Resolve Outstanding Questions

3. 解决待处理问题

Before writing any code, present me with a numbered list of every unresolved question — from both the RFC itself and from community feedback. For each question:

State the question clearly
Summarize relevant community input
Offer a recommended answer with reasoning

Ask me to confirm, override, or skip each question. Do not proceed to implementation until all questions are either answered or explicitly deferred.

Example format:

undefined

在编写任何代码之前，请将所有未解决问题（包括RFC本身和社区反馈中的）以编号列表的形式呈现给我。每个问题需包含：

清晰陈述问题
总结相关的社区意见
给出推荐答案及理由

请让我对每个问题进行确认、驳回或跳过。在所有问题都得到答复或明确延期之前，不要进入实现阶段。

示例格式：

undefined

Unresolved Questions

Should
useRouterState()
accept a path argument for scoped matching? Community feedback: 3 comments in favor, 1 against (concerns about complexity). Recommendation: Yes — scoped matching improves type safety for nested routes. → Your decision: [confirm / override / defer]
What should happen when the path doesn't match the current location? Recommendation: Return
```
null
```
for active state (consistent with
```
useMatch()
```
). → Your decision: [confirm / override / defer]


Save the resolved decisions to a scratch file at `tasks/rfc-decisions.md` for reference during implementation.

Should
useRouterState()
accept a path argument for scoped matching? Community feedback: 3 comments in favor, 1 against (concerns about complexity). Recommendation: Yes — scoped matching improves type safety for nested routes. → Your decision: [confirm / override / defer]
What should happen when the path doesn't match the current location? Recommendation: Return
```
null
```
for active state (consistent with
```
useMatch()
```
). → Your decision: [confirm / override / defer]


将已确认的决策保存到临时文件 `tasks/rfc-decisions.md` 中，供实现阶段参考。

4. Plan the Implementation

4. 制定实现计划

Before writing code, produce a concise implementation plan covering:

New types/interfaces to add
New functions/hooks to implement and their file locations
Existing APIs to deprecate (mark with
```
@deprecated
```
JSDoc + console warning in dev)
Whether a future flag is needed (see §5 below)
Test files to create or extend (unit and/or integration)
Changeset bump level (
```
minor
```
for new features,
```
major
```
for breaking changes behind a future flag that is now defaulted on)

Present the plan to me and wait for approval before implementing.

在编写代码之前，制定一份简洁的实现计划，涵盖以下内容：

需新增的类型/接口
需实现的新函数/hook及其文件位置
需弃用的现有API（标记
```
@deprecated
```
JSDoc + 开发环境下的控制台警告）
是否需要未来特性标志（见下文第5节）
需创建或扩展的测试文件（单元和/或集成测试）
变更集版本升级级别（新功能为
```
minor
```
，未来特性标志默认开启的破坏性变更为
```
major
```
）

将计划提交给我，等待批准后再开始实现。

5. Future Flags for Breaking Changes

5. 破坏性变更的未来特性标志

If the RFC changes or removes existing public API behavior, it must ship behind a future flag which will start with an

unstable_

prefix.

Future flag pattern:

Add the flag to

FutureConfig

packages/react-router/lib/router/utils.ts

export interface FutureConfig {
  // existing flags...
  unstable_myNewBehavior: boolean;
}

Gate the new behavior on the flag:

if (router.future.unstable_myNewBehavior) {
  // new behavior
} else {
  // legacy behavior
}

Document the flag in
```
docs/upgrading/future-flags.md
```
if it exists.

New additive APIs (no behavior change to existing code) do not need a future flag.

如果RFC修改或移除了现有公共API的行为，必须通过以

unstable_

为前缀的未来特性标志发布。

未来特性标志模式：

将标志添加到

packages/react-router/lib/router/utils.ts

的

FutureConfig

中：

export interface FutureConfig {
  // existing flags...
  unstable_myNewBehavior: boolean;
}

通过标志控制新行为的启用：

if (router.future.unstable_myNewBehavior) {
  // new behavior
} else {
  // legacy behavior
}

如果
```
docs/upgrading/future-flags.md
```
存在，在其中记录该标志。

新增的增量API（不改变现有代码的行为）不需要未来特性标志。

6. Key File Locations

6. 关键文件位置

Area	Files
Core router logic	`packages/react-router/lib/router/router.ts`
Router types/utils	`packages/react-router/lib/router/utils.ts`
React components	`packages/react-router/lib/components.tsx`
React hooks	`packages/react-router/lib/hooks.tsx`
Public exports	`packages/react-router/index.ts`
DOM utilities	`packages/react-router/lib/dom/`
Framework/Vite plugin	`packages/react-router-dev/vite/plugin.ts`
RSC runtime	`packages/react-router/lib/rsc/`
Unit tests	`packages/react-router/__tests__/`
Integration tests	`integration/`
Future flags doc	`docs/upgrading/future-flags.md`

Confirm existing patterns before writing new code - prefer using the LSP but

Grep

Glob

also work. Match naming conventions and code style exactly.

领域	文件路径
核心路由逻辑	`packages/react-router/lib/router/router.ts`
路由类型/工具函数	`packages/react-router/lib/router/utils.ts`
React 组件	`packages/react-router/lib/components.tsx`
React hooks	`packages/react-router/lib/hooks.tsx`
公共导出	`packages/react-router/index.ts`
DOM 工具函数	`packages/react-router/lib/dom/`
框架/Vite 插件	`packages/react-router-dev/vite/plugin.ts`
RSC 运行时	`packages/react-router/lib/rsc/`
单元测试	`packages/react-router/__tests__/`
集成测试	`integration/`
未来特性标志文档	`docs/upgrading/future-flags.md`

在编写新代码之前确认现有模式——优先使用LSP，也可以用

Grep

Glob

。严格遵循命名规范和代码风格。

7. Implement the Feature

7. 实现功能

Follow the approved plan. For each logical unit of work:

Write the implementation
Export from the appropriate public entry point (
```
packages/react-router/index.ts
```
)
Add
```
@deprecated
```
JSDoc to any APIs being superseded
Run typecheck to catch type errors early:
sh
```
pnpm typecheck
```

Keep changes minimal and focused. Do not refactor unrelated code. Commit as often as needed.

遵循已批准的计划。每个逻辑工作单元：

编写实现代码
在对应的公共入口文件（
```
packages/react-router/index.ts
```
）中导出
为所有被取代的API添加
```
@deprecated
```
JSDoc 标记
运行类型检查，尽早发现类型错误：
sh
```
pnpm typecheck
```

保持变更的最小化和聚焦性。不要重构不相关的代码。根据需要频繁提交。

8. Write Tests

8. 编写测试

Unit tests (for hooks, pure router logic, component behavior — no build):

Location:
```
packages/react-router/__tests__/
```

Runner: Jest →

pnpm test packages/react-router/__tests__/<file>

Cover: happy path, edge cases identified in RFC/community feedback, future flag gating (if applicable), deprecation warnings

Integration tests (for Vite/Framework Mode, SSR, hydration):

Location:
```
integration/
```

Runner: Playwright →

pnpm test:integration:run --project chromium integration/<file>

Required if the RFC touches Framework Mode, file-system routing, or SSR behavior

Run all tests and confirm they pass:

pnpm test packages/react-router/
pnpm test:integration:run --project chromium  # only if integration tests were added/changed

单元测试（用于hook、纯路由逻辑、组件行为——无需构建）：

位置：
```
packages/react-router/__tests__/
```

运行器：Jest →

pnpm test packages/react-router/__tests__/<文件>

覆盖范围：正常路径、RFC/社区反馈中提到的边界情况、未来特性标志控制（如适用）、弃用警告

集成测试（用于Vite/框架模式、SSR、水合）：

位置：
```
integration/
```

运行器：Playwright →

pnpm test:integration:run --project chromium integration/<文件>

如果RFC涉及框架模式、文件系统路由或SSR行为，则必须编写集成测试

运行所有测试并确认通过：

pnpm test packages/react-router/
pnpm test:integration:run --project chromium  # only if integration tests were added/changed

9. Lint and Typecheck

9. 代码检查与类型校验

pnpm lint
pnpm typecheck

Fix all errors before proceeding.

pnpm lint
pnpm typecheck

修复所有错误后再继续。

10. Create a Change File

10. 创建变更文件

Create

packages/<package>/.changes/<bump-level>.<descriptive-name>.md

. Use the RFC title or tracking issue as the description:

markdown

feat: <brief description matching the RFC title>

Implements the `useRouterState()` RFC (#12358). Deprecates `useLocation`,
`useParams`, `useSearchParams`, `useNavigation`, `useMatches`, `useMatch`,
`useNavigationType`, and `useViewTransitionState` in favor of a unified API.

Enable the `unstable_consolidatedRouterState` future flag to opt in.

Bump levels:

```
patch
```
— bug-adjacent fix only
```
minor
```
— new additive API (no breaking changes)
```
major
```
— breaking change (should be rare; most breaking changes go behind a future flag as
```
minor
```
first)
```
unstable
```
— new API that is not yet stable (e.g. added in a future flag, or an experimental API that may be removed without a major bump)

创建

packages/<包名>/.changes/<升级级别>.<描述性名称>.md

。使用RFC标题或跟踪issue作为描述：

markdown

feat: <brief description matching the RFC title>

Implements the `useRouterState()` RFC (#12358). Deprecates `useLocation`,
`useParams`, `useSearchParams`, `useNavigation`, `useMatches`, `useMatch`,
`useNavigationType`, and `useViewTransitionState` in favor of a unified API.

Enable the `unstable_consolidatedRouterState` future flag to opt in.

版本升级级别：

```
patch
```
— 仅类似bug修复的变更
```
minor
```
— 新增增量API（无破坏性变更）
```
major
```
— 破坏性变更（应很少见；大多数破坏性变更会先通过未来特性标志以
```
minor
```
版本发布）
```
unstable
```
— 尚未稳定的新API（例如通过未来特性标志添加的API，或可能在不升级major版本的情况下移除的实验性API）

11. Report and Review

11. 汇报与评审

Summarize:

What RFC was implemented and which decisions were made
New public APIs added (with brief usage example)
APIs deprecated and the migration path
Future flag name (if applicable) and how to opt in
Test coverage added
Anything deferred or explicitly out of scope

Ask me to review and iterate before opening a PR.

总结以下内容：

实现了哪个RFC，做出了哪些决策
新增的公共API（附简要使用示例）
被弃用的API及迁移路径
未来特性标志名称（如适用）及开启方式
新增的测试覆盖
所有延期或明确超出范围的内容

在创建PR之前，请让我进行评审和迭代。

12. Commit

12. 提交代码

Once I approve, commit and open a PR to

main

gh pr create --base main --title "feat: <RFC title>" --body "..."

PR body should include:

Link to the RFC discussion (Closes or Implements #NNNN)
Summary of what was implemented
Future flag instructions if applicable
Testing notes
Any decisions that deviated from the original proposal and why

一旦我批准，提交代码并向

main

分支创建PR：

gh pr create --base main --title "feat: <RFC title>" --body "..."

PR正文应包含：

RFC讨论的链接（Closes 或 Implements #NNNN）
实现内容的总结
未来特性标志的使用说明（如适用）
测试说明
所有偏离原提案的决策及其原因