Instrumentation.ts runs server-side and client-side

[crummy]

Summary

I need to run some code server-side on app launch to do some initialization. I discovered the instrumentation feature which seemed to cover my use case.

However, when I try to run code that access node.js libraries like os, I get an error:

 X ./instrumentation.ts:1:0
Module not found: Can't resolve 'os'
> 1 | import os from 'os';
  2 | 
  3 | export async function register() {
  4 |   console.log('i am running server side. ' + os.hostname);

My instrumentation.ts looks like this:

import os from 'os';

export async function register() {
  console.log('i am running server side. ' + os.hostname);
}

Am I correct in saying that instrumentation.ts runs server-side so it should be able to access node.js libraries? If not, is there another way to run some initialization code on server launch?

Additional information

No response

Example

https://stackblitz.com/edit/stackblitz-starters-4t86qn?description=The%20React%20framework%20for%20production&file=next.config.js,instrumentation.ts&title=Next.js%20Starter

[crummy]

I have resolved my issue (thanks to StackOverflow) but got very confused along the way. This code works fine:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("os")
  }
}

However, this code does not.

export async function register() {
  const isServer = process.env.NEXT_RUNTIME === "nodejs"
  if (isServer) {
    await import("os")
  }
}

Why????

[crummy]

I have another StackOverflow question up in an attempt to get an answer to "why": https://stackoverflow.com/questions/77427874/next-js-instrumentation-behaves-differently-with-conditional-extracted-to-variab

[anaisbetts]

I'm also extremely Confused by this, the documentation for Instrumentation says that it is initialized once per Next.js server initialization - this seems to very much imply that it runs server-side. I don't know what use this can possibly be if it runs client side?

[crummy]

The code I linked in my comment above will allow you to run server-side specific code. Agreed that the documentation is either wrong or confusing.

[karlhorky]

Wonder if it's also running on the Edge Runtime (eg. Node.js APIs won't work), like the limitations Middleware currently has:

• Switchable Runtime for Middleware (Allow Node.js APIs in Middleware) #46722

[anaisbetts]

Not sure - the error you get is identical to when you use node.js in a React client-side component. This makes sense if instrumentation is intended to be global, it just means that the "Initialize your server-side things" use-case needs to be fulfilled by something other than This

[crummy]

The first code example in the marked answer works fine to import server-side things and run server-side only code.

[teddis]

@crummy Thank you, bruh! You saved me hours!
This helps explain it, but I still don't understand why instrumentation would be executed in both runtimes.

[JulianKingman]

There are actually good reasons to have client-side instrumentation, but it seems we're caught in between, with instrumentation that only runs on the server but acts like it runs on the client