t1k:rn:base:script-graph
| Field | Value |
|---|---|
| Module | base |
| Version | 1.19.22 |
| Effort | medium |
| Tools | — |
Keywords: architecture-diagram, bottom-tabs, dep-cruiser, expo-router, native-stack, navigation, react-native, react-navigation, rn, rn-graph, route-graph, routes, screen-graph, stack-navigator, tab-navigator, ts-morph
How to invoke
Section titled “How to invoke”/t1k:rn:base:script-graphrn-script-graph
Section titled “rn-script-graph”React Native diagram adapter for the T1K diagram toolchain. Produces three diagram types from RN project sources:
- routes — Screen-to-screen navigation graph. Key RN differentiator. Parses
createNativeStackNavigator/createBottomTabNavigator/createDrawerNavigatorcall sites and the<Screen name="X">props, emitting a Mermaidflowchart TD. Regex-based parser (MVP); AST upgrade path documented in references/. - modules — File dependency graph via
dependency-cruiser(per-project). Platform variants (.ios.tsx,.android.tsx,.web.tsx,.native.tsx) surface as individual modules in the MVP — a platform-variant collapser is planned for v1.1. - classes — Honest “not applicable” notice. React Native is functional-component-first; a fake class diagram would violate the “Errors Over Silent Fallbacks” rule. Users are redirected to
routesand (future)statediagrams.
Prerequisites
Section titled “Prerequisites”The diagram tooling is not installable via the CLI right now: t1k diagram install exits 1 with a “not available” message (theonekit-cli#1422).
The routes capability works without any extra tool — the regex parser has zero runtime dependencies. The modules capability requires dependency-cruiser in the scanned RN project’s devDependencies (bun add -d dependency-cruiser); requirements.cjs surfaces the install hint when missing.
Executed by
Section titled “Executed by”Running the diagram tools and tabulating their output is cheap-tier work;
interpreting the graph — judging that a dependency cycle or navigation
tangle is a problem worth fixing — is not (routing SSOT:
rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Step | Agent |
|---|---|
Tabulate the emitted diagrams — total routes/screens per navigator, module-graph node counts from the generated routes.md / modules.md | t1k-metrics-reporter |
Run bun scripts/generate.cjs --type routes/modules/classes (or t1k diagram refresh) and surface output + warnings verbatim (computed-screen-name skips, platform-variant duplication, missing dep-cruiser hint) | t1k-fact-fetcher |
| Interpret the graph — deciding a dependency cycle or architectural smell needs a fix | stays on a reasoning tier, not delegated |
The tools emit deterministic Mermaid + dep-cruiser output; a cheap agent’s job is to run them and report counts and warnings faithfully, never to re-derive architecture conclusions from the diagram.
# Auto-detect and generate all diagramst1k diagram refresh
# Generate a specific typebun scripts/generate.cjs --type routes --out-dir /tmp/outbun scripts/generate.cjs --type modules --out-dir /tmp/outbun scripts/generate.cjs --type classes --out-dir /tmp/out
# Check if this adapter applies to current projectbun scripts/detect.cjs # exit 0 = match (package.json has react-native)
# List available capabilitiesbun scripts/list-capabilities.cjs
# Show tool requirementsbun scripts/requirements.cjsOutput Files
Section titled “Output Files”| Capability | Output |
|---|---|
routes | routes.md — Mermaid flowchart TD of navigator-to-screen graph |
modules | modules.md — Mermaid graph LR of file dependencies (dep-cruiser output) |
classes | classes.md — Honest “not applicable for functional components” notice |
Detection
Section titled “Detection”detect.cjs succeeds when the current working directory (or any ancestor up to a bounded depth) contains a package.json with react-native in dependencies or devDependencies. react-native-web alone does NOT count as RN — it is a web-first signal, so the web adapter can win the tiebreak.
Priority Tiebreak (polyglot monorepos)
Section titled “Priority Tiebreak (polyglot monorepos)”priority: 100 — higher than theonekit-web’s planned 80. When --engine auto matches both, RN wins. Users override via --engine web.
Known Limitations (MVP)
Section titled “Known Limitations (MVP)”- Routes parser is regex-based — handles the common literal
<Screen name="Home" component={HomeScreen} />pattern andStack.Screen/Tab.Screen, but NOT:- Computed screen names:
<Screen name={computedName} ... />(silently skipped with warning) - Programmatic registration via loops (emits a warning pointing to static-config or Expo Router)
- Deep-nesting beyond explicit navigator containers (subgraphs for the detected containers, flat for the rest)
- Computed screen names:
- Module graph does NOT collapse platform variants yet (
Foo.ios.tsxandFoo.android.tsxappear as separate nodes). Planned for v1.1 via a dep-cruiser rule file. - State graph (Redux/Zustand) is planned for v1.1 as an optional capability, skipped silently if the libraries aren’t present.
Hard rules
Section titled “Hard rules”- Computed screen names skip silently — only literal
<Screen name="Home">andname={'Home'}patterns are picked up. Loops, helper-built name maps, and dynamically-imported screen registries emit a warning but produce no edge. Audit warnings before trusting the route graph as complete. react-native-webalone is NOT a match —detect.cjsdeliberately excludes web-first projects so the web adapter wins the tiebreak. If you expect rn to match a polyglot project, confirmreact-native(without the-websuffix) is inpackage.json.- Platform-variant duplication —
Foo.ios.tsx,Foo.android.tsx,Foo.web.tsxappear as separate module-graph nodes in MVP. Treat any “duplicate” file as a platform variant until v1.1 ships the collapser. - dep-cruiser is per-project install — generation fails if the RN project does not have
dependency-cruiserin devDependencies. Runrequirements.cjsfirst to surface the install hint rather than reading a misleading dep-cruiser error. - Polyglot priority tiebreak — when both rn and web adapters match (
react-native+react-native-web), rn wins on priority 100 vs 80. To force web in a polyglot RN project, pass--engine webexplicitly. classescapability is intentionally empty — RN is functional-first; a fake class diagram would violate “Errors Over Silent Fallbacks.” Do not “fix” the empty output by inventing class extraction. Use routes + (future) state instead.
References
Section titled “References”| File | Content |
|---|---|
| references/routes-parser.md | Regex strategy, supported patterns, limitations, AST upgrade path |
| references/depcruise-integration.md | How dep-cruiser runs per-project, config file generation, output post-processing |
| references/functional-components-notice.md | Why we don’t emit class diagrams for RN code; guidance for users |