Next.js plugin for generating the Chrome DevTools project settings file on-the-fly during development. This is the Next.js equivalent of vite-plugin-devtools-json.

This enables seamless integration with the new Chrome DevTools features:

Features

✅ Universal compatibility: Works with Next.js 12, 13, 14, and 15+
✅ All routing systems: Supports both pages/ and app/ router
✅ All config formats: JavaScript, TypeScript, CommonJS, and ESM
✅ Monorepo friendly: Works in monorepo setups
✅ Zero configuration: Auto-setup with CLI command
✅ Development only: Only runs during npm run dev
✅ No API routes: Uses Next.js rewrites and standalone server

Installation

npm install --save-dev next-plugin-devtools-json

Usage

Run the setup command:

npx next-plugin-devtools-json

Or manually add to your Next.js config:

next.config.js (CommonJS):

const withDevToolsJSON = require('next-plugin-devtools-json');

const nextConfig = {
  // your config
};

module.exports = withDevToolsJSON(nextConfig);

next.config.mjs (ESM):

import withDevToolsJSON from 'next-plugin-devtools-json';

const nextConfig = {
  // your config
};

export default withDevToolsJSON(nextConfig);

How it works

This plugin runs a standalone HTTP server (on port 3001) during development and adds Next.js rewrites to proxy the DevTools endpoints to the server. This approach ensures compatibility with both Webpack and Turbopack while providing a truly plug-and-play experience without generating any files in your project.

The plugin serves the Chrome DevTools project settings JSON file at the well-known path (/.well-known/appspecific/com.chrome.devtools.json) as required by the Chrome DevTools specification, enabling Chrome DevTools to automatically recognize your local development project.

Endpoints available:

/.well-known/appspecific/com.chrome.devtools.json (Chrome DevTools standard)
/__devtools_json (alternative endpoint)

The endpoint serves the project settings as JSON with the following structure:

{
  "workspace": {
    "root": "/path/to/project/root",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}

Where root is the absolute path to your project root folder, and uuid is a random v4 UUID, generated the first time you start the Next.js dev server with the plugin installed (it's cached in .next/cache/ for consistency).

Why not a pure Next.js solution?

We investigated using API routes, middleware, or static files, but each approach has significant limitations:

API routes: Would require generating files in your project (not plug-and-play)
Middleware: Limited to Edge runtime (no file system access for UUID persistence)
Static files: Cannot generate dynamic content (workspace paths, UUIDs)

Our standalone server approach provides the best balance of plug-and-play setup, universal compatibility (Webpack + Turbopack), and reliable functionality. See docs/INVESTIGATION.md for detailed analysis.

Chrome DevTools Setup

To enable automatic workspace folder detection in Chrome DevTools:

Open Chrome DevTools
Go to Settings (F1 or click the gear icon)
Navigate to "Workspace"
Enable "Automatically add workspace folders"

Once enabled, Chrome DevTools will automatically detect your Next.js project when you visit http://localhost:3000 during development.

Troubleshooting

Port 3001 already in use? The plugin will log a warning but continue to work if port 3001 is occupied. You can specify a custom port:

module.exports = withDevToolsJSON(nextConfig, { port: 3002 });

Plugin not working? Make sure you're running in development mode (NODE_ENV=development or npm run dev) as the plugin is disabled in production for security.

Need a different port? You can specify a custom port if 3001 is occupied:

module.exports = withDevToolsJSON(nextConfig, { port: 3002 });

Why an extra server? This approach ensures compatibility with both Webpack and Turbopack while avoiding file generation in your project. See our investigation for details on why pure Next.js solutions aren't feasible.

Options

While the plugin can generate a UUID and save it in .next/cache/, you can also specify it in the options:

const withDevToolsJSON = require('next-plugin-devtools-json');

module.exports = withDevToolsJSON(nextConfig, {
  uuid: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
});

Available options:

uuid - Custom UUID for the workspace (optional, auto-generated if not provided)
endpoint - Custom endpoint path (optional, defaults to /__devtools_json)
enabled - Explicitly enable/disable the plugin (optional, defaults to true in development)
port - Custom port for the DevTools server (optional, defaults to 3001)