Explore the different output formats supported by next-introspect for various use cases

Output Formats

next-introspect supports multiple output formats to suit different use cases and workflows.

JSON Format

The JSON format provides a complete, structured representation of your project's routing information.

Basic Usage

next-introspect introspect . --format json --output routes.json

Pretty-printed JSON

next-introspect introspect . --format json --indent 4 --output routes.json

Example Output

{
  "project": {
    "framework": "nextjs",
    "version": "14.0.0",
    "router": "app",
    "rootDir": "/path/to/project",
    "sourceDirs": {
      "app": "app",
      "pages": null
    }
  },
  "routes": [
    {
      "path": "/",
      "filePath": "/path/to/project/app/page.tsx",
      "pattern": "static",
      "router": "app",
      "appRouter": {
        "segment": "",
        "isRouteGroup": false,
        "specialFiles": {
          "page": true,
          "layout": true,
          "loading": false
        },
        "componentTypes": {
          "page": "server",
          "layout": "server"
        }
      }
    },
    {
      "path": "/blog/[slug]",
      "filePath": "/path/to/project/app/blog/[slug]/page.tsx",
      "pattern": "dynamic",
      "dynamicSegments": ["slug"],
      "router": "app",
      "appRouter": {
        "segment": "[slug]",
        "isRouteGroup": false,
        "specialFiles": {
          "page": true
        },
        "componentTypes": {
          "page": "client"
        }
      }
    }
  ],
  "metadata": {
    "analyzedAt": "2024-01-15T10:30:00.000Z",
    "duration": 245,
    "filesProcessed": 15,
    "mode": "comprehensive"
  }
}

Markdown Format

The Markdown format generates human-readable documentation of your routes.

Basic Usage

next-introspect introspect . --format markdown --output ROUTES.md

With Metadata

next-introspect introspect . --format markdown --metadata metadata.json --output ROUTES.md

Example Output

# Next.js Routes Documentation

**Framework:** Next.js 14.0.0
**Router:** App Router
**Analysis Mode:** Comprehensive
**Generated:** January 15, 2024

## Routes

### Static Routes

#### `/`
- **File:** `app/page.tsx`
- **Component Type:** Server Component
- **Special Files:** page, layout
- **Description:** Homepage

### Dynamic Routes

#### `/blog/[slug]`
- **File:** `app/blog/[slug]/page.tsx`
- **Component Type:** Client Component
- **Parameters:** slug (string)
- **Special Files:** page
- **Description:** Individual blog post

#### `/products/[...slug]`
- **File:** `app/products/[...slug]/page.tsx`
- **Pattern:** Catch-all
- **Parameters:** slug (array)
- **Component Type:** Server Component
- **Description:** Product category or individual product

### API Routes

#### `/api/users`
- **File:** `app/api/users/route.ts`
- **Methods:** GET, POST
- **Description:** User management API

#### `/api/products/[id]`
- **File:** `app/api/products/[id]/route.ts`
- **Methods:** GET, PUT, DELETE
- **Parameters:** id (string)
- **Description:** Individual product API

TypeScript Format

The TypeScript format generates type-safe route builders and type definitions.

Basic Usage

next-introspect introspect . --format typescript --output routes.ts

With Custom Prefixes

next-introspect introspect . --format typescript --strip-prefixes "/api/" "/_next/" --output routes.ts

Example Output

// Auto-generated by next-introspect
// Framework: Next.js 14.0.0
// Generated: January 15, 2024

export interface RouteBuilder {
  (params?: Record<string, string | number>): string;
}

export interface RouteGroup {
  [key: string]: RouteBuilder | RouteGroup;
}

export const routes = {
  // Static routes
  $: "/" as const,

  // Dynamic routes
  blog: {
    $slug: (params: { slug: string }) => `/blog/${params.slug}`,
    posts: {
      $slug: (params: { slug: string }) => `/blog/posts/${params.slug}`
    }
  },

  // API routes
  api: {
    users: "/api/users" as const,
    products: {
      $id: (params: { id: string }) => `/api/products/${params.id}`
    }
  }
} as const;

export type Routes = typeof routes;

Usage in Code

import { routes } from './routes';

// Type-safe route generation
const homeUrl = routes.$;
const blogPostUrl = routes.blog.$slug({ slug: 'my-post' });
const productUrl = routes.api.products.$id({ id: '123' });

// All routes are type-safe
console.log(homeUrl);      // "/"
console.log(blogPostUrl);  // "/blog/my-post"
console.log(productUrl);   // "/api/products/123"

Object Format

The object format returns raw JavaScript objects for programmatic use.

Basic Usage

next-introspect introspect . --format object

Programmatic Usage

import { NextIntrospect } from 'next-introspect';

const introspect = new NextIntrospect('./');
await introspect.analyze();

// Get raw object
const result = introspect.exportToObject();

console.log(result.project);
console.log(result.routes);
console.log(result.metadata);

Nested Format

The nested format organizes routes in a hierarchical structure instead of a flat array.

Basic Usage

next-introspect introspect . --format json --nested --output routes-nested.json

With Empty Segments

next-introspect introspect . --format json --nested --include-empty-segments --output routes-full.json

Example Nested Output

{
  "project": { ... },
  "routes": {
    "": {
      "page": {
        "path": "/",
        "filePath": "app/page.tsx",
        "router": "app",
        "componentType": "server"
      },
      "layout": {
        "path": "/",
        "filePath": "app/layout.tsx",
        "router": "app",
        "componentType": "server"
      }
    },
    "blog": {
      "[slug]": {
        "page": {
          "path": "/blog/[slug]",
          "filePath": "app/blog/[slug]/page.tsx",
          "router": "app",
          "componentType": "client"
        }
      },
      "posts": {
        "[slug]": {
          "page": {
            "path": "/blog/posts/[slug]",
            "filePath": "app/blog/posts/[slug]/page.tsx",
            "router": "app",
            "componentType": "server"
          }
        }
      }
    },
    "api": {
      "users": {
        "route": {
          "path": "/api/users",
          "filePath": "app/api/users/route.ts",
          "router": "app",
          "methods": ["GET", "POST"]
        }
      }
    }
  },
  "metadata": { ... }
}

Custom Formatting

Field Exclusion

Exclude specific fields from the output:

next-introspect introspect . --format json --exclude-fields "filePath,pattern,router" --output clean-routes.json

Path Formatting

Customize how paths are displayed:

# Relative to project root
next-introspect introspect . --format json --path-style relative-to-project --show-file-paths --output routes-relative.json

# Strip prefixes
next-introspect introspect . --format json --path-style strip-prefix --strip-prefix "src/app/" --output routes-clean.json

Metadata Integration

JSON Metadata File

Create a metadata.json file:

{
  "/": {
    "title": "Homepage",
    "description": "Welcome to our website"
  },
  "/blog/[slug]": {
    "title": "Blog Post",
    "description": "Read our latest blog posts",
    "category": "content"
  },
  "/api/users": {
    "title": "Users API",
    "description": "User management endpoints",
    "authRequired": true
  }
}

Using Metadata

next-introspect introspect . --format markdown --metadata metadata.json --output ROUTES-with-metadata.md

Enhanced Output with Metadata

{
  "routes": [
    {
      "path": "/",
      "filePath": "app/page.tsx",
      "pattern": "static",
      "router": "app",
      "metadata": {
        "title": "Homepage",
        "description": "Welcome to our website"
      }
    }
  ]
}

Format Comparison

Format	Use Case	Human Readable	Type Safe	Programmatic
JSON	Data exchange, APIs	No	No	Yes
Markdown	Documentation	Yes	No	No
TypeScript	Type-safe routing	No	Yes	Yes
Object	Programmatic use	No	No	Yes
Nested	Hierarchical data	No	No	Yes

Best Practices

For Development

Use TypeScript format for type-safe route generation
Use Object format for programmatic analysis

For Documentation

Use Markdown format with metadata for team documentation
Use nested JSON for hierarchical route visualization

For CI/CD

Use JSON format for automated processing
Use quiet mode to reduce log noise

For APIs

Use field exclusion to reduce payload size
Use path formatting to normalize paths across environments

Output Formats

On this page