Docs: Update `with-docker` example to not use standalone server or update documentation

[Luk-z]

What is the documentation issue?

Why with-docker example use standalone server but the docs say the opposite?

• https://nextjs.org/docs/app/guides/self-hosting -> no reference to standalone
• https://nextjs.org/docs/app/getting-started/deploying#docker -> no reference to standalone but there are links to with-docker example using standalone
• standalone is discouraged -> it should only be used when the integrated router of Next.js can't meet your app requirements

If this is not an error maybe you could write a minimal docs on why it is used with Dockerfile.

Is there any context that might help us understand?

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/getting-started/deploying#docker

[icyJoseph]

I think you are mixing standalone mode, with custom-server? Standalone is not necessarily a custom server, but an optimized build output, https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files - that as part of its build output generates a minimal server.js file to run in production. This is auto-generated by Next.js, not a custom server you write yourself.

Whereas a custom server is more about writing your own server.js/ts file, to couple with the next server starter.

The with-docker example use standalone mode, not a custom server.

I am reviewing this community PR though: #87069 so there'll be some upcoming changes

The self-hosting or Docker examples don't explicitly mention that mode, because it is an optimization rather. You can totally self-host without standalone mode or build in Docker.

[Luk-z]

@icyJoseph Sorry for mixing, you are right. I repost my concerns:

1. If the best way to self-hosting or Dockerize Next.js is using standalone why not mention it in the docs?
   My boss told me: "why we are using output: "standalone" if it is not present in the self-hosting/docker official documentation and neither in the with-docker example readme?".
   Maybe short explanation will be very useful.
2. "A custom server will remove important performance optimizations", does standalone server.js removes these "important performance optimizations"? is it optimize like 'next start' ?

[icyJoseph]

I'd say, there's a gap in the docs to cover:

• next start = works fine, full node_modules
• output: 'standalone' = same thing, smaller footprint (optional optimization)

I'll see what edits I can do.

Why are you using it? Because it outputs a smaller deployment size. Calling it the best is also not exactly the right framing, it is one more way to deploy. What standalone does is in the output document https://nextjs.org/docs/app/api-reference/config/next-config-js/output#automatically-copying-traced-files

The auto-generated server.js file is tailored to be equivalent to next start's runtime optimizations, AFAIK anyway

[Luk-z]

@icyJoseph sorry for come back. The output: export is only for spa, I think the need is for an SSR next start Docker example since it is the official way to deploy SSR applications.
Next.js support spa but is great for SSR so there must be a Docker example.

[Luk-z]

If you want my team can work on it because we wanna know if we can switch from standalone to next start. But if you have already a working example it would be very appreciated.

[icyJoseph]

@Luk-z I am not following? what are you talking about now? The with-docker example uses output: 'standalone', and #87069 contains both an output: 'standalone' update and a new output: 'export'. Do you mean a next start only Docker example?

Edit: The with-docker example already is an SSR Docker example the standalone mode doesn't change that. To use next start instead, remove output: 'standalone' from next.config.js, and in the Docker file, the copying from builder to runner step:

 COPY --from=builder /app/public ./public 
 COPY --from=builder /app/node_modules ./node_modules                                                                                                                   
 COPY --from=builder /app/.next ./.next                                                                                                                                 
 COPY --from=builder /app/package.json ./                                                                                                                               
 
ENV PORT=3000                                                                                                                                                          
ENV HOSTNAME="0.0.0.0"  
 
 CMD ["npm", "run", "start"]         

Why do you want to switch to next start exactly?

[Luk-z]

yes

[Luk-z]

@icyJoseph standalone strips node_modules binaries and we have a use case in which we need binaries.
Additionally we experience a bug with turbopack in standalone mode with last version of next -> #88844.

When you talk about standalone optimization, are you talking about only the "reduced deployment size"? or are there other optimizations?