t1k:web:frontend:script-graph

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	frontend
Version	1.9.0
Effort	medium
Tools	—

Keywords: app-router, class-diagram, dep-cruiser, module-graph, nextjs, pages-router, react-router, route-graph, ts-morph, web

How to invoke

/t1k:web:frontend:script-graph

---

web-script-graph

Web diagram adapter for the T1K diagram toolchain. Produces three diagram types from a React/TypeScript web project:

1. modules — Import-level module dependency graph via dependency-cruiser
2. classes — Class/interface extraction via ts-morph (honest skip notice emitted for functional-only projects)
3. routes — Next.js route tree (App Router or Pages Router) — falls back to React Router static detection

Prerequisites

Install the full Web toolchain:

t1k diagram install --preset web

This installs mermaid-cli globally and records dependency-cruiser + ts-morph as per-project installs. To enable per-project capabilities:

npm install --save-dev dependency-cruiser ts-morph

The routes capability works without either per-project tool (it uses a pure file-system walker + regex parser).

Priority & Polyglot Detection

This adapter declares priority: 80. In polyglot repos where the RN adapter (priority: 100) also detects, RN wins the tiebreak. Users may override with --engine web.

This adapter’s detect.cjs treats a package.json that depends on react-native (core) as an RN-first project and exits non-zero. react-native-web alone (without react-native) is accepted as a web-first signal.

Usage

# Auto-detect and generate all diagrams
t1k diagram refresh

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

# Check if this adapter applies to current project
node scripts/detect.cjs            # exit 0 = match

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

# Show tool requirements
node scripts/requirements.cjs

Output Files

Capability	Output
modules	modules.md — Mermaid graph LR of module-to-module imports
classes	classes.md — class diagram, or honest “not applicable” notice
routes	routes.md — Mermaid flowchart TD of route tree

Route Detection

routes tries in order:

1. Next.js App Router — if app/ or src/app/ contains page.tsx|jsx|ts|js or layout.tsx, walk the directory tree and emit a route hierarchy. Route groups (groupName) are collapsed, dynamic segments [slug] preserved as :slug, catch-all [...rest] as *rest.
2. Next.js Pages Router — if pages/ or src/pages/ exists with .tsx/.jsx/.ts/.js files, each file is a route. index.tsx → /, about.tsx → /about, [id].tsx → /:id.
3. React Router fallback — regex-scan source for <Route path="..." JSX or path: "..." object routes (static only, documented limitations).

If none match, routes.md contains the honest notice: No static routes detected — project uses dynamic routing or no router is installed.

Class Diagrams — Honest Notice

Modern React and most new TypeScript web apps are functional-component-based. When ts-morph finds fewer than 3 class declarations in the project, classes.md contains:

Class diagrams have limited value for this project — fewer than 3 class declarations found. Modern React uses functional components with hooks. See modules.md and routes.md for more relevant views.

This follows the rules/development-principles.md → “Errors Over Silent Fallbacks” policy — we don’t invent a fake diagram.

Known Limitations

• React Router dynamic routes (routes composed at runtime from config objects pulled in from a DB) cannot be statically analyzed — the regex parser handles only inline JSX <Route> and top-level path: literals.
• dep-cruiser per-project install required for the modules capability. If not installed, modules.md contains a skip notice with the npm install --save-dev dependency-cruiser hint.
• Monorepo workspaces (Nx / Turborepo) are not auto-detected in v1.0.0 — operate in single-package mode. Planned for v1.1.0.

References

File	Content
references/depcruise-setup.md	dep-cruiser invocation, per-project config, fallback behavior
references/ts-morph-class-extraction.md	ts-morph AST traversal, class + interface extraction, functional-component notice
references/nextjs-route-graph.md	App Router vs Pages Router detection, dynamic/catch-all segment rendering
references/react-router-fallback.md	Static regex parser design + limitations

Gotchas

• Web routing varies by framework — Next.js (file-based), Remix (file-based), SvelteKit (file-based), but each has different conventions; one regex parser doesn’t fit all.
• Module graphs from dep-cruiser exclude type-only imports by default — flip the flag if you need them in the diagram.
• Server vs client bundles in Next.js are TWO graphs — render both or your diagram lies about what runs where.