Add documentation about asset generation

[timneutkens]

We currently don't have documentation about what the Next.js build output looks like from an architectural standpoint, this might be useful to add sometime. (it's not a public API that people should use)

_DX-2429

[Gaelan]

This would be especially useful for those of us building compatibility layers to run Next on non-Vercel cloud platforms. Currently, doing this takes a lot of reverse engineering either Next itself or other people's compatibility layers, which isn't exactly fun.

(Yes, I know, you'd like us to run it on Vercel. Vercel is a fantastic platform and I'd generally love to do this, but sometimes this isn't possible. For example, my current employer runs everything on AWS, and trying to get them to use Vercel for this one project would be a pretty hard sell.)

[timneutkens]

If you're not hosting on Vercel you don't have to know about the asset structure as well, as said in the initial message it's not a public API to be used. If you're hosting somewhere else you can use next build and then next start and Next.js will handle assets correctly including setting Cache-Control that automatically integrates with CDNs and such. next start supports all Next.js features.

[Gaelan]

The "not-Vercel" in this case is AWS Lambda, so it's not that simple unfortunately.

[Gaelan]

By the way, for better or worse, I'm not the first one to depend on next bulid's output--both next-on-netlify and serverless-next.js do as well.

[timneutkens]

next-on-netlify is unoffical and does not correctly support Next.js features as documented so I personally wouldn't recommend it as it's unreliable comparing to next start. serverless-next.js is a community project that implements some of Next.js' features but not all as of right now (you can check their docs).

The reason we recommend next start is that it allows us to greatly optimize your end user experience whereas if you roll your own thing it's going to miss a lot of optimizations, e.g. gzip and soon brotli is often forgotten, setting the correct cache-control for static assets, setting the correct cache control for data requests and more. Even features are incomplete if you end up not using next start, for example preview mode, incremental static generation, incremental static regeneration and more.

We're working on converging the target option back into just a single target that can then be hosted anywhere btw. So there won't be a distinction between serverless/server in the Next.js core soon which massively reduced error surface.

[humphd]

I was about to file a new issue, but perhaps this is the correct place to add this.

I have some next sites I need to export and host statically, and I would love some official guidance on how to set cache-control for the various things in the build output. When I worked with Gatsby I used their recommendations. It would be great if https://nextjs.org/docs/advanced-features/static-html-export or another doc provided a run down on how to set your cache headers when you can't use next start and have it do it for you.

A discussion of what gets built, and how to cache these, would be welcome.

[manovotny]

Also should document what is discussed in #40217.

• output: "standalone" in next.config.js
• Differences between dev and build output and how some of the files that are in there are related or unused in the production version.