# API Reference

# API Reference

This section provides a complete reference for the next-introspect programmatic API.

## NextIntrospect Class

The main class for analyzing Next.js projects.

### Constructor

```typescript
new NextIntrospect(projectPath: string, options?: IntrospectionOptions)
```

**Parameters:**

* `projectPath`: Path to the Next.js project root
* `options`: Optional configuration object

### Methods

#### analyze()

Analyzes the Next.js project and returns project information.

```typescript
async analyze(): Promise<ProjectInfo>
```

**Returns:** Promise resolving to `ProjectInfo` object

**Throws:** Error if project is invalid or analysis fails

#### getRoutes()

Returns all detected routes.

```typescript
getRoutes(): RouteInfo[]
```

**Returns:** Array of `RouteInfo` objects

**Requires:** Call `analyze()` first

#### getResult()

Returns the complete introspection result.

```typescript
getResult(): IntrospectionResult
```

**Returns:** Complete introspection result object

**Requires:** Call `analyze()` first

#### exportToObject()

Alias for `getResult()`.

```typescript
exportToObject(): IntrospectionResult
```

#### format()

Formats the results using the specified formatter.

```typescript
format(format: OutputFormat): string | object
```

**Parameters:**

* `format`: Output format (`'object' | 'json' | 'markdown' | 'typescript'`)

**Returns:** Formatted result as string or object

#### exportToFile()

Exports results to a file.

```typescript
async exportToFile(filePath: string, format?: OutputFormat): Promise<void>
```

**Parameters:**

* `filePath`: Path to output file
* `format`: Output format (default: `'json'`)

#### setMode()

Sets the analysis mode.

```typescript
setMode(mode: OutputMode): void
```

**Parameters:**

* `mode`: Analysis mode (`'basic' | 'detailed' | 'comprehensive'`)

#### getMode()

Returns the current analysis mode.

```typescript
getMode(): OutputMode
```

#### updateOptions()

Updates analysis options.

```typescript
updateOptions(newOptions: Partial<IntrospectionOptions>): void
```

**Parameters:**

* `newOptions`: Partial options object to merge

#### getRoutesByRouter()

Gets routes filtered by router type.

```typescript
getRoutesByRouter(router: 'app' | 'pages'): RouteInfo[]
```

#### getApiRoutes()

Gets all API routes (Pages Router only).

```typescript
getApiRoutes(): RouteInfo[]
```

#### getSpecialPages()

Gets special pages (Pages Router only).

```typescript
getSpecialPages(): RouteInfo[]
```

#### getDynamicRoutes()

Gets all dynamic routes.

```typescript
getDynamicRoutes(): RouteInfo[]
```

#### getStaticRoutes()

Gets all static routes.

```typescript
getStaticRoutes(): RouteInfo[]
```

#### mergeWithJson()

Merges existing JSON results with new metadata.

```typescript
async mergeWithJson(jsonFilePath: string, metadata: Record<string, RouteMetadata> | IntrospectionResult): Promise<IntrospectionResult>
```

#### reanalyze()

Re-analyzes the project (useful when files have changed).

```typescript
async reanalyze(): Promise<ProjectInfo>
```

#### isAnalyzed()

Checks if the project has been analyzed.

```typescript
isAnalyzed(): boolean
```

#### getProjectInfo()

Returns project information.

```typescript
getProjectInfo(): ProjectInfo | null
```

#### getOptions()

Returns current analysis options.

```typescript
getOptions(): IntrospectionOptions
```

## Type Definitions

### IntrospectionOptions

Configuration options for analysis.

```typescript
interface IntrospectionOptions {
  /** Detail level of analysis */
  mode?: OutputMode;

  /** File patterns to include in analysis */
  include?: string[];

  /** File patterns to exclude from analysis */
  exclude?: string[];

  /** Maximum depth for directory traversal */
  maxDepth?: number;

  /** Custom ignore patterns */
  ignorePatterns?: string[];

  /** Whether to follow symbolic links */
  followSymlinks?: boolean;

  /** Path display options */
  pathDisplay?: {
    /** Path display style */
    style?: 'absolute' | 'relative-to-project' | 'relative-to-app' | 'relative-to-pages' | 'strip-prefix';

    /** Prefix to strip when using strip-prefix style */
    stripPrefix?: string;

    /** Whether to show file paths */
    showFilePaths?: boolean;
  };

  /** Package.json display options */
  packageDisplay?: {
    /** Include full package.json details */
    includeFullDetails?: boolean;

    /** Include scripts section */
    includeScripts?: boolean;

    /** Include dependencies */
    includeDependencies?: boolean;
  };

  /** Output formatting options */
  outputFormat?: {
    /** Output routes in nested structure */
    nested?: boolean;

    /** Include empty segments in nested structure */
    includeEmptySegments?: boolean;

    /** Fields to exclude from output */
    excludeFields?: string[];

    /** Prefixes to strip from route paths */
    stripPrefixes?: string[];
  };

  /** Metadata options */
  metadata?: {
    /** Path to metadata file */
    file?: string;

    /** Metadata entries keyed by route path */
    entries?: Record<string, RouteMetadata>;
  };
}
```

### ProjectInfo

Information about the analyzed project.

```typescript
interface ProjectInfo {
  /** Framework name */
  framework: string;

  /** Framework version */
  version: string;

  /** Router type(s) detected */
  router: RouterType;

  /** Project root directory */
  rootDir: string;

  /** Next.js configuration */
  config?: NextConfig;

  /** Package.json information */
  packageInfo?: PackageInfo;

  /** Detected source directories */
  sourceDirs: {
    app?: string;
    pages?: string;
    api?: string;
  };
}
```

### RouteInfo

Information about a single route.

```typescript
interface RouteInfo extends BaseRoute {
  /** Router type this route belongs to */
  router: 'app' | 'pages';

  /** App Router specific data */
  appRouter?: Omit<AppRouterRoute, keyof BaseRoute>;

  /** Pages Router specific data */
  pagesRouter?: Omit<PagesRouterRoute, keyof BaseRoute>;

  /** Metadata from external file */
  metadata?: RouteMetadata;
}
```

### BaseRoute

Common route information.

```typescript
interface BaseRoute {
  /** Route path (URL path) */
  path: string;

  /** File system path to the route file */
  filePath: string;

  /** Route pattern type */
  pattern: RoutePattern;

  /** Dynamic segments in the route */
  dynamicSegments?: string[];

  /** Catch-all segment */
  catchAllSegment?: string;
}
```

### AppRouterRoute

App Router specific route information.

```typescript
interface AppRouterRoute extends BaseRoute {
  /** Route segment name */
  segment: string;

  /** Whether this is a route group */
  isRouteGroup: boolean;

  /** Whether this is an intercepting route */
  isInterceptingRoute: boolean;

  /** Whether this is a parallel route */
  isParallelRoute: boolean;

  /** Special files present */
  specialFiles: {
    page?: boolean;
    layout?: boolean;
    loading?: boolean;
    error?: boolean;
    notFound?: boolean;
    template?: boolean;
    default?: boolean;
    route?: boolean;
  };

  /** Component types for special files */
  componentTypes: {
    page?: ComponentType;
    layout?: ComponentType;
    loading?: ComponentType;
    error?: ComponentType;
    notFound?: ComponentType;
    template?: ComponentType;
    default?: ComponentType;
  };

  /** Exported functions and metadata */
  exports?: {
    metadata?: boolean;
    generateMetadata?: boolean;
    generateStaticParams?: boolean;
    generateViewport?: boolean;
    revalidate?: number;
  };

  /** Child routes */
  children?: AppRouterRoute[];
}
```

### PagesRouterRoute

Pages Router specific route information.

```typescript
interface PagesRouterRoute extends BaseRoute {
  /** Whether this is an API route */
  isApiRoute: boolean;

  /** Data fetching methods */
  dataFetching?: {
    getStaticProps?: boolean;
    getServerSideProps?: boolean;
    getStaticPaths?: boolean;
  };

  /** Whether it's a special Next.js page */
  isSpecialPage?: boolean;

  /** Special page type */
  specialPageType?: 'app' | 'document' | 'error' | '404' | '500';

  /** Component type */
  componentType?: ComponentType;
}
```

### RouteMetadata

Metadata for routes.

```typescript
interface RouteMetadata {
  /** Human-readable title */
  title?: string;

  /** Description of the route's purpose */
  description?: string;

  /** Additional custom metadata */
  [key: string]: any;
}
```

### IntrospectionResult

Complete analysis result.

```typescript
interface IntrospectionResult {
  /** Project information */
  project: ProjectInfo;

  /** All detected routes */
  routes: RouteInfo[] | Record<string, any>;

  /** Analysis metadata */
  metadata: {
    /** Analysis timestamp */
    analyzedAt: Date;

    /** Analysis duration in milliseconds */
    duration: number;

    /** Total files processed */
    filesProcessed: number;

    /** Analysis mode used */
    mode: OutputMode;

    /** Merge timestamp (for merged results) */
    mergedAt?: Date;

    /** Source file for merged results */
    mergeSource?: string;
  };
}
```

## Enums and Constants

### OutputFormat

```typescript
type OutputFormat = 'object' | 'json' | 'markdown' | 'typescript';
```

### OutputMode

```typescript
type OutputMode = 'basic' | 'detailed' | 'comprehensive';
```

### RouterType

```typescript
type RouterType = 'app' | 'pages' | 'both';
```

### ComponentType

```typescript
type ComponentType = 'server' | 'client' | 'unknown';
```

### RoutePattern

```typescript
type RoutePattern = 'static' | 'dynamic' | 'catch-all' | 'optional-catch-all';
```

## Utility Functions

### isNextJsProject()

Checks if a directory is a Next.js project.

```typescript
function isNextJsProject(projectPath: string): Promise<boolean>
```

### detectRouterType()

Detects the router type used in a Next.js project.

```typescript
function detectRouterType(projectPath: string): Promise<RouterType>
```

### parseRouteSegment()

Parses a route segment string.

```typescript
function parseRouteSegment(segment: string): RouteSegment
```

### formatRoutePath()

Formats a route path for display.

```typescript
function formatRoutePath(path: string, style?: string, baseDir?: string): string
```

### detectComponentType()

Detects if a component is server or client.

```typescript
function detectComponentType(filePath: string): Promise<ComponentType>
```

### routesToNested()

Converts flat routes array to nested structure.

```typescript
function routesToNested(routes: RouteInfo[], includeEmptySegments?: boolean): Record<string, any>
```

### routesToArray()

Converts nested routes back to flat array.

```typescript
function routesToArray(nestedRoutes: Record<string, any>): RouteInfo[]
```

### parseMetadataFile()

Parses metadata from JSON or TOML file.

```typescript
function parseMetadataFile(filePath: string): Promise<Record<string, RouteMetadata>>
```

### mergeRouteMetadata()

Merges metadata into routes.

```typescript
function mergeRouteMetadata(routes: RouteInfo[], metadata: Record<string, RouteMetadata>): RouteInfo[]
```

### filterExcludedFields()

Filters out specified fields from result object.

```typescript
function filterExcludedFields(result: IntrospectionResult, excludeFields: string[]): IntrospectionResult
```

### formatPathForDisplay()

Formats file paths according to display options.

```typescript
function formatPathForDisplay(
  filePath: string,
  projectRoot: string,
  sourceDirs: Record<string, string>,
  pathDisplay: any
): string
```

## Adapters

### BaseAdapter

Base class for framework adapters.

```typescript
abstract class BaseAdapter {
  abstract name: string;
  abstract detect(projectPath: string): Promise<boolean>;
  abstract getProjectInfo(projectPath: string): Promise<ProjectInfo>;
  abstract getRoutes(projectPath: string, mode: OutputMode): Promise<RouteInfo[]>;
}
```

### NextJsAdapter

Next.js specific adapter implementation.

```typescript
class NextJsAdapter extends BaseAdapter {
  name = 'nextjs';
  detect(projectPath: string): Promise<boolean>;
  getProjectInfo(projectPath: string, packageDisplay?: any): Promise<ProjectInfo>;
  getRoutes(projectPath: string, mode: OutputMode): Promise<RouteInfo[]>;
}
```

## Parsers

### AppRouterParser

Parses App Router routes.

```typescript
class AppRouterParser {
  constructor(config: ParserConfig);
  parse(): Promise<AppRouterRoute[]>;
  parseRouteFile(filePath: string): Promise<AppRouterRoute>;
  getSpecialFiles(dirPath: string): Promise<Record<string, boolean>>;
  detectComponentType(filePath: string): Promise<ComponentType>;
}
```

### PagesRouterParser

Parses Pages Router routes.

```typescript
class PagesRouterParser {
  constructor(config: ParserConfig);
  parse(): Promise<PagesRouterRoute[]>;
  parseRouteFile(filePath: string): Promise<PagesRouterRoute>;
  detectApiRoute(filePath: string): Promise<boolean>;
  getDataFetchingMethods(filePath: string): Promise<Record<string, boolean>>;
}
```

### ConfigParser

Parses Next.js configuration.

```typescript
class ConfigParser {
  static parseConfig(projectPath: string): Promise<NextConfig>;
  static parsePackageJson(projectPath: string): Promise<PackageInfo>;
  static detectRouterType(projectPath: string): Promise<RouterType>;
}
```

## Formatters

### Base Formatter Interface

```typescript
interface Formatter {
  format(result: IntrospectionResult): string | object;
  getFormatType(): OutputFormat;
}
```

### ObjectFormatter

Returns raw JavaScript objects.

```typescript
class ObjectFormatter implements Formatter {
  format(result: IntrospectionResult): object;
  getFormatType(): OutputFormat;
}
```

### JsonFormatter

Formats results as JSON.

```typescript
class JsonFormatter implements Formatter {
  constructor(options?: { indent?: number });
  format(result: IntrospectionResult): string;
  getFormatType(): OutputFormat;
}
```

### MarkdownFormatter

Formats results as Markdown documentation.

```typescript
class MarkdownFormatter implements Formatter {
  format(result: IntrospectionResult): string;
  getFormatType(): OutputFormat;
  private formatRoute(route: RouteInfo): string;
  private formatProjectInfo(project: ProjectInfo): string;
}
```

### TypeScriptFormatter

Generates TypeScript type definitions and route helpers.

```typescript
class TypeScriptFormatter implements Formatter {
  constructor(options?: { stripPrefixes?: string[] });
  format(result: IntrospectionResult): string;
  getFormatType(): OutputFormat;
  private generateRouteTypes(routes: RouteInfo[]): string;
  private generateRouteHelpers(routes: RouteInfo[]): string;
}
```

## Error Types

next-introspect throws specific error types for different failure scenarios.

### InvalidProjectError

Thrown when the specified path is not a valid Next.js project.

```typescript
class InvalidProjectError extends Error {
  constructor(projectPath: string);
}
```

### AnalysisError

Thrown when analysis fails.

```typescript
class AnalysisError extends Error {
  constructor(message: string, cause?: Error);
}
```

### FormatterError

Thrown when formatting fails.

```typescript
class FormatterError extends Error {
  constructor(format: OutputFormat, cause?: Error);
}
```

## Constants

### DEFAULT\_OPTIONS

Default introspection options.

```typescript
const DEFAULT_OPTIONS: IntrospectionOptions = {
  mode: 'comprehensive',
  maxDepth: 10,
  followSymlinks: false
};
```

### SUPPORTED\_FORMATS

Supported output formats.

```typescript
const SUPPORTED_FORMATS: OutputFormat[] = [
  'object',
  'json',
  'markdown',
  'typescript'
];
```

### SUPPORTED\_MODES

Supported analysis modes.

```typescript
const SUPPORTED_MODES: OutputMode[] = [
  'basic',
  'detailed',
  'comprehensive'
];
```

## Migration Guide

### From v0.2.x to v0.3.x

**Breaking Changes:**

* `Introspect` class renamed to `NextIntrospect`
* `getAllRoutes()` renamed to `getRoutes()`
* `export()` renamed to `format()`
* Configuration structure updated

**Migration:**

```typescript
// Before
import { Introspect } from 'next-introspect';
const introspect = new Introspect('./', { mode: 'detailed' });
await introspect.analyze();
const routes = introspect.getAllRoutes();
const output = introspect.export('json');

// After
import { NextIntrospect } from 'next-introspect';
const introspect = new NextIntrospect('./', { mode: 'detailed' });
await introspect.analyze();
const routes = introspect.getRoutes();
const output = introspect.format('json');
```

For more detailed migration information, see the [changelog](https://github.com/benfavre/next-introspect/blob/main/CHANGELOG.md).


# Programmatic API

# Programmatic API

Use next-introspect directly in your code for custom integrations, build tools, or automated workflows.

## Basic Usage

```typescript
import { NextIntrospect } from 'next-introspect';

// Create introspector instance
const introspect = new NextIntrospect('/path/to/nextjs/project', {
  mode: 'comprehensive'
});

// Analyze project
const projectInfo = await introspect.analyze();

// Get routes
const routes = introspect.getRoutes();

// Export results
await introspect.exportToFile('routes.json', 'json');
```

## Configuration Options

```typescript
import { NextIntrospect } from 'next-introspect';

const introspect = new NextIntrospect('./my-nextjs-app', {
  // Analysis mode: 'basic' | 'detailed' | 'comprehensive'
  mode: 'comprehensive',

  // Path display options
  pathDisplay: {
    style: 'relative-to-project',
    showFilePaths: true,
    stripPrefix: 'src/'
  },

  // Package display options
  packageDisplay: {
    includeFullDetails: false,
    includeScripts: true,
    includeDependencies: true
  },

  // Output formatting
  outputFormat: {
    nested: true,
    includeEmptySegments: false,
    excludeFields: ['filePath', 'pattern'],
    stripPrefixes: ['/api/', '/_next/']
  },

  // Metadata integration
  metadata: {
    file: './metadata.json'
  }
});
```

## Working with Results

### Get All Routes

```typescript
const routes = introspect.getRoutes();

routes.forEach(route => {
  console.log(`Route: ${route.path}`);
  console.log(`File: ${route.filePath}`);
  console.log(`Router: ${route.router}`);
  console.log(`Pattern: ${route.pattern}`);
});
```

### Filter Routes by Type

```typescript
// Get all API routes (Pages Router only)
const apiRoutes = introspect.getApiRoutes();

// Get all dynamic routes
const dynamicRoutes = introspect.getDynamicRoutes();

// Get routes by router type
const appRoutes = introspect.getRoutesByRouter('app');
const pagesRoutes = introspect.getRoutesByRouter('pages');
```

### Export in Different Formats

```typescript
// Get results as object
const results = introspect.getResult();

// Format as JSON
const jsonOutput = introspect.format('json');

// Format as Markdown
const markdownOutput = introspect.format('markdown');

// Format as TypeScript
const typescriptOutput = introspect.format('typescript');
```

## Advanced Usage

### Merging Results

```typescript
// Merge existing JSON with new metadata
const mergedResult = await introspect.mergeWithJson(
  'existing-routes.json',
  {
    '/blog': { title: 'Blog', description: 'Company blog posts' },
    '/about': { title: 'About Us', description: 'Learn about our company' }
  }
);
```

### Re-analysis

```typescript
// Initial analysis
await introspect.analyze();

// ... later, when files have changed
await introspect.reanalyze();
```

### Custom Metadata Integration

```typescript
// Load custom metadata
const metadata = {
  '/products/[id]': {
    title: 'Product Details',
    description: 'View detailed product information',
    customField: 'special handling required'
  }
};

// Create introspector with metadata
const introspect = new NextIntrospect('./', {
  metadata: {
    entries: metadata
  }
});
```

## TypeScript Integration

### Type-Safe Route Access

```typescript
// Generate TypeScript definitions
await introspect.exportToFile('routes.ts', 'typescript');

// Use in your code
import { routes } from './routes';

// Type-safe route generation
const productUrl = routes.products.byId({ id: '123' });
const categoryUrl = routes.categories.bySlug({ slug: 'electronics' });
const blogPostUrl = routes.blog.posts.byId({ id: '456', slug: 'my-post' });
```

### Type Definitions

```typescript
import type {
  NextIntrospect,
  IntrospectionOptions,
  IntrospectionResult,
  RouteInfo,
  ProjectInfo,
  OutputFormat,
  OutputMode
} from 'next-introspect';

const options: IntrospectionOptions = {
  mode: 'comprehensive',
  pathDisplay: {
    style: 'relative-to-project',
    showFilePaths: true
  }
};

const introspect: NextIntrospect = new NextIntrospect('./', options);
```

## Build Tool Integration

### Webpack Plugin Example

```javascript
// next-introspect-webpack-plugin.js
const { NextIntrospect } = require('next-introspect');

class NextIntrospectWebpackPlugin {
  constructor(options = {}) {
    this.options = options;
  }

  apply(compiler) {
    compiler.hooks.beforeCompile.tapPromise('NextIntrospectPlugin', async () => {
      const introspect = new NextIntrospect(this.options.projectPath || './', {
        mode: 'basic',
        ...this.options
      });

      await introspect.analyze();
      await introspect.exportToFile(this.options.output || 'routes.json', 'json');
    });
  }
}

module.exports = NextIntrospectWebpackPlugin;
```

### Vite Plugin Example

```typescript
// next-introspect-vite-plugin.ts
import { NextIntrospect } from 'next-introspect';
import type { Plugin } from 'vite';

export function nextIntrospectPlugin(options: {
  output?: string;
  format?: 'json' | 'typescript';
} = {}): Plugin {
  let introspect: NextIntrospect;

  return {
    name: 'next-introspect',
    buildStart() {
      introspect = new NextIntrospect('./', { mode: 'comprehensive' });
    },
    buildEnd() {
      // Generate route information after build
      introspect.analyze().then(() => {
        return introspect.exportToFile(
          options.output || 'routes.json',
          options.format || 'json'
        );
      });
    }
  };
}
```

## CI/CD Integration

### GitHub Actions Example

```yaml
# .github/workflows/routes-check.yml
name: Route Analysis
on:
  push:
    paths:
      - 'app/**'
      - 'pages/**'
      - 'next.config.js'

jobs:
  analyze-routes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      - run: bun add next-introspect
      - name: Analyze routes
        run: bunx next-introspect introspect . --format json --output routes.json
      - name: Upload routes artifact
        uses: actions/upload-artifact@v3
        with:
          name: routes-analysis
          path: routes.json
```

### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit

# Run route analysis before commit
bunx next-introspect introspect . --format json --output routes.json

# Add to staging if routes changed
if git diff --quiet routes.json; then
  echo "Routes unchanged"
else
  echo "Routes updated, adding to commit"
  git add routes.json
fi
```

## Error Handling

```typescript
try {
  const introspect = new NextIntrospect(projectPath);
  await introspect.analyze();
  const routes = introspect.getRoutes();

  // Process routes...
} catch (error) {
  if (error.message.includes('Invalid Next.js project')) {
    console.error('The specified path is not a valid Next.js project');
    console.error('Make sure it contains package.json with Next.js dependency');
  } else {
    console.error('Analysis failed:', error.message);
  }
  process.exit(1);
}
```

## Performance Optimization

### Incremental Analysis

```typescript
class CachedIntrospect {
  private cache = new Map<string, { routes: RouteInfo[], timestamp: number }>();
  private cacheTimeout = 5 * 60 * 1000; // 5 minutes

  async getRoutes(projectPath: string): Promise<RouteInfo[]> {
    const cached = this.cache.get(projectPath);
    const now = Date.now();

    if (cached && (now - cached.timestamp) < this.cacheTimeout) {
      return cached.routes;
    }

    const introspect = new NextIntrospect(projectPath, { mode: 'basic' });
    await introspect.analyze();
    const routes = introspect.getRoutes();

    this.cache.set(projectPath, { routes, timestamp: now });
    return routes;
  }
}
```

### Parallel Processing

```typescript
async function analyzeMultipleProjects(projectPaths: string[]) {
  const results = await Promise.allSettled(
    projectPaths.map(async (path) => {
      const introspect = new NextIntrospect(path, { mode: 'basic' });
      await introspect.analyze();
      return {
        path,
        routes: introspect.getRoutes(),
        project: introspect.getProjectInfo()
      };
    })
  );

  // Handle results...
  results.forEach((result, index) => {
    if (result.status === 'fulfilled') {
      console.log(`${projectPaths[index]}: ${result.value.routes.length} routes`);
    } else {
      console.error(`${projectPaths[index]}: ${result.reason.message}`);
    }
  });
}
```


# Configuration

# Configuration

next-introspect offers extensive configuration options to customize analysis behavior and output formatting.

## Analysis Modes

### Basic Mode

Fastest analysis with essential route information.

```bash
next-introspect introspect . --mode basic
```

**Includes:**

* Route paths and patterns
* Basic route metadata
* Router type detection

### Detailed Mode

Includes component analysis and extended metadata.

```bash
next-introspect introspect . --mode detailed
```

**Includes:**

* All basic mode data
* Component types (server/client)
* Special files detection
* Route groups and intercepting routes

### Comprehensive Mode

Complete analysis with all available metadata.

```bash
next-introspect introspect . --mode comprehensive
```

**Includes:**

* All detailed mode data
* Export analysis (metadata, generateStaticParams, etc.)
* Data fetching methods (getServerSideProps, getStaticProps)
* API route method detection

## Path Display Options

### Path Styles

#### Absolute Paths (Default)

```bash
next-introspect introspect . --path-style absolute
```

Shows full absolute paths to files.

#### Relative to Project Root

```bash
next-introspect introspect . --path-style relative-to-project
```

Shows paths relative to the project root directory.

#### Relative to App Directory

```bash
next-introspect introspect . --path-style relative-to-app
```

Shows paths relative to the `app/` directory (App Router).

#### Relative to Pages Directory

```bash
next-introspect introspect . --path-style relative-to-pages
```

Shows paths relative to the `pages/` directory (Pages Router).

#### Strip Prefix

```bash
next-introspect introspect . --path-style strip-prefix --strip-prefix "src/"
```

Removes specified prefix from paths.

### Multiple Prefix Stripping

```bash
next-introspect introspect . --strip-prefixes "src/app/" "packages/"
```

## Package Information Display

### Package Summary

```bash
next-introspect introspect . --package-summary
```

Shows only essential package.json information:

* Name and version
* Dependency counts
* Framework detection

### Include Scripts

```bash
next-introspect introspect . --package-summary --include-scripts
```

Includes the scripts section in the summary.

### Include Dependencies

```bash
next-introspect introspect . --package-summary --include-deps
```

Includes dependencies and devDependencies in the summary.

## Output Formatting

### Nested Structure

```bash
next-introspect introspect . --nested --format json
```

Organizes routes in a hierarchical structure instead of a flat array.

### Include Empty Segments

```bash
next-introspect introspect . --nested --include-empty-segments --format json
```

Includes empty path segments in the nested structure.

### Field Exclusion

```bash
next-introspect introspect . --exclude-fields "filePath,pattern,router"
```

Excludes specified fields from the output. Useful for reducing payload size or focusing on specific data.

**Common exclusions:**

* `filePath` - Remove file system paths
* `pattern` - Remove route pattern information
* `router` - Remove router type information
* `dynamicSegments` - Remove dynamic segment details
* `componentTypes` - Remove component type analysis

### TypeScript Strip Prefixes

```bash
next-introspect introspect . --format typescript --strip-prefixes "/api/" "/_next/"
```

Removes specified prefixes from generated TypeScript route paths.

## Metadata Integration

### Metadata File

```bash
next-introspect introspect . --metadata metadata.json
```

Loads additional metadata from a JSON file to enhance route information.

### Metadata File Format

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

### TOML Support

next-introspect also supports TOML format for metadata (basic support):

```toml
["/"]
title = "Homepage"
description = "Welcome to our website"

["/blog/[slug]"]
title = "Blog Post"
description = "Read our latest blog posts"
```

## Watch Mode Configuration

### Basic Watch

```bash
next-introspect introspect . --watch
```

### Watch with Custom Output

```bash
next-introspect introspect . --watch --format typescript --output routes.ts
```

### Quiet Watch

```bash
next-introspect introspect . --watch --quiet --output routes.json
```

### Watched File Types

Watch mode monitors these file extensions:

* `.js`, `.jsx`, `.ts`, `.tsx` - Route components and API handlers
* `.json` - Package.json and configuration files
* Configuration files - `next.config.*`, `tsconfig.json`

### Ignored Directories

Automatically ignores:

* `node_modules/` - Dependencies
* `.next/` - Build output
* `.git/` - Version control
* `dist/` - Distribution files
* `build/` - Build artifacts

## Programmatic Configuration

### TypeScript Configuration

```typescript
import { NextIntrospect } from 'next-introspect';

const introspect = new NextIntrospect('/path/to/project', {
  // Analysis mode
  mode: 'comprehensive',

  // Path display configuration
  pathDisplay: {
    style: 'relative-to-project',
    stripPrefix: 'src/',
    showFilePaths: true
  },

  // Package display options
  packageDisplay: {
    includeFullDetails: false,
    includeScripts: true,
    includeDependencies: false
  },

  // Output formatting
  outputFormat: {
    nested: false,
    includeEmptySegments: false,
    excludeFields: ['filePath'],
    stripPrefixes: ['/api/', '/_next/']
  },

  // Metadata integration
  metadata: {
    file: './metadata.json'
  }
});
```

### Configuration Types

```typescript
interface IntrospectionOptions {
  mode?: 'basic' | 'detailed' | 'comprehensive';
  maxDepth?: number;
  followSymlinks?: boolean;

  pathDisplay?: {
    style?: 'absolute' | 'relative-to-project' | 'relative-to-app' | 'relative-to-pages' | 'strip-prefix';
    stripPrefix?: string;
    showFilePaths?: boolean;
  };

  packageDisplay?: {
    includeFullDetails?: boolean;
    includeScripts?: boolean;
    includeDependencies?: boolean;
  };

  outputFormat?: {
    nested?: boolean;
    includeEmptySegments?: boolean;
    excludeFields?: string[];
    stripPrefixes?: string[];
  };

  metadata?: {
    file?: string;
    entries?: Record<string, RouteMetadata>;
  };
}
```

## Environment-Specific Configuration

### Development Configuration

```typescript
const devConfig: IntrospectionOptions = {
  mode: 'comprehensive',
  pathDisplay: {
    style: 'relative-to-project',
    showFilePaths: true
  },
  outputFormat: {
    excludeFields: []
  }
};
```

### Production Configuration

```typescript
const prodConfig: IntrospectionOptions = {
  mode: 'basic',
  pathDisplay: {
    style: 'strip-prefix',
    stripPrefix: '/app/',
    showFilePaths: false
  },
  outputFormat: {
    excludeFields: ['filePath', 'componentTypes']
  }
};
```

### CI/CD Configuration

```typescript
const ciConfig: IntrospectionOptions = {
  mode: 'detailed',
  outputFormat: {
    nested: true,
    excludeFields: ['filePath']
  }
};
```

## Configuration File Support

### next-introspect.config.js

```javascript
module.exports = {
  mode: 'comprehensive',
  pathDisplay: {
    style: 'relative-to-project',
    showFilePaths: true
  },
  outputFormat: {
    nested: false,
    excludeFields: ['filePath']
  },
  metadata: {
    file: './metadata.json'
  }
};
```

### next-introspect.config.ts

```typescript
import type { IntrospectionOptions } from 'next-introspect';

const config: IntrospectionOptions = {
  mode: 'comprehensive',
  pathDisplay: {
    style: 'relative-to-project',
    showFilePaths: true
  },
  outputFormat: {
    excludeFields: ['filePath']
  }
};

export default config;
```

## Performance Tuning

### Fast Analysis

```bash
next-introspect introspect . --mode basic --quiet
```

### Memory Optimization

```bash
next-introspect introspect . --exclude-fields "componentTypes,exports,dataFetching"
```

### Large Project Handling

```bash
next-introspect introspect . --mode basic --exclude-fields "filePath,dynamicSegments"
```

## Validation and Error Handling

### Configuration Validation

next-introspect validates configuration options and provides helpful error messages:

```
Error: Invalid mode 'fast'. Valid modes: basic, detailed, comprehensive
Error: Invalid path style 'relative'. Valid styles: absolute, relative-to-project, relative-to-app, relative-to-pages, strip-prefix
```

### Graceful Degradation

If optional configuration files are missing, next-introspect continues with defaults:

```bash
# This works even if metadata.json doesn't exist
next-introspect introspect . --metadata metadata.json
```

## Best Practices

### Development

* Use `--mode comprehensive` for full analysis during development
* Use `--path-style relative-to-project` for readable paths
* Include `--show-file-paths` for debugging

### Production

* Use `--mode basic` for faster builds
* Use `--exclude-fields` to reduce output size
* Use `--strip-prefix` to normalize paths

### CI/CD

* Use `--quiet` to reduce log noise
* Use `--format json` for machine-readable output
* Use `--output` to save results for later processing

### Documentation

* Use `--format markdown` for human-readable docs
* Use `--metadata` to add descriptions and titles
* Use `--nested` for hierarchical route visualization


# Examples & Tutorials

# Examples & Tutorials

This section provides practical examples and tutorials for using next-introspect in various scenarios.

## Quick Start Examples

### Basic Route Analysis

```bash
# Analyze your current project
next-introspect introspect .

# Analyze a specific project
next-introspect introspect /path/to/my-nextjs-app

# Save results to a file
next-introspect introspect . --output routes.json
```

### Generate Documentation

```bash
# Create Markdown documentation
next-introspect introspect . --format markdown --output ROUTES.md

# Include metadata for better descriptions
next-introspect introspect . --format markdown --metadata metadata.json --output ROUTES.md
```

### Type-Safe Route Generation

```bash
# Generate TypeScript route helpers
next-introspect introspect . --format typescript --output routes.ts
```

Then use in your code:

```typescript
import { routes } from './routes';

// Type-safe route generation
const homeUrl = routes.$;
const blogPostUrl = routes.blog.$slug({ slug: 'my-article' });
const apiUrl = routes.api.users.$id({ id: '123' });
```

## Real-World Use Cases

### Development Workflow Integration

#### Automatic Route Generation During Development

```bash
# Watch mode for continuous route generation
next-introspect introspect . --watch --format typescript --output src/routes.ts
```

This keeps your route definitions up-to-date as you add new pages and API routes.

#### Build-Time Route Validation

Add to your `package.json`:

```json
{
  "scripts": {
    "build": "next-introspect introspect . --mode basic --quiet && next build",
    "dev": "next-introspect introspect . --watch --format typescript --output routes.ts & next dev"
  }
}
```

### Documentation Generation

#### API Documentation

```bash
# Generate API route documentation
next-introspect introspect . --mode comprehensive --format markdown --output API-ROUTES.md
```

#### Route Inventory for Large Applications

```bash
# Comprehensive route analysis for enterprise apps
next-introspect introspect . \
  --mode comprehensive \
  --format json \
  --nested \
  --include-empty-segments \
  --output route-inventory.json
```

### CI/CD Integration

#### Route Change Detection

```yaml
# .github/workflows/route-check.yml
name: Route Analysis
on:
  pull_request:
    paths:
      - 'app/**'
      - 'pages/**'

jobs:
  analyze-routes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      - name: Install next-introspect
        run: bun add -g next-introspect
      - name: Analyze routes
        run: next-introspect introspect . --format json --output routes.json
      - name: Upload route analysis
        uses: actions/upload-artifact@v3
        with:
          name: route-analysis
          path: routes.json
```

#### Documentation Deployment

```yaml
# Deploy route documentation to GitHub Pages
name: Deploy Route Docs
on:
  push:
    branches: [main]

jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      - name: Generate documentation
        run: |
          bun add -g next-introspect
          next-introspect introspect . --format markdown --metadata docs-metadata.json --output docs/ROUTES.md
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
```

## Advanced Examples

### Custom Route Metadata

Create a `metadata.json` file:

```json
{
  "/": {
    "title": "Homepage",
    "description": "Main landing page",
    "category": "public",
    "authRequired": false
  },
  "/dashboard": {
    "title": "Dashboard",
    "description": "User dashboard with analytics",
    "category": "authenticated",
    "authRequired": true,
    "roles": ["user", "admin"]
  },
  "/api/users": {
    "title": "Users API",
    "description": "CRUD operations for user management",
    "category": "api",
    "methods": ["GET", "POST", "PUT", "DELETE"],
    "authRequired": true
  },
  "/blog/[slug]": {
    "title": "Blog Post",
    "description": "Individual blog post pages",
    "category": "content",
    "dynamic": true,
    "params": {
      "slug": {
        "type": "string",
        "description": "URL-friendly post identifier"
      }
    }
  }
}
```

Use with analysis:

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

### Multi-Environment Route Analysis

#### Development Environment

```bash
next-introspect introspect . \
  --mode comprehensive \
  --path-style relative-to-project \
  --show-file-paths \
  --format json \
  --output routes-dev.json
```

#### Production Environment

```bash
next-introspect introspect . \
  --mode basic \
  --path-style strip-prefix \
  --strip-prefix "/app/" \
  --exclude-fields "filePath,componentTypes" \
  --format json \
  --output routes-prod.json
```

### API Route Analysis

Focus specifically on API routes:

```bash
# Get all API routes
next-introspect introspect . --format json | jq '.routes[] | select(.path | startswith("/api/"))'
```

Or programmatically:

```typescript
import { NextIntrospect } from 'next-introspect';

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

const apiRoutes = introspect.getRoutes().filter(route =>
  route.path.startsWith('/api/')
);

console.log('API Routes:', apiRoutes);
```

### Dynamic Route Analysis

Find all dynamic routes:

```typescript
const dynamicRoutes = introspect.getDynamicRoutes();

dynamicRoutes.forEach(route => {
  console.log(`Dynamic route: ${route.path}`);
  console.log(`Parameters: ${route.dynamicSegments?.join(', ')}`);
  console.log(`Pattern: ${route.pattern}`);
});
```

### Route Change Detection

Compare route structures between commits:

```bash
# Get current routes
next-introspect introspect . --format json --output routes-current.json

# Get previous routes (from git)
git show HEAD~1:routes.json > routes-previous.json

# Compare
diff routes-previous.json routes-current.json || echo "Routes have changed"
```

## Framework-Specific Examples

### App Router Examples

#### Route Groups Analysis

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

const routeGroups = introspect.getRoutes().filter(route =>
  route.appRouter?.isRouteGroup
);

console.log('Route Groups:', routeGroups);
```

#### Intercepting Routes

```typescript
const interceptingRoutes = introspect.getRoutes().filter(route =>
  route.appRouter?.isInterceptingRoute
);

interceptingRoutes.forEach(route => {
  console.log(`Intercepting route: ${route.path}`);
  console.log(`Intercepts: ${route.appRouter?.segment}`);
});
```

#### Parallel Routes

```typescript
const parallelRoutes = introspect.getRoutes().filter(route =>
  route.appRouter?.isParallelRoute
);

parallelRoutes.forEach(route => {
  console.log(`Parallel route: ${route.path}`);
  console.log(`Slot: ${route.appRouter?.segment}`);
});
```

### Pages Router Examples

#### API Routes Analysis

```typescript
const apiRoutes = introspect.getApiRoutes();

apiRoutes.forEach(route => {
  console.log(`API Route: ${route.path}`);
  console.log(`File: ${route.filePath}`);
  console.log(`Is API: ${route.pagesRouter?.isApiRoute}`);
});
```

#### Special Pages

```typescript
const specialPages = introspect.getSpecialPages();

specialPages.forEach(route => {
  console.log(`Special page: ${route.path}`);
  console.log(`Type: ${route.pagesRouter?.specialPageType}`);
  console.log(`File: ${route.filePath}`);
});
```

#### Data Fetching Methods

```typescript
const routesWithDataFetching = introspect.getRoutes().filter(route =>
  route.pagesRouter?.dataFetching
);

routesWithDataFetching.forEach(route => {
  console.log(`Route: ${route.path}`);
  console.log(`Data fetching:`, route.pagesRouter?.dataFetching);
});
```

## Integration Examples

### With Build Tools

#### Vite Plugin

```typescript
// vite-plugin-routes.ts
import { NextIntrospect } from 'next-introspect';
import type { Plugin } from 'vite';

export function routesPlugin(): Plugin {
  return {
    name: 'routes',
    buildStart() {
      // Generate routes at build start
      const introspect = new NextIntrospect('./src', {
        mode: 'basic',
        outputFormat: { excludeFields: ['filePath'] }
      });

      introspect.analyze().then(() => {
        return introspect.exportToFile('./src/routes.ts', 'typescript');
      });
    }
  };
}
```

#### Webpack Plugin

```javascript
// NextIntrospectWebpackPlugin.js
const { NextIntrospect } = require('next-introspect');

class NextIntrospectWebpackPlugin {
  constructor(options = {}) {
    this.options = options;
  }

  apply(compiler) {
    compiler.hooks.beforeCompile.tapPromise('NextIntrospectPlugin', async () => {
      const introspect = new NextIntrospect(this.options.projectPath || './', {
        mode: 'basic',
        ...this.options
      });

      await introspect.analyze();
      await introspect.exportToFile(this.options.output || './routes.json', 'json');
    });
  }
}

module.exports = NextIntrospectWebpackPlugin;
```

### With Testing Frameworks

#### Route Testing Helper

```typescript
// test/helpers/routes.ts
import { NextIntrospect } from 'next-introspect';

let routesCache: any = null;

export async function getRoutes() {
  if (!routesCache) {
    const introspect = new NextIntrospect('./');
    await introspect.analyze();
    routesCache = introspect.getResult();
  }
  return routesCache;
}

export async function getRoute(path: string) {
  const result = await getRoutes();
  return result.routes.find((route: any) => route.path === path);
}
```

#### Route Existence Tests

```typescript
// tests/routes.test.ts
import { getRoutes, getRoute } from '../test/helpers/routes';

describe('Routes', () => {
  let routes: any;

  beforeAll(async () => {
    routes = await getRoutes();
  });

  test('should have homepage', async () => {
    const homeRoute = await getRoute('/');
    expect(homeRoute).toBeDefined();
    expect(homeRoute.router).toBe('app');
  });

  test('should have blog routes', async () => {
    const blogRoutes = routes.routes.filter((route: any) =>
      route.path.startsWith('/blog')
    );
    expect(blogRoutes.length).toBeGreaterThan(0);
  });

  test('should have API routes', async () => {
    const apiRoutes = routes.routes.filter((route: any) =>
      route.path.startsWith('/api')
    );
    expect(apiRoutes.length).toBeGreaterThan(0);
  });
});
```

### With Storybook

#### Route-Based Story Organization

```typescript
// .storybook/routes.ts
import { NextIntrospect } from 'next-introspect';

export async function generateStories() {
  const introspect = new NextIntrospect('../app'); // Adjust path
  await introspect.analyze();
  const routes = introspect.getRoutes();

  const stories = routes.map(route => ({
    title: `Routes/${route.path}`,
    component: () => <div>Route: {route.path}</div>,
    parameters: {
      route: route.path,
      filePath: route.filePath
    }
  }));

  return stories;
}
```

## Migration Examples

### From Pages Router to App Router

Track the migration progress:

```bash
# Analyze current state
next-introspect introspect . --format json --output migration-status.json

# Generate migration report
node scripts/migration-report.js migration-status.json
```

```typescript
// scripts/migration-report.js
const fs = require('fs');

const result = JSON.parse(fs.readFileSync(process.argv[2], 'utf-8'));

const pagesRoutes = result.routes.filter(r => r.router === 'pages');
const appRoutes = result.routes.filter(r => r.router === 'app');

console.log('Migration Status Report');
console.log('=======================');
console.log(`Pages Router routes: ${pagesRoutes.length}`);
console.log(`App Router routes: ${appRoutes.length}`);
console.log(`Migration progress: ${((appRoutes.length / (pagesRoutes.length + appRoutes.length)) * 100).toFixed(1)}%`);

// Identify routes that need migration
const apiRoutes = pagesRoutes.filter(r => r.pagesRouter?.isApiRoute);
console.log(`API routes to migrate: ${apiRoutes.length}`);

const dynamicRoutes = pagesRoutes.filter(r => r.pattern !== 'static');
console.log(`Dynamic routes to migrate: ${dynamicRoutes.length}`);
```

### Route Cleanup

Find unused or problematic routes:

```typescript
const introspect = new NextIntrospect('./');
await introspect.analyze();
const routes = introspect.getRoutes();

// Find routes without corresponding files
const missingFiles = routes.filter(route => {
  try {
    require('fs').accessSync(route.filePath);
    return false;
  } catch {
    return true;
  }
});

console.log('Routes with missing files:', missingFiles);

// Find API routes without proper HTTP methods
const apiRoutes = introspect.getApiRoutes();
const incompleteApiRoutes = apiRoutes.filter(route => {
  // Check if route file exports proper HTTP method handlers
  // Implementation depends on your analysis needs
});

console.log('Incomplete API routes:', incompleteApiRoutes);
```

## Performance Examples

### Large Project Optimization

```bash
# Fast analysis for large projects
next-introspect introspect . \
  --mode basic \
  --exclude-fields "componentTypes,exports,dataFetching" \
  --quiet \
  --output routes-fast.json
```

### Incremental Analysis

```typescript
class IncrementalAnalyzer {
  private lastAnalysis: number = 0;
  private cache: Map<string, any> = new Map();

  async analyzeIfNeeded(projectPath: string) {
    const stats = await fs.stat(projectPath);
    const mtime = stats.mtime.getTime();

    if (mtime > this.lastAnalysis) {
      const introspect = new NextIntrospect(projectPath, { mode: 'basic' });
      await introspect.analyze();
      this.cache.set(projectPath, introspect.getResult());
      this.lastAnalysis = mtime;
    }

    return this.cache.get(projectPath);
  }
}
```

These examples demonstrate how to integrate next-introspect into various development workflows, from simple CLI usage to complex programmatic integrations.


# Next.js Introspect

# Next.js Introspect

[<img alt="npm version" src="https://badge.fury.io/js/next-introspect.svg" width="133" height="20" />](https://badge.fury.io/js/next-introspect)
[<img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" width="82" height="20" />](https://opensource.org/licenses/MIT)

A comprehensive Next.js project introspection tool that analyzes routing structures, detects framework configurations, and provides detailed metadata about your Next.js application.

## 🚀 Quick Start

**Install globally for CLI usage:**

```bash
npm install -g next-introspect
# or
bun add -g next-introspect
```

**Analyze your Next.js project:**

*Using global installation:*

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

*Or run without global installation:*

```bash
# Using bunx
bunx next-introspect introspect . --format typescript --output routes.ts

# Using npx
npx next-introspect introspect . --format typescript --output routes.ts
```

**Use in your code:**

```typescript
import { routes } from './routes';

const postUrl = routes.blog.posts.byId({ id: "123" });
// → "/blog/posts/123"
```

## ✨ Features

* **Framework Detection**: Automatically detects Next.js projects and router types (App Router, Pages Router, or both)
* **Route Analysis**: Comprehensive analysis of all routes including dynamic routes, API routes, and special pages
* **Multiple Output Formats**: Export results as JavaScript objects, JSON, or Markdown documentation
* **Analysis Modes**: Choose between basic, detailed, or comprehensive analysis levels
* **App Router Support**: Full support for Next.js 13+ App Router with special files, route groups, and metadata
* **Pages Router Support**: Complete analysis of traditional Pages Router with API routes and data fetching
* **Configuration Parsing**: Extracts Next.js configuration and project metadata
* **CLI Tool**: Command-line interface for quick analysis and file export
* **Watch Mode**: Continuously monitor for file changes and auto-re-analyze
* **TypeScript**: Full TypeScript support with comprehensive type definitions

## 📚 Documentation

<Cards>
  <Card title="CLI Usage" href="/docs/cli-usage" description="Learn how to use the command-line interface" />

  <Card title="Programmatic API" href="/docs/api-usage" description="Use next-introspect in your code" />

  <Card title="Output Formats" href="/docs/output-formats" description="Explore different output formats" />

  <Card title="Configuration" href="/docs/configuration" description="Customize analysis options" />
</Cards>

## 🛠️ Installation

### Global Installation (CLI)

```bash
bun add -g next-introspect
# or
npm install -g next-introspect
```

### Local Installation (Programmatic)

```bash
bun add next-introspect
# or
npm install next-introspect
```


# Output Formats

# 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

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

### Pretty-printed JSON

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

### Example Output

```json
{
  "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

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

### With Metadata

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

### Example Output

```markdown
# 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

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

### With Custom Prefixes

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

### Example Output

```typescript
// 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

```typescript
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

```bash
next-introspect introspect . --format object
```

### Programmatic Usage

```typescript
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

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

### With Empty Segments

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

### Example Nested Output

```json
{
  "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:

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

### Path Formatting

Customize how paths are displayed:

```bash
# 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:

```json
{
  "/": {
    "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

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

### Enhanced Output with Metadata

```json
{
  "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


# CLI Usage

# Command Line Interface

The next-introspect CLI provides a powerful interface for analyzing Next.js projects from the command line.

## Basic Usage

```bash
# Analyze current directory
next-introspect introspect .

# Analyze specific project
next-introspect introspect /path/to/nextjs/project
```

## Output Formats

### JSON Output

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

### Markdown Documentation

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

### TypeScript Types

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

### Pretty-printed JSON

```bash
next-introspect introspect . --format json --indent 4
```

## Analysis Modes

### Basic Analysis (Fastest)

```bash
next-introspect introspect . --mode basic
```

Includes: route paths, patterns, and basic metadata.

### Detailed Analysis

```bash
next-introspect introspect . --mode detailed
```

Includes: component types, special files, and extended metadata.

### Comprehensive Analysis (Slowest)

```bash
next-introspect introspect . --mode comprehensive
```

Includes: all exports, data fetching methods, and complete metadata.

## Path Display Options

### Relative to Project Root

```bash
next-introspect introspect . --path-style relative-to-project --show-file-paths
```

### Relative to App Directory

```bash
next-introspect introspect . --path-style relative-to-app --show-file-paths
```

### Strip Custom Prefix

```bash
next-introspect introspect . --path-style strip-prefix --strip-prefix "src/app" --show-file-paths
```

## Advanced Options

### Quiet Mode

```bash
next-introspect introspect . --quiet --output result.json
```

### Exclude Fields

```bash
next-introspect introspect . --exclude-fields "filePath,pattern,router" --format json
```

### Nested Structure

```bash
next-introspect introspect . --nested --format json
```

### Include Empty Segments

```bash
next-introspect introspect . --nested --include-empty-segments --format json
```

### Package Summary

```bash
next-introspect introspect . --package-summary
next-introspect introspect . --package-summary --include-scripts --include-deps
```

### Metadata Integration

```bash
next-introspect introspect . --metadata metadata.json --format markdown
```

## Watch Mode

Watch mode continuously monitors your Next.js project for file changes and automatically re-runs the analysis.

### Basic Watch Mode

```bash
next-introspect introspect . --watch
```

### Watch with Custom Output

```bash
next-introspect introspect . --watch --format typescript --output routes.ts
```

### Quiet Watch Mode

```bash
next-introspect introspect . --watch --quiet --output routes.json
```

### Full Watch Command

```bash
next-introspect introspect . --watch --mode comprehensive --format markdown --output ROUTES.md
```

## Merge Command

Merge existing introspection results with additional metadata.

### Basic Merge

```bash
next-introspect merge routes.json metadata.json --output merged.json
```

### Merge with Field Filtering

```bash
next-introspect merge routes.json metadata.json --exclude-fields "filePath" --output clean.json
```

### Merge to Markdown

```bash
next-introspect merge routes.json metadata.json --format markdown --output merged.md
```

## Command Reference

### introspect

```bash
next-introspect introspect <projectPath> [options]
```

**Options:**

* `-f, --format <format>`: Output format (object, json, markdown, typescript)
* `-m, --mode <mode>`: Analysis mode (basic, detailed, comprehensive)
* `-o, --output <file>`: Write output to file instead of console
* `--indent <number>`: JSON indentation (default: 2)
* `--quiet`: Suppress progress messages
* `--path-style <style>`: Path display style (absolute, relative-to-project, relative-to-app, relative-to-pages, strip-prefix)
* `--strip-prefix <prefix>`: Prefix to strip from paths when using strip-prefix style
* `--strip-prefixes <prefix>`: Prefix to strip from route paths (can be used multiple times)
* `--show-file-paths`: Format file paths according to the path style
* `--package-summary`: Show only package.json summary
* `--include-scripts`: Include scripts section in summary
* `--include-deps`: Include dependencies/devDependencies in summary
* `--nested`: Output routes in nested hierarchical structure
* `--include-empty-segments`: Include empty path segments in nested structure
* `--exclude-fields <fields>`: Comma-separated list of fields to exclude
* `--metadata <file>`: Path to metadata file (JSON or TOML) with titles and descriptions
* `-w, --watch`: Watch mode: continuously monitor for file changes

### merge

```bash
next-introspect merge <jsonFile> <metadataFile> [options]
```

**Options:**

* `-o, --output <file>`: Write merged output to file instead of console
* `-f, --format <format>`: Output format for merged result
* `--indent <number>`: JSON indentation (default: 2)
* `--exclude-fields <fields>`: Comma-separated list of fields to exclude

## Examples

### Development Workflow

```bash
# Watch for changes during development
next-introspect introspect . --watch --format typescript --output src/routes.ts
```

### Documentation Generation

```bash
# Auto-update route documentation
next-introspect introspect . --watch --format markdown --output docs/ROUTES.md
```

### CI/CD Integration

```bash
# Monitor route changes in deployment pipeline
next-introspect introspect . --watch --quiet --output routes.json
```

### Advanced Analysis

```bash
# Full analysis with all options
next-introspect introspect /path/to/project \
  --format markdown \
  --mode comprehensive \
  --path-style relative-to-project \
  --show-file-paths \
  --package-summary \
  --include-scripts \
  --include-deps \
  --nested \
  --metadata metadata.json \
  --output project-routes.md
```


# Troubleshooting

# Troubleshooting

This guide helps you resolve common issues and problems when using next-introspect.

## Installation Issues

### Command Not Found

**Problem:** `next-introspect: command not found`

**Solutions:**

1. **Global Installation Check:**
   ```bash
   # Install globally
   npm install -g next-introspect
   # or
   bun add -g next-introspect

   # Check if installed
   which next-introspect
   next-introspect --version
   ```

2. **PATH Issues:**
   * On macOS/Linux, check if npm global bin directory is in PATH
   * On Windows, restart terminal or VS Code
   * Try using `npx next-introspect` instead

3. **Permission Issues:**
   ```bash
   # Try with sudo (not recommended)
   sudo npm install -g next-introspect

   # Or use a version manager
   bun add -g next-introspect
   ```

### Module Not Found (Local Installation)

**Problem:** `Cannot find module 'next-introspect'`

**Solutions:**

1. **Install Locally:**
   ```bash
   npm install next-introspect
   # or
   bun add next-introspect
   ```

2. **Use npx:**
   ```bash
   npx next-introspect introspect .
   ```

3. **Check package.json:**
   ```json
   {
     "devDependencies": {
       "next-introspect": "^0.3.16"
     }
   }
   ```

## Analysis Errors

### Invalid Next.js Project

**Problem:** `Error: Invalid Next.js project: /path/to/project`

**Solutions:**

1. **Check Project Structure:**
   * Ensure `package.json` exists with Next.js dependency
   * Check for `app/` directory (App Router) or `pages/` directory (Pages Router)
   * Verify Next.js is listed in dependencies

2. **Correct Package.json:**
   ```json
   {
     "dependencies": {
       "next": "^14.0.0"
     }
   }
   ```

3. **Framework Detection:**
   ```bash
   # Check if Next.js is detected
   ls -la package.json
   grep -i next package.json
   ```

### No Routes Found

**Problem:** Analysis completes but no routes are found

**Solutions:**

1. **Check Directory Structure:**
   ```bash
   # App Router
   ls -la app/
   ls -la app/**/

   # Pages Router
   ls -la pages/
   ls -la pages/**/
   ```

2. **File Extensions:**
   * Ensure files have correct extensions: `.js`, `.jsx`, `.ts`, `.tsx`
   * Check for TypeScript configuration if using `.ts`/`.tsx`

3. **Special Files:**
   * App Router: Check for `page.tsx`, `layout.tsx`, `route.ts`
   * Pages Router: Check for page files and API routes

### Permission Errors

**Problem:** `EACCES: permission denied` or `EPERM: operation not permitted`

**Solutions:**

1. **File Permissions:**
   ```bash
   # Check permissions
   ls -la /path/to/project

   # Fix permissions
   chmod -R 755 /path/to/project
   ```

2. **Run as Administrator:**
   ```bash
   # On macOS/Linux
   sudo next-introspect introspect .

   # On Windows (PowerShell as Admin)
   next-introspect introspect .
   ```

3. **Node Modules:**
   ```bash
   # Clear and reinstall
   rm -rf node_modules package-lock.json
   npm install
   ```

## Output Issues

### File Not Written

**Problem:** Analysis runs but output file is not created

**Solutions:**

1. **Directory Permissions:**
   ```bash
   # Check write permissions
   touch test-output.json && rm test-output.json

   # Create directory if needed
   mkdir -p output/dir/
   ```

2. **Relative Paths:**
   ```bash
   # Use absolute paths
   next-introspect introspect . --output /full/path/to/output.json

   # Or ensure current directory is writable
   pwd && ls -la
   ```

3. **File Locks:**
   * Close any applications that might have the file open
   * Wait a moment if another process is writing to the file

### Invalid JSON Output

**Problem:** JSON output is malformed or unreadable

**Solutions:**

1. **Pretty Print:**
   ```bash
   next-introspect introspect . --format json --indent 2 --output routes.json
   ```

2. **Validate JSON:**
   ```bash
   # Check if valid JSON
   cat routes.json | jq . > /dev/null && echo "Valid JSON" || echo "Invalid JSON"
   ```

3. **Large Files:**
   * Use `--indent 0` for compact JSON
   * Split analysis if project is very large

### TypeScript Compilation Errors

**Problem:** Generated TypeScript file has compilation errors

**Solutions:**

1. **Type Imports:**
   ```typescript
   // Ensure proper imports in generated file
   import type { RouteBuilder } from 'next-introspect';
   ```

2. **Type Conflicts:**
   * Check for conflicting type definitions
   * Use namespace imports to avoid conflicts

3. **Strip Prefixes:**
   ```bash
   # Use strip-prefixes to avoid path issues
   next-introspect introspect . --format typescript --strip-prefixes "/api/" "/_next/"
   ```

## Watch Mode Issues

### Watch Not Detecting Changes

**Problem:** Watch mode doesn't react to file changes

**Solutions:**

1. **File Types:**
   * Watch mode only monitors specific file types
   * Ensure changes are to `.js`, `.jsx`, `.ts`, `.tsx`, or `.json` files

2. **Ignored Directories:**
   * Changes in `node_modules/`, `.next/`, `.git/` are ignored
   * Move files outside ignored directories

3. **Debounce Timing:**
   * Wait at least 300ms between changes
   * Large projects may need longer debounce

### Watch Process Won't Stop

**Problem:** `Ctrl+C` doesn't stop watch mode

**Solutions:**

1. **Force Kill:**
   ```bash
   # Find process
   ps aux | grep next-introspect

   # Kill process
   kill -9 <PID>
   ```

2. **Port Conflicts:**
   * Check if another process is using the same resources
   * Restart terminal

### High CPU Usage in Watch Mode

**Problem:** Watch mode consumes excessive CPU

**Solutions:**

1. **Reduce Analysis Depth:**
   ```bash
   next-introspect introspect . --watch --mode basic
   ```

2. **Exclude Unnecessary Files:**
   ```bash
   next-introspect introspect . --watch --exclude-fields "componentTypes,exports"
   ```

3. **Increase Debounce:**
   * Currently fixed at 300ms
   * Consider using file system events instead

## Configuration Issues

### Metadata File Not Found

**Problem:** `--metadata file.json` shows warning about missing file

**Solutions:**

1. **File Path:**
   ```bash
   # Check file exists
   ls -la metadata.json

   # Use absolute path
   next-introspect introspect . --metadata /full/path/to/metadata.json
   ```

2. **File Format:**
   ```json
   {
     "/route/path": {
       "title": "Route Title",
       "description": "Route description"
     }
   }
   ```

3. **TOML Support:**
   * TOML support is limited
   * Use JSON format for best compatibility

### Invalid Configuration Options

**Problem:** `Error: Invalid [option] '[value]'`

**Solutions:**

1. **Check Valid Values:**
   * `--mode`: `basic`, `detailed`, `comprehensive`
   * `--format`: `object`, `json`, `markdown`, `typescript`
   * `--path-style`: `absolute`, `relative-to-project`, `relative-to-app`, `relative-to-pages`, `strip-prefix`

2. **Case Sensitivity:**
   * All option values are case-sensitive
   * Use exact values as shown in help

### Path Style Issues

**Problem:** Path formatting doesn't work as expected

**Solutions:**

1. **App/Pages Directories:**
   ```bash
   # Ensure correct directories exist
   ls -la app/ pages/
   ```

2. **Strip Prefix:**
   ```bash
   # Verify prefix exists in paths
   next-introspect introspect . --format json | grep "filePath"
   ```

3. **Show File Paths:**
   ```bash
   # Add --show-file-paths to see file path formatting
   next-introspect introspect . --path-style relative-to-project --show-file-paths
   ```

## Performance Issues

### Slow Analysis

**Problem:** Analysis takes too long

**Solutions:**

1. **Use Basic Mode:**
   ```bash
   next-introspect introspect . --mode basic
   ```

2. **Exclude Fields:**
   ```bash
   next-introspect introspect . --exclude-fields "componentTypes,exports,dataFetching"
   ```

3. **Limit Depth:**
   * Currently analyzes entire project
   * Consider analyzing specific directories

### Memory Issues

**Problem:** Out of memory errors

**Solutions:**

1. **Increase Memory:**
   ```bash
   NODE_OPTIONS="--max-old-space-size=4096" next-introspect introspect .
   ```

2. **Reduce Analysis:**
   ```bash
   next-introspect introspect . --mode basic --exclude-fields "exports,dataFetching"
   ```

3. **Split Analysis:**
   * Analyze different parts of the project separately
   * Use programmatic API for custom analysis

### Large Output Files

**Problem:** Generated files are too large

**Solutions:**

1. **Field Exclusion:**
   ```bash
   next-introspect introspect . --exclude-fields "filePath,componentTypes,exports"
   ```

2. **Compact JSON:**
   ```bash
   next-introspect introspect . --format json --indent 0
   ```

3. **Split Output:**
   * Generate separate files for different route types
   * Use programmatic API to filter results

## Framework-Specific Issues

### App Router Issues

**Problem:** App Router routes not detected correctly

**Solutions:**

1. **File Structure:**
   ```
   app/
   ├── layout.tsx
   ├── page.tsx
   ├── blog/
   │   ├── page.tsx
   │   └── [slug]/
   │       └── page.tsx
   └── api/
       └── users/
           └── route.ts
   ```

2. **Special Files:**
   * Ensure correct file names: `page.tsx`, `layout.tsx`, `route.ts`
   * Check for TypeScript configuration

3. **Route Groups:**
   ```bash
   # Route groups should be in parentheses
   ls -la app/(group)/
   ```

### Pages Router Issues

**Problem:** Pages Router routes not detected

**Solutions:**

1. **Directory Structure:**
   ```
   pages/
   ├── index.tsx
   ├── about.tsx
   ├── blog/
   │   ├── index.tsx
   │   └── [slug].tsx
   └── api/
       └── users.ts
   ```

2. **API Routes:**
   * API routes should export HTTP method handlers
   * Check file exports

3. **Special Pages:**
   * `_app.tsx`, `_document.tsx`, `_error.tsx` are detected as special pages

### Mixed Router Issues

**Problem:** Both App and Pages routers detected but causing conflicts

**Solutions:**

1. **Choose Primary Router:**
   ```bash
   # Analysis works with both, but focus on one
   next-introspect introspect . --format json | jq '.project.router'
   ```

2. **Separate Analysis:**
   * Analyze App Router routes: filter by `router === "app"`
   * Analyze Pages Router routes: filter by `router === "pages"`

## Integration Issues

### Build Tool Integration

**Problem:** next-introspect doesn't work in build scripts

**Solutions:**

1. **Script Timing:**
   ```json
   {
     "scripts": {
       "build": "next-introspect introspect . && next build"
     }
   }
   ```

2. **Error Handling:**
   ```json
   {
     "scripts": {
       "build": "next-introspect introspect . || echo 'Route analysis failed' && next build"
     }
   }
   ```

3. **Conditional Execution:**
   ```json
   {
     "scripts": {
       "build": "if [ \"$CI\" != \"true\" ]; then next-introspect introspect .; fi && next build"
     }
   }
   ```

### CI/CD Issues

**Problem:** next-introspect fails in CI environment

**Solutions:**

1. **Dependencies:**
   ```yaml
   - name: Install next-introspect
     run: npm install -g next-introspect
   ```

2. **Permissions:**
   ```yaml
   - name: Analyze routes
     run: next-introspect introspect . --output routes.json
   ```

3. **Caching:**
   ```yaml
   - name: Cache node modules
     uses: actions/cache@v3
     with:
       path: ~/.npm
       key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
   ```

## Debug Mode

### Verbose Output

```bash
# Enable verbose logging (if available)
DEBUG=* next-introspect introspect .

# Check Node.js version
node --version

# Check npm version
npm --version
```

### Manual Verification

```bash
# Check project structure
find . -name "*.tsx" -o -name "*.ts" -o -name "*.jsx" -o -name "*.js" | head -20

# Check package.json
cat package.json | jq '.dependencies.next'

# Test file access
ls -la app/page.tsx
ls -la pages/index.js
```

### Create Test Case

```bash
# Create minimal test project
mkdir test-project
cd test-project
npm init -y
npm install next react react-dom
mkdir app
echo 'export default function Home() { return <h1>Hello</h1>; }' > app/page.tsx
echo '{"scripts": {"dev": "next dev"}}' > package.json

# Test next-introspect
next-introspect introspect .
```

## Getting Help

### Issue Reporting

When reporting issues, please include:

1. **Version Information:**
   ```bash
   next-introspect --version
   node --version
   npm --version
   ```

2. **Project Information:**
   ```bash
   ls -la package.json
   grep -A5 -B5 '"next"' package.json
   find . -name "app" -o -name "pages" | head -5
   ```

3. **Command and Error:**
   ```bash
   # Exact command that failed
   next-introspect introspect . --format json
   ```

4. **Environment:**
   * Operating system and version
   * Shell being used
   * Any relevant environment variables

### Common Workarounds

1. **Use Basic Mode:** For performance issues, start with `--mode basic`
2. **Use Local Installation:** For permission issues, use `npx` or local installation
3. **Simplify Configuration:** Remove advanced options to isolate problems
4. **Check File Paths:** Ensure all paths are accessible and correct

If you continue to have issues, please check the [GitHub repository](https://github.com/benfavre/next-introspect) for existing issues or create a new issue with detailed information.