RFC: Custom _server.ts setup file

[alexandros-megas]

Background / Motivation

https://jake.tl/notes/2021-04-04-nextjs-preload-hack
#16600

Currently, if you want to insert some custom code either before or after the nextJS server starts up, you're faced with 2 options:

• Use a custom express server
• Use a "hack" to require a custom module before executing node_modules/.bin/next start

I, myself, am currently planning to add some datadog APM stuff to my set up, and this is why I'm interested in something like this. I can also imagine other use cases:

1. Do some basic validation tasks, and fail early and explicitly (for example, check if all expected environment variables are present).
2. Attach some process level monitors, like memory usage, garbage collection, etc.
3. Call some external system after my server is done starting up.

Idea

NextJS already has concepts like _app.tsx and _document.tsx for customizing the app and document respectively. Other abstractions also, exist, like 404.tsx and 500.tsx. In similar fashion, adding pages/_server.ts would be treated as a special file, whose default export is an async function that can be used to execute custom code before and after the nextJS server starts. In the example, I'm using typescript to show what kind of types I might expect from this feature's API.

Implementation 1: a single Koa-style async function

// pages/_server.ts

export default async function customServer(start: () => Promise<void>): Promise<void> {
  // do stuff before starting nextJS
  const [envValid, missingVars] = await checkEnvironment();
  if (!envValid) {
    console.error(`Some variables missing: ${missingVars}`);
    return;
  }
  await attachMonitoring();

  // start nextjs
  try {
    await start();
  } catch (e) {
    console.error(`Next JS failed to start up because ${e.message}`);
    await sendServerFailureToSlack(e);
    return;
  }

  // do post-next stuff
  await checkSomeMoreStuff();
  await sendServerSuccessToSlack();
}

Implementation 2: Multiple named exports

Another way this might be implemented is via named exports, but I think this makes it less flexible, particularly in the case where a post-server task depends on the result of a pre-server task. This might look something like this:

// pages/_server.ts

// do stuff before starting nextJS
export async function beforeServer(): Promise<void> {
  const [envValid, missingVars] = await checkEnvironment();
  if (!envValid) {
    console.error(`Some variables missing: ${missingVars}`);
    return;
  }
  await attachMonitoring();
}

// do post-next stuff
export async function afterServer(): Promise<void> {
  await checkSomeMoreStuff();
  await sendServerSuccessToSlack();
}

// do stuff if nextJS fails to start
export async function onError(err: Error): Promise<void> {
  console.error(`Next JS failed to start up because ${err.message}`);
  await sendServerFailureToSlack(err);
}

Other things

• What should happen when deploying to Vercel: Error? Warning? Ignore?
• I don't think any additional internals should be exposed. If, for example, you expose the router, it could lead to many anti-patterns, like attaching endpoints in a non-standard way, for example.

[mayteio]

+1 on this one! I'm unable to use node --require ./server-preload.js ./node_modules/.bin/next start with yarn plug'n'play. This would be great functionality to have.

[anthonyalayo]

I refresh this repository weekly in the hopes that this RFC gets noticed.

[dzcpy]

Yet no one in the dev team seem to care about it 😆

[gregg-cbs]

I need to setup database watchers on server start and im having a tough time finding a way to do it.

[mayteio]

I was able to run startup code with yarn pnp using node --require:

node -r ./server-preload.js $(yarn bin next) start

[Capricair]

Implementation 1

It seems more flexible
I have been waiting for this feature for a long time

[0n3byt3]

+100 Implementation 1
Hope it doesn't take long to implement...

[esemeniuc]

+100, this is sorely needed

[pr1ntr]

we really need this!

[galaxynova1999]

+100 really need

[webmandman]

I voted for this earlier, but just to make sure. I want to know if this RFC will provide a way for me to do what I want.

I would like to call cron.schedule() at server start, so that the cron jobs get scheduled when the application starts up. How would you do this currently? or this RFC the best desired way to do it?

[jtlapp]

I'd like this to do some configuration validation so I can spit out user-friendly errors and exit the process before the configuration becomes a problem or spits out unfriendly errors.

[cdaringe]

It's a nice proposal, but respectfully, I don't think it clearly articulates why the status-quo is not acceptable. Next.js offer prepareServer, which returns to you a middleware.

It's actually quite wonderful. do whatever you want, then load next.js. Next.js turns into a library, vs a top-level executable, which is exactly what you want, because you want to do custom stuff.

This proposal has the real con of putting next.js in front of all of the customization you may want to apply before it. For instance, I launch multiple next servers (middlewares, really), from my custom server implementation. This proposal would break that awesome capability.

What's being asked here IMHO is for a redundant API with less-capable utility. I think next.js team hit the sweet spot:

• want the default stuff? use next executable
• want custom stuff? use next as a library

just my 2c

[Capricair]

I think you forgot one thing

A custom server will remove important performance optimizations, like serverless functions and Automatic Static Optimization.

[leerob]

I just realized I haven't commented back here: we have a solution for this now!

https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation

// instrumentation.ts

import { init } from 'package-init'
 
export function register() {
  init()
}

Let me know if this solves your use case.

[Capricair]

It can be solved, but it is not as good as implementation 1

[alexandros-megas]

Thank you! Sorry for late response, but just now coming back to this RFC. This absolutely solves my use case (and I imagine the needs of others). There's a little less fine grained control compared to what I had imagined in my first "example" implementation, but I don't think that's necessarily a bad thing.

👍