First-class extension API for Next.js development tooling (dev indicators and plugins)

[foxted]

Goals

1. Let apps and libraries add items to dev-only UI (for example the dev tools menu) through a documented file and API, not private hacks.
2. Give people a supported hook so fewer one-off forks and internal patches are needed.
3. Keep behaviour clear in dev; production should not pick up this code unless we explicitly say it can.
4. Make room for small dev-only helpers (health checks, RSC introspection, whatever) that ship with apps or packages instead of living in a fork of next.

Non-Goals

1. Replace or clone full React DevTools / the browser’s own devtools.
2. Ship a huge bundled “everything” devtools suite inside next by default.
3. This is not asking maintainers to lock down every part of the current dev tools implementation. It is asking for a small stable surface so extensions do not depend on private details.
4. Not about production builds or deployed apps. Only development UX. No requirement that production behaviour, bundle size, or security model changes for people who use this.

Background

Nuxt DevTools is the example I keep coming back to: dev-only UI that helps you understand the app without leaving the browser. Next.js does not need to copy that product, but the idea that the framework can host small dev tools in one predictable place is useful.

There is already community energy around this. next-devtools wraps Next with extra dev UI, which tells me people want more than ad hoc scripts or browser extensions.

On my side I maintain RSC Boundary. It wants a tiny dev-only signal so users know the tooling is on. I can ship a floating pill or something similar, but it would feel better if library authors could plug into the same dev tools surface Next.js already shows, instead of adding another overlay. SWR and other packages could also hook into this surface.

Right now, if you want to extend that area you mostly reach for internals or a fork. A small public extension point would make ecosystem tools easier to build and easier to trust.

Proposal

Ship a documented way to extend dev tooling: a root file convention plus a stable module (for example next/devtools) with primitives for menu items. Apps and packages compose those in one place so everything lines up with the built-in dev tools menu.

Before:

After:

Illustrative API (names and rules are up for debate)

1. Project root or src/: dev-indicators.tsx

The app registers indicators by default-exporting a single MenuItem, a component that renders MenuItem, or an array of those (each entry is one indicator).

// dev-indicators.tsx
// Example: a library *could* expose a devtools entry; the path is illustrative.
import { RscBoundaryIndicator } from 'rsc-boundary/devtools'
import { ApiHealthIndicator } from './devtools-api-health'
export default function DevIndicators() {
  return [<RscBoundaryIndicator />, <ApiHealthIndicator />]
}

2. Same pattern inside a package

A library ships an indicator component; the app imports and lists it.

// In a library package (example)
import { MenuItem, MenuItemLabel, MenuItemValue } from 'next/devtools'
export function RscBoundaryIndicator() {
  return (
    <MenuItem title="RSC boundary status">
      <MenuItemLabel>RSC boundary</MenuItemLabel>
      <MenuItemValue>Active</MenuItemValue>
    </MenuItem>
  )
}

3. Local or app-specific indicator

// devtools-api-health.tsx
import { MenuItem, MenuItemLabel, MenuItemValue } from 'next/devtools'
export function ApiHealthIndicator() {
  return (
    <MenuItem title="API health">
      <MenuItemLabel>API</MenuItemLabel>
      <MenuItemValue>Healthy (p95: 84ms)</MenuItemValue>
    </MenuItem>
  )
}

Open questions (for discussion)

Big unknowns for me: how indicator trees get evaluated (sync vs normal client mount), and what you allow inside leaf components (hooks or not). That changes ergonomics and bundles a lot, so I would rather take guidance from people who ship this every day.

I also assume this stays dev-only in practice and lines up with existing knobs like devIndicators where that already exists.

I would ship a small surface first (menu items and labels). If that works, more ambitious devtools UI can follow.

Sketch implementation

I have a rough branch and a demo app so people can click around. Neither is a promise about the final API.

Fork: foxted/next.js feat/devtools-plugins
Demo: foxted/dev-indicators-demo

The demo pins next to that fork (packages/next via git). If install does not run, build packages/next from the fork or point next at a local build, same idea as in the demo README.

Notes

I have not contributed to Next.js before. If the direction (official extension hooks for dev tooling) is interesting but this shape is wrong, tell me what you would do instead. I am also curious whether next-devtools-style projects would benefit from a supported boundary here, or if maintainers prefer a different integration model.

[SeifeddineJamei]

@foxted Next.js Dev-Extension API The Goal: Move from "private hacks" and forks to a standardized, plugin-based architecture for Next.js development tooling (Dev Indicators and Menus).

1. The Core Mechanism: dev-indicators.tsx
   A new root-level convention (similar to layout.tsx or middleware.ts) that serves as the entry point for development-only UI.

Location: Project root or /src.

Behavior: Default exports a component or array of components that hook into the Next.js Dev Overlay.

Isolation: This file is strictly excluded from production bundles, ensuring zero impact on end-user performance.

2. The API Surface (next/devtools)
   The proposal introduces a stable set of primitives to keep the UI consistent with the existing Next.js aesthetic:

: The top-level wrapper for a tool entry.

and : Sub-components for structured data (e.g., "API Health: 84ms").

3. Why This Wins (The "Galaxy Brain" Logic)
   Ecosystem Harmony: Instead of libraries like SWR, Prisma, or RSC Boundary each injecting their own floating "pills" or overlays (which clutter the screen), they can all "plug in" to the official Next.js dev menu.

Reduced Fragmentation: It eliminates the need for projects like next-devtools to maintain complex forks of Next.js internals just to add a UI layer.

Framework-Level Introspection: It allows for "Health Checks" and "RSC Introspection" to be shipped directly with packages, making the "Black Box" of Next.js more transparent during development.

💡 Key Technical Considerations (For the Badge)
To provide the most "insightful" answer, highlight these two open challenges mentioned in the proposal:

Execution Context: Should these indicators be standard React Client Components (allowing hooks/state) or static metadata? (The proposal leans toward components for flexibility).

Tree Shaking: Ensuring the next/devtools package is completely purged during next build is the highest priority for the Next.js core team.
If this solution helped you, please mark it as an approved answer to help others