Next.js Instrumentation: Code That Runs on Server Startup
Next.js's instrumentation.ts file runs code once when your server process starts, before any requests. It's ideal for setting up global logging, monitoring like OpenTelemetry, or database connections.
Why it exists
Modern applications need to perform setup tasks before they're ready to serve traffic. Things like connecting to a database or initializing a monitoring service shouldn't happen on the first user request, as that would add latency. Next.js needed a standard, predictable place for this one-time server initialization logic.
The mental model
Think of instrumentation.ts as the main function for your Next.js server process. It's a single entry point that executes once when the server boots up, and then it's done. It's not part of the request-response lifecycle; it happens before that lifecycle even begins.
How it works
You create a file named instrumentation.ts (or .js) in the root of your project or inside the src/ directory. Inside this file, you must export a function named register. Next.js will automatically detect this file, import it, and call the register function when the server process starts. This applies to next dev, next build, and next start. Note that you may need to opt-in via next.config.js.
When to use it
Use it for tasks that need to run once for the lifetime of the server. The canonical use case mentioned in the Next.js documentation is setting up OpenTelemetry for distributed tracing and metrics. Other good uses include initializing a database connection pool or connecting to external services that require a persistent, long-lived client.
When not to use it
Do not use this for any client-side logic; it never runs in the browser. Do not use it for logic that needs to run on every incoming request, like checking authentication headers—that's what Middleware is for. Avoid putting heavy, synchronous, blocking tasks here, as they will delay your server's startup time.
One canonical example
To set up a simple logger that announces server startup, you would create instrumentation.ts with the code: export function register() { console.log('Server instrumentation hook registered. The server is starting...'); }. A more realistic example involves initializing the OpenTelemetry SDK to automatically trace requests across your Next.js application.
Interview question
When does the `register` function within Next.js's `instrumentation.ts` file execute?
- a.After all server-side rendering for the initial page load is complete.
- b.On every incoming HTTP request to the Next.js server.
- c.Whenever a new client-side component is mounted in the browser.
- d.Once, when the Next.js server process initializes, prior to handling any client requests.Correct
Why? this is the answer
The `instrumentation.ts` file's `register` function executes only once when the Next.js server process starts, before any requests are handled, making it ideal for one-time global setup. It is explicitly stated not to run on every request (like middleware) or in the browser.
Just read this? Test yourself on what you have been reading.
Read the original → nextjs.org
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on nextjs — each one lists the topics its interview covers.
See open roles