Run code once per node server startup #15341

anyone have ideas on how to do this WITHOUT a custom server?

I solved this by using some kind of memo function to access the object that needs initialization within the server-side code - the initialization code will only run once, afterwards, the initialized object gets returned. This works, but is not as elegant as it could be. But it's still better than building a custom server. It also suffers from the fact that next.js' recompile on code changes does not offer the ability to reset the state of this code which quickly leads to unwanted behaviour. (this also applies to the situation where a custom server is used. This is a general problem) Which in turn makes me wonder whether next.js really is ready for applications that go beyond simple crud with their backend.

Even with fast-memo, the memoized function was getting called 7 times. I wonder if it had something to do with concurrency configured for the node instance which got spawned.

I worked around that by completely separating the data access layer from the route handlers and by making sure everything is properly initialized before any data access even occurs. But in retrospective, once again, I stumbled over the fact that next is a little too opinionated for the things my apps are doing.

I worked around that by completely separating the data access layer from the route handlers and by making sure everything is properly initialized before any data access even occurs

Yea, I did the same, but not being able to check the DB connection at startup without being forced to use a custom server just for that seems ridiculous... That forces to perform a request to check if the server is properly configured, which is a pain for CIs or even for deployment.

Hi there, I've did a simple console.log in the file and it only runs on build, but when I run dev or start it never outputted anything to the console

For resources that need to be initiated in a single API route, you can use the fact that code outside of the API function export will run one time when the file is imported, so you can initialize resources there, for example:

// pages/api/hello.js

// Code you place here will run only once

export default (req, res) => {
  // Code you place here runs on every request
  // ...
}

I ran into massive problems with singleton usage when using development mode (next dev) because native resouces (e.g. db connections, open files) were not properly being destroyed on reloading after code changes. In production, this works and is exactly what we did, too.

The problem with this is that for a task that needs to wait (something that returns a promise), the request might proceed before the promise resolves. So If I wanted to do some database initialization before continuing the request, it would mostly fail in this case.

This isn't a solution, either. A bunch of hacks that work around next.js don't solve the original Problem that next.js should be able to provide a proper solution in the first place.

The only solution I found that really works consistently by now is providing the actual backend not via next.js, but in a separate nodejs microservice. Not what we intended to do originally, but at least that doesn't break anything in dev.

This would be so nice

Would love to have something like this. Or something like _hooks.js that would attach exported startup, shutdown, etc listener functions to the corresponding events.

After trying several "hacky" solution, this is the best ever.
I used it for DB connection:

module.exports = async (phase) => {
  console.log("Starting at phase:", phase);
  if(['phase-production-server', 'phase-development-server'].includes(phase))
    await dbConnect();
  return withSentryConfig(nextConfig, sentryWebpackPluginOptions);
};

This doesn't work if you are trying to import a typescript singleton though, since next.config.js is not parsed by typescript, unless I am missing something. I wasn't able to get this to work with typescript, which is a dealbreaker for me.

I also wasn't able to get this working with typescript.

Would this get executed in the browser as well? I'm worried it might bundle server-specific code into the frontend bundle and/or leak secrets in env vars 🤔

Yeah, it would. It is often the case people attach router event listeners here as well, and of course those end up in the client.

Though, I guess, unless you prefix the env vars with NEXT_PUBLIC_, they won't really leak, but it creates a bit of a mess.

Router.events.on("routeChangeStart", () => NProgress.start());
Router.events.on("routeChangeComplete", () => NProgress.done());
Router.events.on("routeChangeError", () => NProgress.done());

function App({ Component, pageProps }: AppProps) {
// rest of app

You can use the https://next-code-elimination.vercel.app/ for other cases, it is a great visual helper.

There is also the issue that getServerSideProps and api routes does not get the same instance of singleton service.

Switched to custom server with express instead.

import express, { NextFunction, Request, Response } from "express";
import nextjs from "next";
import { getSubdomain } from "../shared/utils/http";
import apiSessionService from "./services/apiSessionService";
import fs from "fs";
import https from "https";

const dev = process.env.NODE_ENV !== "production";
const nextjsApp = nextjs({ dev });
const handle = nextjsApp.getRequestHandler();
const port = process.env.PORT || 3443;
const key = fs.readFileSync("./ssl/self-signed-cert.key");
const cert = fs.readFileSync("./ssl/self-signed-cert.pem");

(async () => {
    try {
        await nextjsApp.prepare();
        const app = express();
        const server = https.createServer({ key, cert }, app);
        app.all("*", async (req: Request, res: Response, next: NextFunction) => {
            try {
                console.log("> express request:", req.url);
                const session = await apiSessionService(app).keepAlive(
                    getSubdomain(req.headers.host)
                );
                res.locals.session = session;
                return handle(req, res);
            } catch (err: any) {
                next(err);
            }
        });
        server.listen(port, (err?: any) => {
            if (err) throw err;
            console.log(`🚀 Ready on localhost:${port} - env ${process.env.NODE_ENV}`);
        });
    } catch (e) {
        console.error(e);
        process.exit(1);
    }
})();

On 12.2.2 this doesn't work for me, it only get's called on the first request, not when the server starts. Make sure you don't have any browser windows open that auto refresh and make requests when the server starts up to confirm.

I bit the bullet and created a good ol' simple express server

As a workaround you can use a similar singleton pattern
https://github.com/trpc/examples-next-prisma-starter/blob/adc29973aff893633d65e5d34efd7fb0bb8e6a9e/src/server/prisma.ts

https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices#solution

I'd strongly suggest using @icyJoseph 's approach: #15341 (comment)
From Next.js' official documentation, the next.config.js exposes each server stage under the phase parameter.
You can then use conditionals to run your initialization code during your preferred phase

I've been successfully using said approach in production.

Thank you! That works. I used a custom server before, but it created several inconveniences. Your suggestion seems to be the most convenient solution right now.

Did NextJS 13 solve this? I see there is something called "Server Components" now but not sure if this exact situation of running code once on the server is available on NextJS 13.

Nope, that's something else.

What do you recommend? I need to initialize a node module once on server startup and have the object available on clients.

You can use the solution posted above. Or you could also use a separate backend. However, this will increase latency and worsen maintainability. You could also go for a custom server as described in their docs. I personally wouldn't do that. Really depends on what you're looking for.

The solution above isn't ideal, but works fine. I personally will look for an alternative to nextjs in the future that better fits my needs.

Thank you! I'm going to look into this solution. Main thing is being able to import the node module to initiate it.

Yes, this is a very basic feature that any web framework would have. Especially now Next.js is more and more used as a "full stack framework" as tRPC (create-t3-app) and Blitz.js are getting populer