Skip to content

t1k:rn:base:script-graph

FieldValue
Modulebase
Version1.19.22
Effortmedium
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

/t1k:rn:base:script-graph

React Native diagram adapter for the T1K diagram toolchain. Produces three diagram types from RN project sources:

  1. 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/.
  2. 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.
  3. 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.

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.

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”):

StepAgent
Tabulate the emitted diagrams — total routes/screens per navigator, module-graph node counts from the generated routes.md / modules.mdt1k-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 fixstays 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.

Terminal window
# Auto-detect and generate all diagrams
t1k diagram refresh
# Generate a specific type
bun scripts/generate.cjs --type routes --out-dir /tmp/out
bun scripts/generate.cjs --type modules --out-dir /tmp/out
bun scripts/generate.cjs --type classes --out-dir /tmp/out
# Check if this adapter applies to current project
bun scripts/detect.cjs # exit 0 = match (package.json has react-native)
# List available capabilities
bun scripts/list-capabilities.cjs
# Show tool requirements
bun scripts/requirements.cjs
CapabilityOutput
routesroutes.md — Mermaid flowchart TD of navigator-to-screen graph
modulesmodules.md — Mermaid graph LR of file dependencies (dep-cruiser output)
classesclasses.md — Honest “not applicable for functional components” notice

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: 100 — higher than theonekit-web’s planned 80. When --engine auto matches both, RN wins. Users override via --engine web.

  • 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.
  • 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.
FileContent
references/routes-parser.mdRegex strategy, supported patterns, limitations, AST upgrade path
references/depcruise-integration.mdHow dep-cruiser runs per-project, config file generation, output post-processing
references/functional-components-notice.mdWhy we don’t emit class diagrams for RN code; guidance for users