Conditional Instrumentation: Environment-based Control for Next.js Instrumentation API #75273
Description
Discussed in #75129
Originally posted by JamesRobertWiseman January 21, 2025
Goals
- Enable developers to disable instrumentation in specific environments
- Reduce development overhead by skipping unnecessary instrumentation code
- Provide a clean, declarative way to manage environment-specific instrumentation 1
Non-Goals
- Modify existing instrumentation functionality in production environments
- Change how instrumentation works when enabled
- Add complexity to the current stable instrumentation API 2
Background
The instrumentation API was stabilized in Next.js 15, providing a way to execute code when a new Next.js server instance starts. Currently, developers need to implement manual environment checks within the instrumentation file.
Starting from Next.js's recommended code:
// instrumentation.js
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
await import('./instrumentation-node')
}
if (process.env.NEXT_RUNTIME === 'edge') {
await import('./instrumentation-edge')
}
}To disable instrumentation in development, developers must add additional environment checks:
// instrumentation.js
export async function register() {
if (process.env.NODE_ENV !== 'production') {
return;
}
if (process.env.NEXT_RUNTIME === 'nodejs') {
await import('./instrumentation-node')
}
if (process.env.NEXT_RUNTIME === 'edge') {
await import('./instrumentation-edge')
}
}This approach, while functional, leads to:
- Boilerplate code in instrumentation files
- Potential code bundling of unused imports in development
- Less maintainable and harder to understand instrumentation setup
- Repetitive environment checks across different instrumentation features
A more elegant solution is needed to handle environment-specific instrumentation.
Proposal
Implement either:
- Add
disableInstrumentationconfiguration option innext.config.jsthat accepts a boolean or function returning boolean:
// next.config.js
module.exports = {
disableInstrumentation: process.env.NODE_ENV !== 'production'
// or as a function
disableInstrumentation: (options) => {
return process.env.NODE_ENV !== 'production'
}
}- Introduce environment-specific file conventions:
instrumentation.prod.ts|js- Only runs in productioninstrumentation.dev.ts|js- Only runs in developmentinstrumentation.ts|js- Runs in all environments (maintaining backward compatibility)
I'm interested in contributing to the implementation of this feature. The preferred approach would be option 1, as it provides more flexibility and maintains the single file convention while allowing for simple environment control.