next-route-graph 1.0.0 → 1.0.2

package/README.md

@@ -1,95 +1,52 @@
+````md
 # next-route-graph
 
-> Visualize and inspect the structure of a Next.js App Router project directly from your terminal.
+> Visualize and inspect your Next.js App Router structure from the terminal.
 
-`next-route-graph` is a lightweight, fast, zero-config CLI tool for Next.js developers.
+`next-route-graph` is a lightweight, zero-config CLI that scans your `app/` or `src/app/` directory and turns your routing structure into a clear overview.
 
-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.
+Useful for quickly understanding unfamiliar projects, documenting routes in a GitHub README, onboarding developers, or giving AI coding tools a structured view of your project's routing architecture.
+
+No configuration. No network requests. No Next.js runtime.
 
 ## 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.
+- Detects static, dynamic, catch-all, and optional catch-all routes
+- Supports Route Groups, Parallel Routes, and Intercepting Routes
+- Detects Server/Client rendering
+- Detects layouts, route handlers, and special App Router files
+- Tree, flat, and JSON output
+- Route search and filtering
+- Lightweight and fast
 
 ## 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:
+Or install 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:
+Run from 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:
+Analyze another project:
 
 ```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:
+Example output:
 
 ```text
 Project     my-next-app
@@ -100,268 +57,78 @@ 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]
+├── /[locale]/blog               page.tsx  [dynamic]
+├── /[locale]/blog/[slug]        page.tsx  [dynamic]
 └── /api                         route.ts
 
 Summary
 ────────────────────────────────────────
-Routes       6
-Dynamic      5
+Routes       5
+Dynamic      4
 Client       0
-Server       6
+Server       5
 Layouts      1
-Loading      0
-Errors       0
-
-✓ Analysis completed in 18ms
 ```
 
-## CLI Options
+## CLI
+
+```text
+next-route-graph
+next-route-graph <projectPath>
+next-route-graph --flat
+next-route-graph --json
+next-route-graph --search <query>
+next-route-graph --help
+next-route-graph --version
+```
 
 ### `--flat`
 
-Output only route paths as a flat list.
+Show only route paths:
 
 ```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.
+Output structured JSON for scripts, automation, AI tools, or CI:
 
 ```bash
 npx next-route-graph --json
 ```
 
-This is useful for scripts, automation, CI workflows, and other development tools.
-
-### `--search <query>`
+### `--search`
 
-Filter routes using a search query.
+Filter routes:
 
 ```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:
+Options can be combined:
 
 ```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
+MIT © 2026 Nima Soltanian
 
-See the [LICENSE](./LICENSE) file for the full license text.
+[GitHub](https://github.com/Nima-sltn/next-route-graph) · [npm](https://www.npmjs.com/package/next-route-graph)
 
-## Links
+```
 
-- **npm:** https://www.npmjs.com/package/next-route-graph
-- **GitHub:** https://github.com/Nima-sltn/next-route-graph
+```

package/dist/core/analyzer.js

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

package/dist/core/parser.js

@@ -21,43 +21,36 @@ 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;
+        const clientDirectiveRegex = /^(?:(?:\s*\/\/.*?\n)|(?:\s*\/\*[\s\S]*?\*\/)|(?:\s*))["']use client["']/m;
         if (clientDirectiveRegex.test(firstLines)) {
             return "client";
         }
     }
-    catch {
-        // Default to server if unreadable
-    }
+    catch { }
     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(/^\(\.\.\.\)|\(\.\.\)|\(\.\)/, "");
+            cleanedPart = cleanedPart.replace(/^(?:\(\.\.\.\)|\(\.\.\)|\(\.\))/, "");
         }
         urlSegments.push(cleanedPart);
     }

package/dist/render/tree.js

@@ -4,9 +4,9 @@ export function renderTree(result) {
     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(`${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("────────────────────────────────────────"));
@@ -18,12 +18,15 @@ export function renderTree(result) {
         const fileStr = pc.dim(route.file.split("/").pop() || "");
         let badge = "";
         if (route.rendering === "client") {
-            badge = `  ${pc.cyan("[client]")}`;
+            const clientBadge = pc.cyan("[client]");
+            badge = `  ${clientBadge}`;
         }
         else if (route.segmentType !== "static") {
-            badge = `  ${pc.yellow(`[${route.segmentType}]`)}`;
+            const segmentBadge = `[${route.segmentType}]`;
+            badge = `  ${pc.yellow(segmentBadge)}`;
         }
-        lines.push(`${pc.dim(prefix)}${pc.bold(pathStr)} ${fileStr}${badge}`);
+        const routeLine = `${pc.dim(prefix)}${pc.bold(pathStr)} ${fileStr}${badge}`;
+        lines.push(routeLine);
     });
     if (routes.length === 0) {
         lines.push(pc.dim("  (No routes found)"));
@@ -31,13 +34,13 @@ export function renderTree(result) {
     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(`${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("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-route-graph",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Visualize and inspect the structure of a Next.js App Router project from the terminal",
   "type": "module",
   "bin": {
@@ -28,8 +28,18 @@
     "route-map",
     "typescript"
   ],
-  "author": "Next Route Map Contributors",
+  "author": {
+    "name": "Nima Soltanian",
+    "url": "https://github.com/Nima-sltn"
+  },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nima-sltn/next-route-graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nima-sltn/next-route-graph/issues"
+  },
   "dependencies": {
     "commander": "^12.1.0",
     "picocolors": "^1.1.0"