Why does a Next.js Custom Server disable Automatic Static Optimization?

Question

I am having trouble understanding why in the docs it is stated that having a custom server disables Automatic Static Optimization.

Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like serverless functions and Automatic Static Optimization.

My understanding is that thanks to it, during the build phase (next build) it will automatically generate an HTML file (for pages that qualify) which will be then served in future requests.

What I have tried

• I have created a static page with no getServerSideProps or getInitialProps that should be pre-rendered in build phase thanks to Automatic Static Optimization.
• I have added a console.log() to the functional page component to know when the component is being rendered: i.e. if it renders on the server per request or only on the client.

The static page component code:

export default function Static() {
  console.log("The static page component is being rendered.")

  return <div>Hello from static page!</div>
}

• I have created a custom server that would let all requests be handled by nextjs handler

Custom server code:

const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  const server = express()

  server.all('*', (req, res) => {
    return handle(req, res)
  })
})

• Tested serving the app with both built-in server next start and my custom server mentioned above.

Results

After running next build, in both cases, a corresponding HTML file was generated for the Static page. When accessing the static page route, in both cases the logged message only appeared in the browser's console and not in node's console. When requesting the static route via curl and analysing the response, I could see <div>Hello from static page!</div> present. From that I have inferred that it is actually serving the pre-rendered HTML and thus using the Automatic Static Optimization.

Questions

1. The docs stated that custom server would disable Automatic Static Optimization, which by my understanding runs during the build step next build, how is it possible that in my testing it worked: generated the HTML file and served it for all requests to that static page route?

2. If a custom server really disables Automatic Static Optimization, what is preventing nextjs handler in the custom server from using already generated files from the next build step and serving them just as the built-in server would?

3. Have I misunderstood what the Automatic Static Optimization is really doing? Or something else?

Thanks!

Answer 1

You're correct, static automatic optimization does work with custom server when you let nextjs handle the requests. The warning probably refers to when you're actually using the custom server to handle page requests, instead of just passing them to nextjs.

Here's a quote from co-author of next.js:

Overall we recommend not adding a custom server, not to make you use Vercel but to make sure we can optimize the whole stack end to end. Automatic static optimization is always there, but if you're using a custom server there's some downsides like you can't remap routes which can lead to bugs in your application, hence why we don't recommend it.