argon-router

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Argon Router

Use this skill to implement argon-router in React web apps with predictable Effector dataflow and typed paths.

在具有可预测Effector数据流和类型化路径的React Web应用中，使用此skill来实现argon-router。

Workflow

工作流程

Classify the task:

```
setup
```
: create route map, router, and controls.
```
ui
```
: connect router to React views, links, and outlet.
```
native
```
: integrate argon-router with React Navigation in React Native.
```
query
```
: track URL query state and sync enter/exit flows.
```
composition
```
: build derived/protected/virtual routes.
```
adapters
```
: pick and configure history/query/custom adapter.
```
ssr
```
: scope-safe initialization with memory history and
```
allSettled
```
.
```
hooks
```
: route activity and router access hooks in React.
```
debug
```
: validate path/router wiring and route lifecycle.

Load only required references:

Always start with
```
references/core-routing.md
```
.
Add
```
references/react-web.md
```
for any React integration task.
Add
```
references/react-native.md
```
for React Native stack/tabs integration.
Add
```
references/paths-dsl.md
```
when working with route path syntax or parsing/building URLs.
Add
```
references/query-tracking.md
```
when query params or filters are involved.
Add
```
references/route-composition.md
```
when using auth guards, grouped states, or virtual routes.

Add

references/adapters-ssr.md

for

historyAdapter

queryAdapter

, adapter selection, SSR bootstrap.

Add

references/react-navigation-apis.md

for

Link

useRouter

useRouterContext

useIsOpened

useOpenedViews

Add

references/lazy-layout.md

for

createLazyRouteView

and

withLayout

Add
```
references/examples.md
```
for copyable happy-path scaffolds.
End with
```
references/checklist.md
```
before final output.

Resolve source of truth before implementation:

Prefer

../argon-router/packages/*/lib/*.ts

and package

lib/index.ts

exports.

Use docs as explanatory context and examples.
If docs and code differ, follow code behavior and note mismatch briefly.

Build in this order:

Define route units with explicit paths and params.
Create router controls and initialize history adapter.
Create router with known routes, optional base, and explicit pathless mapping (
```
{ path, route }
```
) when needed.
Create React route views and wire
```
RouterProvider
```
+
```
createRoutesView
```
(add
```
otherwise
```
when fallback behavior is required).
Add link/navigation actions via route
```
open
```
and
```
Link
```
first.
Use
```
useLink
```
only for custom interaction surfaces.
Add dynamic registration (
```
router.registerRoute(...)
```
) only if runtime extension is required.
Add query trackers only when URL query behavior is required.
Add route composition (
```
chainRoute
```
,
```
group
```
) after baseline routing works.
Add lazy/layout organization (
```
createLazyRouteView
```
,
```
withLayout
```
) when route tree is stable.

Produce output contract:

Router topology: routes, router, controls, view mapping.
Wiring snippets for navigation and query flows.
Notes for params/path DSL used by each route.
Notes on adapter/SSR decisions when relevant.
Validation checklist with expected lifecycle behavior.

对任务进行分类：

```
setup
```
：创建路由映射、路由器和控制器。
```
ui
```
：将路由器连接到React视图、链接和Outlet。
```
native
```
：在React Native中集成argon-router与React Navigation。
```
query
```
：跟踪URL查询状态并同步进入/退出流程。
```
composition
```
：构建派生/受保护/虚拟路由。
```
adapters
```
：选择并配置history/query/自定义适配器。
```
ssr
```
：使用内存历史记录和
```
allSettled
```
进行作用域安全的初始化。
```
hooks
```
：React中的路由活动和路由器访问钩子。
```
debug
```
：验证路径/路由器连接和路由生命周期。

仅加载所需参考资料：

始终从
```
references/core-routing.md
```
开始。
对于任何React集成任务，添加
```
references/react-web.md
```
。
对于React Native栈/标签页集成，添加
```
references/react-native.md
```
。
处理路由路径语法或解析/构建URL时，添加
```
references/paths-dsl.md
```
。
涉及查询参数或过滤器时，添加
```
references/query-tracking.md
```
。
使用身份验证守卫、分组状态或虚拟路由时，添加
```
references/route-composition.md
```
。

处理

historyAdapter

queryAdapter

、适配器选择、SSR引导时，添加

references/adapters-ssr.md

。

处理

Link

、

useRouter

、

useRouterContext

、

useIsOpened

、

useOpenedViews

时，添加

references/react-navigation-apis.md

。

处理

createLazyRouteView

和

withLayout

时，添加

references/lazy-layout.md

。

如需可复制的最佳实践脚手架，添加
```
references/examples.md
```
。
最终输出前，添加
```
references/checklist.md
```
。

实现前确定事实来源：

优先使用

../argon-router/packages/*/lib/*.ts

和包的

lib/index.ts

导出内容。

将文档用作解释性上下文和示例。
如果文档与代码存在差异，遵循代码行为并简要说明不匹配之处。

按以下顺序构建：

定义具有明确路径和参数的路由单元。
创建路由器控制器并初始化history适配器。
使用已知路由、可选基础路径创建路由器，必要时使用明确的无路径映射（
```
{ path, route }
```
）。
创建React路由视图并连接
```
RouterProvider
```
+
```
createRoutesView
```
（需要回退行为时添加
```
otherwise
```
）。
首先通过路由
```
open
```
和
```
Link
```
添加链接/导航操作。
仅在自定义交互界面中使用
```
useLink
```
。
仅在需要运行时扩展时添加动态注册（
```
router.registerRoute(...)
```
）。
仅在需要URL查询行为时添加查询跟踪器。
在基础路由正常工作后，添加路由组合（
```
chainRoute
```
、
```
group
```
）。
路由树稳定后，添加懒加载/布局组织（
```
createLazyRouteView
```
、
```
withLayout
```
）。

生成输出约定：

路由器拓扑：路由、路由器、控制器、视图映射。
用于导航和查询流程的连接代码片段。
每个路由使用的参数/路径DSL说明。
相关的适配器/SSR决策说明。
包含预期生命周期行为的验证清单。

Defaults

默认设置

Target React web only (
```
@argon-router/react
```
).
Switch to React Native patterns only when task explicitly targets mobile/native stack.
Use happy-path integration patterns.
Keep route graph explicit and small before adding composition.
Prefer declarative Effector links (
```
sample
```
,
```
attach
```
) over imperative glue code.
Prefer
```
Link
```
over
```
useLink
```
unless custom interaction requires manual handlers.

仅针对React Web（
```
@argon-router/react
```
）。
仅当任务明确针对移动/原生栈时，才切换到React Native模式。
使用最佳实践集成模式。
在添加组合之前，保持路由图明确且简洁。
优先使用声明式Effector链接（
```
sample
```
、
```
attach
```
）而非命令式粘合代码。
除非自定义交互需要手动处理程序，否则优先使用
```
Link
```
而非
```
useLink
```
。

Guardrails

注意事项

Initialize controls with
```
setHistory
```
before expecting route activation from URL changes.
Pass router adapters to
```
setHistory
```
(
```
historyAdapter(...)
```
or
```
queryAdapter(...)
```
), not raw history objects.
Ensure every route used by
```
useLink
```
is registered in
```
createRouter({ routes })
```
.
Keep route paths deterministic; avoid ambiguous wildcard-heavy patterns unless required.
Model query state through
```
trackQuery
```
, not ad-hoc parsing in components.
Keep view rendering centralized in
```
createRoutesView
```
and
```
Outlet
```
composition.
Add
```
createRoutesView({ otherwise })
```
when no-match fallback is part of requirements.
Use
```
historyAdapter
```
for pathname routing and
```
queryAdapter
```
for secondary/modal/tab routing.

For SSR/testing, initialize router in scope with

allSettled(router.setHistory, { params: historyAdapter(createMemoryHistory(...)) })

在期望URL更改触发路由激活之前，使用
```
setHistory
```
初始化控制器。
将路由器适配器传递给
```
setHistory
```
（
```
historyAdapter(...)
```
或
```
queryAdapter(...)
```
），而非原始history对象。
确保
```
useLink
```
使用的每个路由都已在
```
createRouter({ routes })
```
中注册。
保持路由路径确定；除非必要，避免使用模糊的、大量通配符的模式。
通过
```
trackQuery
```
建模查询状态，而非在组件中进行临时解析。
将视图渲染集中在
```
createRoutesView
```
和
```
Outlet
```
组合中。
当无匹配回退是需求的一部分时，添加
```
createRoutesView({ otherwise })
```
。
使用
```
historyAdapter
```
进行路径名路由，使用
```
queryAdapter
```
进行次要/模态/标签页路由。

对于SSR/测试，在作用域中使用

allSettled(router.setHistory, { params: historyAdapter(createMemoryHistory(...)) })

初始化路由器。