next-route-graph 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Next Route Map Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom me the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,367 @@
+# next-route-graph
+
+> Visualize and inspect the structure of a Next.js App Router project directly from your terminal.
+
+`next-route-graph` is a lightweight, fast, zero-config CLI tool for Next.js developers.
+
+It scans your local App Router structure and provides useful information about routes, dynamic segments, rendering types, layouts, route handlers, and special Next.js files — without requiring any configuration or network requests.
+
+## Features
+
+- ⚡ **Zero-config** — Works out of the box with no configuration files.
+- 🚫 **Zero-network** — Analyzes your project locally without sending files or data anywhere.
+- 🎯 **App Router focused** — Automatically detects both `app/` and `src/app/`.
+- 📁 **Dynamic route support** — Detects dynamic, catch-all, and optional catch-all segments.
+- 🧩 **Advanced routing support** — Recognizes Route Groups, Parallel Routes, and Intercepting Routes.
+- 🖥️ **Rendering detection** — Identifies Server and Client components.
+- 📄 **Special files** — Detects Next.js App Router special files and route handlers.
+- 🔍 **Search & filter** — Quickly find routes matching a specific query.
+- 📊 **Multiple output formats** — Human-readable tree, flat route list, or machine-readable JSON.
+- 🚀 **Fast & lightweight** — No Next.js runtime or project configuration required.
+
+## Installation
+
+### Run with npx
+
+The easiest way to use `next-route-graph`:
+
+```bash
+npx next-route-graph
+```
+
+### Install globally
+
+You can also install it globally:
+
+```bash
+npm install -g next-route-graph
+```
+
+Then run:
+
+```bash
+next-route-graph
+```
+
+## Usage
+
+Run the CLI from the root of your Next.js project:
+
+```bash
+npx next-route-graph
+```
+
+The CLI automatically detects your App Router directory:
+
+```text
+app/
+```
+
+or:
+
+```text
+src/app/
+```
+
+You can also provide a custom project path:
+
+```bash
+npx next-route-graph ./my-next-app
+```
+
+## Example
+
+For a project with the following structure:
+
+```text
+src/app/
+├── [locale]/
+│   ├── about/
+│   │   └── page.tsx
+│   ├── concepts/
+│   │   ├── [category]/
+│   │   │   └── [slug]/
+│   │   │       └── page.tsx
+│   │   └── page.tsx
+│   └── page.tsx
+├── api/
+│   └── route.ts
+└── layout.tsx
+```
+
+`next-route-graph` produces a route overview such as:
+
+```text
+Project     my-next-app
+Router      App Router
+Root        src/app
+
+Routes
+────────────────────────────────────────
+├── /[locale]                    page.tsx  [dynamic]
+├── /[locale]/about              page.tsx  [dynamic]
+├── /[locale]/concepts           page.tsx  [dynamic]
+├── /[locale]/concepts/[category] page.tsx [dynamic]
+├── /[locale]/concepts/[category]/[slug] page.tsx [dynamic]
+└── /api                         route.ts
+
+Summary
+────────────────────────────────────────
+Routes       6
+Dynamic      5
+Client       0
+Server       6
+Layouts      1
+Loading      0
+Errors       0
+
+✓ Analysis completed in 18ms
+```
+
+## CLI Options
+
+### `--flat`
+
+Output only route paths as a flat list.
+
+```bash
+npx next-route-graph --flat
+```
+
+Example:
+
+```text
+/[locale]
+/[locale]/about
+/[locale]/concepts
+/[locale]/concepts/[category]
+/api
+```
+
+This format is useful when you only need the route paths without additional metadata.
+
+### `--json`
+
+Output the complete analysis as machine-readable JSON.
+
+```bash
+npx next-route-graph --json
+```
+
+This is useful for scripts, automation, CI workflows, and other development tools.
+
+### `--search <query>`
+
+Filter routes using a search query.
+
+```bash
+npx next-route-graph --search blog
+```
+
+For example:
+
+```text
+/blog
+/blog/[slug]
+/blog/archive
+```
+
+Search can be combined with other output modes:
+
+```bash
+npx next-route-graph --search blog --flat
+```
+
+or:
+
+```bash
+npx next-route-graph --search blog --json
+```
+
+### `<projectPath>`
+
+Analyze a specific Next.js project instead of the current directory.
+
+```bash
+npx next-route-graph ./my-next-app
+```
+
+## Command Reference
+
+| Command / Option                 | Description                         |
+| -------------------------------- | ----------------------------------- |
+| `next-route-graph`               | Analyze the current Next.js project |
+| `next-route-graph <projectPath>` | Analyze a specific project          |
+| `--flat`                         | Output only route paths             |
+| `--json`                         | Output machine-readable JSON        |
+| `--search <query>`               | Filter routes by search string      |
+| `--help`                         | Show CLI help                       |
+| `--version`                      | Show the installed version          |
+
+## Supported Next.js Routing Features
+
+`next-route-graph` understands common Next.js App Router conventions, including:
+
+### Static Routes
+
+```text
+/about
+/dashboard
+/settings/profile
+```
+
+### Dynamic Routes
+
+```text
+/[id]
+/products/[productId]
+```
+
+### Catch-all Routes
+
+```text
+/docs/[...slug]
+```
+
+### Optional Catch-all Routes
+
+```text
+/docs/[[...slug]]
+```
+
+### Route Groups
+
+```text
+/(marketing)/about
+```
+
+### Parallel Routes
+
+```text
+/dashboard/@analytics
+```
+
+### Intercepting Routes
+
+```text
+(.)photo
+(..)photo
+(...)photo
+```
+
+### Route Handlers
+
+```text
+/api/users/route.ts
+```
+
+### Special App Router Files
+
+The analyzer detects relevant Next.js App Router files such as:
+
+```text
+layout.tsx
+page.tsx
+loading.tsx
+error.tsx
+not-found.tsx
+route.ts
+```
+
+## Output Formats
+
+`next-route-graph` currently provides three output modes.
+
+### Tree
+
+The default output provides a human-readable overview of the project.
+
+```bash
+npx next-route-graph
+```
+
+### Flat
+
+Outputs only route paths.
+
+```bash
+npx next-route-graph --flat
+```
+
+### JSON
+
+Outputs structured data for programmatic use.
+
+```bash
+npx next-route-graph --json
+```
+
+## Why next-route-graph?
+
+Next.js App Router projects can become difficult to navigate as the number of routes, layouts, dynamic segments, and special files grows.
+
+`next-route-graph` gives you a quick overview of the routing structure directly from your terminal.
+
+No configuration.
+
+No network requests.
+
+No Next.js runtime.
+
+Just run it and inspect your routes.
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/Nima-sltn/next-route-graph.git
+cd next-route-graph
+```
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run type checking:
+
+```bash
+npm run typecheck
+```
+
+Build the project:
+
+```bash
+npm run build
+```
+
+## Contributing
+
+Contributions, bug reports, feature requests, and improvements are welcome.
+
+If you find an issue or have an idea for improving `next-route-graph`, feel free to open an issue or submit a pull request.
+
+Before submitting a pull request, please make sure that:
+
+- Tests are passing.
+- Type checking passes.
+- The project builds successfully.
+
+## License
+
+MIT © 2026 Next Route Map Contributors
+
+See the [LICENSE](./LICENSE) file for the full license text.
+
+## Links
+
+- **npm:** https://www.npmjs.com/package/next-route-graph
+- **GitHub:** https://github.com/Nima-sltn/next-route-graph

package/dist/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { analyzeRoutes } from "./core/analyzer.js";
+import { detectAppRouter } from "./core/detector.js";
+import { scanAppDir } from "./core/scanner.js";
+import { renderFlat } from "./render/flat.js";
+import { renderJson } from "./render/json.js";
+import { renderTree } from "./render/tree.js";
+const program = new Command();
+program
+    .name("next-route-graph")
+    .description("Inspect and visualize Next.js App Router project routes")
+    .version("1.0.0")
+    .argument("[projectPath]", "Path to the Next.js project root", ".")
+    .option("--flat", "Output only flat route paths")
+    .option("--json", "Output machine-readable JSON")
+    .option("--search <query>", "Filter routes by search string")
+    .action(async (projectPath, options) => {
+    try {
+        const { appDir, displayRoot } = detectAppRouter(projectPath);
+        const scannedFiles = await scanAppDir(appDir);
+        let analysisResult = await analyzeRoutes(scannedFiles, projectPath, displayRoot);
+        if (options.search) {
+            const search = options.search;
+            analysisResult.routes = analysisResult.routes.filter((route) => route.path.includes(search));
+            analysisResult.summary = {
+                ...analysisResult.summary,
+                routes: analysisResult.routes.length,
+                dynamic: analysisResult.routes.filter((route) => route.segmentType === "dynamic").length,
+                client: analysisResult.routes.filter((route) => route.rendering === "client").length,
+                server: analysisResult.routes.filter((route) => route.rendering === "server").length,
+            };
+        }
+        if (options.json) {
+            console.log(renderJson(analysisResult));
+        }
+        else if (options.flat) {
+            const flatOutput = renderFlat(analysisResult.routes);
+            if (flatOutput) {
+                console.log(flatOutput);
+            }
+        }
+        else {
+            console.log(renderTree(analysisResult));
+        }
+    }
+    catch (error) {
+        if (options.json) {
+            console.error(JSON.stringify({ error: error.message }));
+        }
+        else {
+            console.error(pc.red(`✗ ${error.message}`));
+        }
+        process.exit(1);
+    }
+});
+program.parse(process.argv);

package/dist/core/analyzer.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { detectRenderingType, getSegmentType, parseRoutePath, parseSpecialFileType, } from "./parser.js";
+export async function analyzeRoutes(files, projectPath, displayRoot) {
+    const startTime = Date.now();
+    const dirMap = new Map();
+    for (const file of files) {
+        const dir = path.dirname(file.relativePath).replace(/\\/g, "/");
+        if (!dirMap.has(dir)) {
+            dirMap.set(dir, []);
+        }
+        dirMap.get(dir).push(file);
+    }
+    const routesMap = new Map();
+    let totalLayouts = 0;
+    let totalLoading = 0;
+    let totalErrors = 0;
+    for (const [dir, dirFiles] of dirMap.entries()) {
+        const routeFiles = [];
+        for (const file of dirFiles) {
+            const specialType = parseSpecialFileType(file.fileName);
+            if (specialType) {
+                const rendering = await detectRenderingType(file.fullPath);
+                routeFiles.push({
+                    type: specialType,
+                    fileName: file.fileName,
+                    relativePath: file.relativePath,
+                    rendering,
+                });
+                if (specialType === "layout")
+                    totalLayouts++;
+                if (specialType === "loading")
+                    totalLoading++;
+                if (specialType === "error")
+                    totalErrors++;
+            }
+        }
+        const pageFile = routeFiles.find((f) => f.type === "page");
+        const routeHandlerFile = routeFiles.find((f) => f.type === "route");
+        if (pageFile || routeHandlerFile) {
+            const primaryFile = (pageFile || routeHandlerFile);
+            const computedPath = parseRoutePath(primaryFile.relativePath);
+            routesMap.set(computedPath, {
+                path: computedPath,
+                type: pageFile ? "page" : "route",
+                file: primaryFile.relativePath,
+                segmentType: getSegmentType(computedPath),
+                rendering: primaryFile.rendering,
+                files: routeFiles,
+            });
+        }
+    }
+    const routes = Array.from(routesMap.values()).sort((a, b) => a.path.localeCompare(b.path));
+    let dynamicCount = 0;
+    let clientCount = 0;
+    let serverCount = 0;
+    for (const route of routes) {
+        if (route.segmentType !== "static") {
+            dynamicCount++;
+        }
+        if (route.rendering === "client") {
+            clientCount++;
+        }
+        else {
+            serverCount++;
+        }
+    }
+    const projectName = path.basename(path.resolve(projectPath));
+    const summary = {
+        routes: routes.length,
+        dynamic: dynamicCount,
+        client: clientCount,
+        server: serverCount,
+        layouts: totalLayouts,
+        loading: totalLoading,
+        errors: totalErrors,
+    };
+    return {
+        project: projectName,
+        router: "App Router",
+        root: displayRoot,
+        routes,
+        summary,
+        executionTimeMs: Date.now() - startTime,
+    };
+}

package/dist/core/detector.js

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+export function detectAppRouter(projectDir) {
+    const absoluteDir = path.resolve(projectDir);
+    if (!fs.existsSync(absoluteDir)) {
+        throw new Error("The specified project path does not exist.");
+    }
+    const srcAppPath = path.join(absoluteDir, "src", "app");
+    const appPath = path.join(absoluteDir, "app");
+    const hasSrcApp = fs.existsSync(srcAppPath) && fs.statSync(srcAppPath).isDirectory();
+    const hasApp = fs.existsSync(appPath) && fs.statSync(appPath).isDirectory();
+    if (hasSrcApp && hasApp) {
+        throw new Error(`Could not determine the App Router root.\n\nFound both:\n  ./app\n  ./src/app\n\nPlease keep only one App Router root for analysis.`);
+    }
+    if (hasSrcApp) {
+        return {
+            appDir: srcAppPath,
+            displayRoot: "src/app",
+        };
+    }
+    if (hasApp) {
+        return {
+            appDir: appPath,
+            displayRoot: "app",
+        };
+    }
+    throw new Error(`No Next.js App Router directory found.\n\nExpected:\n  ./app\n  ./src/app`);
+}

package/dist/core/parser.js

@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const SPECIAL_FILES = new Set([
+    "page",
+    "layout",
+    "loading",
+    "error",
+    "not-found",
+    "template",
+    "default",
+    "route",
+]);
+export function parseSpecialFileType(fileName) {
+    const baseName = path.parse(fileName).name;
+    if (SPECIAL_FILES.has(baseName)) {
+        return baseName;
+    }
+    return null;
+}
+export async function detectRenderingType(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const firstLines = content.slice(0, 500);
+        const clientDirectiveRegex = /^\s*(?:\/\/.*?\n|\/\*[\s\S]*?\*\/)*\s*["']use client["']/m;
+        if (clientDirectiveRegex.test(firstLines)) {
+            return "client";
+        }
+    }
+    catch {
+        // Default to server if unreadable
+    }
+    return "server";
+}
+export function parseRoutePath(relativePath) {
+    const parts = relativePath.split("/");
+    // Remove the file name at the end
+    parts.pop();
+    const urlSegments = [];
+    for (const part of parts) {
+        if (!part)
+            continue;
+        // Route groups are ignored in URL matching
+        if (part.startsWith("(") && part.endsWith(")")) {
+            const inner = part.slice(1, -1);
+            // Exclude intercepting routes which also start with '('
+            if (!inner.startsWith(".") && inner !== "...") {
+                continue;
+            }
+        }
+        // Parallel routes are ignored in URL pathing
+        if (part.startsWith("@")) {
+            continue;
+        }
+        // Intercepting routes clean-up for display path
+        let cleanedPart = part;
+        if (cleanedPart.startsWith("(.)") ||
+            cleanedPart.startsWith("(..)") ||
+            cleanedPart.startsWith("(...)") ||
+            cleanedPart.startsWith("(..)(..)")) {
+            cleanedPart = cleanedPart.replace(/^\(\.\.\.\)|\(\.\.\)|\(\.\)/, "");
+        }
+        urlSegments.push(cleanedPart);
+    }
+    const routePath = "/" + urlSegments.join("/");
+    return routePath === "/" ? "/" : routePath.replace(/\/+/g, "/");
+}
+export function getSegmentType(routePath) {
+    if (routePath.includes("[[...")) {
+        return "optional-catch-all";
+    }
+    if (routePath.includes("[...")) {
+        return "catch-all";
+    }
+    if (routePath.includes("[")) {
+        return "dynamic";
+    }
+    return "static";
+}

package/dist/core/scanner.js

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const ALLOWED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+const IGNORE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    "coverage",
+]);
+export async function scanAppDir(rootDir, currentDir = rootDir) {
+    let files = [];
+    let entries;
+    try {
+        entries = await fs.readdir(currentDir, { withFileTypes: true });
+    }
+    catch {
+        throw new Error("Unable to read the App Router directory.");
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORE_DIRS.has(entry.name)) {
+                const subFiles = await scanAppDir(rootDir, fullPath);
+                files = files.concat(subFiles);
+            }
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name);
+            if (ALLOWED_EXTENSIONS.has(ext)) {
+                const relativePath = path
+                    .relative(rootDir, fullPath)
+                    .replace(/\\/g, "/");
+                files.push({
+                    relativePath,
+                    fullPath,
+                    fileName: entry.name,
+                    extension: ext,
+                });
+            }
+        }
+    }
+    return files;
+}

package/dist/render/flat.js

@@ -0,0 +1,3 @@
+export function renderFlat(routes) {
+    return routes.map((r) => r.path).join("\n");
+}

package/dist/render/json.js

@@ -0,0 +1,16 @@
+export function renderJson(result) {
+    const output = {
+        project: result.project,
+        router: "app",
+        root: result.root,
+        routes: result.routes.map((r) => ({
+            path: r.path,
+            type: r.type,
+            file: r.file,
+            segmentType: r.segmentType,
+            rendering: r.rendering,
+        })),
+        summary: result.summary,
+    };
+    return JSON.stringify(output, null, 2);
+}

package/dist/render/tree.js

@@ -0,0 +1,45 @@
+import pc from "picocolors";
+export function renderTree(result) {
+    const lines = [];
+    lines.push("");
+    lines.push(pc.bold("next-route-graph"));
+    lines.push("");
+    lines.push(`${pc.dim("Project    ")} ${result.project}`);
+    lines.push(`${pc.dim("Router     ")} ${result.router}`);
+    lines.push(`${pc.dim("Root       ")} ${result.root}`);
+    lines.push("");
+    lines.push(pc.bold("Routes"));
+    lines.push(pc.dim("────────────────────────────────────────"));
+    const routes = result.routes;
+    routes.forEach((route, index) => {
+        const isLast = index === routes.length - 1;
+        const prefix = isLast ? "└── " : "├── ";
+        const pathStr = route.path.padEnd(28, " ");
+        const fileStr = pc.dim(route.file.split("/").pop() || "");
+        let badge = "";
+        if (route.rendering === "client") {
+            badge = `  ${pc.cyan("[client]")}`;
+        }
+        else if (route.segmentType !== "static") {
+            badge = `  ${pc.yellow(`[${route.segmentType}]`)}`;
+        }
+        lines.push(`${pc.dim(prefix)}${pc.bold(pathStr)} ${fileStr}${badge}`);
+    });
+    if (routes.length === 0) {
+        lines.push(pc.dim("  (No routes found)"));
+    }
+    lines.push("");
+    lines.push(pc.bold("Summary"));
+    lines.push(pc.dim("────────────────────────────────────────"));
+    lines.push(`${pc.dim("Routes      ")} ${result.summary.routes}`);
+    lines.push(`${pc.dim("Dynamic     ")} ${result.summary.dynamic}`);
+    lines.push(`${pc.dim("Client      ")} ${result.summary.client}`);
+    lines.push(`${pc.dim("Server      ")} ${result.summary.server}`);
+    lines.push(`${pc.dim("Layouts     ")} ${result.summary.layouts}`);
+    lines.push(`${pc.dim("Loading     ")} ${result.summary.loading}`);
+    lines.push(`${pc.dim("Errors      ")} ${result.summary.errors}`);
+    lines.push("");
+    lines.push(pc.green(`✓ Analysis completed in ${result.executionTimeMs}ms`));
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "next-route-graph",
+  "version": "1.0.0",
+  "description": "Visualize and inspect the structure of a Next.js App Router project from the terminal",
+  "type": "module",
+  "bin": {
+    "next-route-graph": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "nextjs",
+    "app-router",
+    "routes",
+    "cli",
+    "visualization",
+    "route-map",
+    "typescript"
+  ],
+  "author": "Next Route Map Contributors",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  }
+}