Canonical approach to instantiating singletons in NextJS

[dwjohnston]

Summary

I'm looking for advice regarding how one would instantiate a server-side singleton.

Where in something like an express.js application, we have a clear entry point for our application, an index.ts or server.ts and that's where we can instantiate/configure such service singletons - nextjs doesn't appear to have a clear entry point.

My scenario

In my specific scenario this singleton essentially behaves as an alternative to context provider, where I do something like this:

// some-rsc-component.tsx

import config from "@/the-config-singleton"; 



export async function SomeComponent() {
     const dataFetchingFunction = config.dataFn; 

     const data = await dataFetchingFucntion(); 

     return <>
         //... 
     </>
}

// src/app/layout.tsx? 
// src/instrumentation.ts? 

import config from "@/the-config-singleton"; 

config.dataFetchingFunction  = () => {
    //implementation here 
}

Other Scenarios

There are other scenarios that I've run across in the wild:

This discussion mentions instantiating database connections: #16271
Advice in the thread appear to be 'instantiate as and where you need it' , (could be problematic, surely), and otherwise people mentioning instantiating in layout.tsx

This in-progress MSW example PR shows instantiating the MSW behaviour in layout.tsx
https://github.com/mswjs/examples/pull/101/files#diff-8c12b389f7663528d803c57e6fe92f1635c6bbeafcf9d1b3d069d8b31fc88471R5-R12

Solutions

• Use the root level layout.tsx

This is the first solution I'd thought of too - it seems like the most obvious 'this is the first thing will render'. My experimenting with a local dev server does indicate that this module will only be evaluated once.

• Use instrumentation.ts?

The reason this file seems appropriate is the documentation says:

Then, export a register function in the file. This function will be called once when a new Next.js server instance is initiated.

Additional information

No response

Example

No response

[khuezy]

There's a lot of confusion regarding singletons in Nextjs since a lot has changed from Next 13 to the current version. Since 13+, all Nextjs context now runs in the same process (prior to 13, there were 2-3 jest workers handling different things like pages & app router, middleware, etc...)

But now that everything runs in the same process, globalThis will work across different chunks.
eg:

// singleton.ts

const instance = {
   db: new DBConnection()
}
export default instance

In nodejs, normally this would be a singleton since all modules will be cached. But with webpack, this will get bundled and duplicated across multiple chunks - so you'll end up having multiple instances of singleton.ts and breaking the singleton pattern.

To make sure the singleton still works, just wrap all single variables inside globalThis

// singleton.ts

globalThis.instance = globalThis.instance ||  { db: new DBConnection() }
export default globalThis.instance

You'll want to extend globalThis with some typings. But this should work now. The singleton.ts file will get bundled multiple times but the actual memory should be shared via globalThis.

Don't use layout.ts. instrumentation.ts is a good place to init your singletons though.