DOCSEARCHbyAlgolia
Submit Docs

next-lens

repository·main·Indexed 43 days ago

https://github.com/1weiho/next-lens

A lightweight CLI for the Next.js App Router that scans project directories to surface routes and stack details without requiring a Next.js runtime. It features route discovery for API and page routes, a visual Web Inspector UI, and Model Context Protocol (MCP) integration to expose routing insights to IDEs and AI copilots.

Tokens
15.1K
Snippets
71
Records
83
Agent score
53%

What's inside next-lens

  2. Explore the documentation application structure

    main

    The apps/docs application follows a standard Next.js App Router structure with Fumadocs integration:

    • app/(home): Route group containing the landing page and other top-level pages.
    • app/docs: Contains the documentation layout and specific documentation pages.
    • app/api/search/route.ts: The Route Handler responsible for handling search queries.
    • lib/source.ts: Contains the code for the content source adapter using the loader() interface.
    • lib/layout.shared.tsx: Contains shared layout options.

  3. Key features of next-lens

    main

    The tool provides several capabilities for inspecting Next.js App Router projects:

    • Route Discovery: Lists app/api/**/route.* with detected HTTP handlers and app/**/page.* with loading/error fallback coverage.
    • Visual Parsing: Colorizes dynamic, optional, and catch-all parameters for easier reading.
    • Flexible Execution: Works on any target directory (defaults to the current working directory).
    • Web Inspector: Launch a visual UI via next-lens web.
    • IDE Integration: Supports MCP (Model Context Protocol) server mode to expose routing tools to IDEs and AI copilots.

  4. How the Raycast Extension workflow works

    main

    The integration follows these steps:

    1. Run next-lens raycast in your Next.js project directory.
    2. The CLI starts an API server that exposes your project's route data.
    3. The Raycast extension connects to the local endpoint at http://localhost:9453/api (or your custom port).
    4. You can then search and browse routes within Raycast.

    The server remains active until you terminate the process with Ctrl+C.

  5. Quickstart with the next-lens CLI

    main

    The next-lens CLI allows you to scan a Next.js App Router project to map routes, list pages, and inspect API handlers without needing to run the Next.js development server.

    Prerequisites

    • Node.js: version 18 or higher.
    • Project Access: You must have access to the directory of the Next.js project you wish to scan.
    npx next-lens@latest web

  6. Start the Next Lens Inspector UI

    main

    Use the next-lens web command to run a local server that visualizes your Next.js App Router pages and API routes in a browser. This allows you to search and filter routes, modify HTTP methods on API routes, and open source files directly in your IDE.

    By default, it targets the current directory and opens http://localhost:9453 in your browser.

    npx next-lens web [target-directory]

  8. Enable type-aware ESLint rules

    main

    For production applications, it is recommended to enable type-aware lint rules by replacing tseslint.configs.recommended with one of the following in your ESLint configuration:

    • tseslint.configs.recommendedTypeChecked: Standard recommended type-aware rules.
    • tseslint.configs.strictTypeChecked: Stricter type-aware rules.
    • tseslint.configs.stylisticTypeChecked: Adds stylistic type-aware rules.

    When enabling these, you must configure languageOptions.parserOptions to include your project (e.g., ./tsconfig.app.json) and tsconfigRootDir so the parser can access type information.

    export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Replace tseslint.configs.recommended with:
      tseslint.configs.recommendedTypeChecked,
      // Or for stricter rules:
      // tseslinter.configs.strictTypeChecked,
      // Or for stylistic rules:
      // tseslint.configs.stylisticTypeChecked,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
])

  9. Integrate next-lens with MCP clients

    main

    You can expose next-lens route insights to IDEs or AI copilots by running a Model Context Protocol (MCP) server. To configure a client (such as Claude Desktop or other MCP-compatible tools), add a next-lens entry to your mcpServers configuration using npx to run the latest version of the tool with the mcp command.

    {
  "mcpServers": {
    "next-lens": {
      "command": "npx",
      "args": ["next-lens@latest", "mcp"]
    }
  }
}

  10. Run the documentation development server

    main

    To start the development server for the documentation site, use one of the following package manager commands from the root of the apps/docs directory. Once running, the site will be available at http://localhost:3000.

    npm run dev
# or
pnpm dev
# or
yarn dev