t1k:rn:base:script-graph

Field	Value
Module	`base`
Version	`1.7.4`
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

/t1k:rn:base:script-graph

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 / createDrawerNavigator call sites and the <Screen name="X"> props, emitting a Mermaid flowchart 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 routes and (future) state diagrams.

Prerequisites

Install the RN toolchain:

t1k diagram install --preset rn

This installs mermaid-cli + graphviz globally, and registers dependency-cruiser as per-project-install-required. The routes capability works without any per-project tool — the regex parser has zero runtime dependencies. The modules capability requires dependency-cruiser in the scanned RN project’s devDependencies; requirements.cjs surfaces the install hint when missing.

Usage

# Auto-detect and generate all diagrams
t1k diagram refresh

# Generate a specific type
node scripts/generate.cjs --type routes   --out-dir /tmp/out
node scripts/generate.cjs --type modules  --out-dir /tmp/out
node scripts/generate.cjs --type classes  --out-dir /tmp/out

# Check if this adapter applies to current project
node scripts/detect.cjs   # exit 0 = match (package.json has react-native)

# List available capabilities
node scripts/list-capabilities.cjs

# Show tool requirements
node scripts/requirements.cjs

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

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)

priority: 100 — higher than theonekit-web’s planned 80. When --engine auto matches both, RN wins. Users override via --engine web.

Known Limitations (MVP)

Routes parser is regex-based — handles the common literal <Screen name="Home" component={HomeScreen} /> pattern and Stack.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)
Module graph does NOT collapse platform variants yet (Foo.ios.tsx and Foo.android.tsx appear 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.

Gotchas

Computed screen names skip silently — only literal <Screen name="Home"> and name={'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-web alone is NOT a match — detect.cjs deliberately excludes web-first projects so the web adapter wins the tiebreak. If you expect rn to match a polyglot project, confirm react-native (without the -web suffix) is in package.json.
Platform-variant duplication — Foo.ios.tsx, Foo.android.tsx, Foo.web.tsx appear 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-cruiser in devDependencies. Run requirements.cjs first 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 web explicitly.
classes capability 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

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