Documentation for target:serverless

[bezreyhan]

Describe the feature you'd like to request

I was not able to find any documentation for what is exported when a Next app is built using target: serverless. I also did not find documentation for the function signature of the render function that gets exported.

Background: I'm using the target: serverless option and was trying to see how to deploy my pages using AWS Lambda. I was not able to find any documentation about how to wrap the functions that exported by Next.

Describe the solution you'd like

I was able to use the following links to get the information I need, but it would be helpful if this was documented somewhere.

• Support AWS Lambda as target serverless #6173
• Add docs for Serverless target #6070 (comment)

Describe alternatives you've considered

It looks like it was once documented in the ReadMe but I did not see it there: #6070 (comment)

[lachlanjc]

Check out #20487: #20487 (comment)

[bezreyhan]

@lachlanjc thanks for the pointer. I missed that thread. It looks like that issue has been closed but I don't see why there can't be better documentation about how the serverless target can be used. If the serverless target is not recommended, then that could be document as well. The team I'm working on has been refactoring our app specifically so we can use the serverless target so it would be good to know what the drawbacks are of using it.

[timneutkens]

Closing based on my reply here: #20487 (comment)

The team I'm working on has been refactoring our app specifically so we can use the serverless target so it would be good to know what the drawbacks are of using it.

• Does not cover the full Next.js feature set (e.g. preview mode, revalidate etc)
• Significantly slower compilation (as all deps are bundled in the page bundles, there's better ways to handle it nowadays, especially with AWS lambdas)
• Lambas no longer have cold start problems related to zip size, only related to code loading, more code loaded takes longer to boot, Next.js next start by default only loads code needed for the incoming request.

Basically the serverless target only covers a small fraction of Next.js features and does not fully support the features introduced in the last year or so. Not because we didn't add support for them, they can work with the serverless target, but because a serverless function is only a code execution runtime, not a full application runtime that includes an enterprise-level CDN (that supports dynamic caching etc)

[bezreyhan]

@timneutkens thanks for the reply. Your points make sense. Though, I was hoping that information could be documented. It is fine if the serverless target does not support all of the Next features as long as developers are aware of what the tradeoffs are. In our case, we might not have spent all of the time that we did refactoring our app.

Despite the downsides of the serverless target, there will still be developers and teams who would prefer to package their app as individual functions and use their own CDN for delivering static assets. There are already people who are deploying their monolithic Next app on FaaS, so breaking their app into smaller functions would still be valuable.

To sum up, there should be documentation for:

• The drawbacks of using the serverless target
• The way you can use the serverless target if you choose to

With this information developers can make the decision that works best for them. Also, it will allow developers to contribute to Next in a way that will support their use case.

Finally, we really enjoy using Next so thanks for all of your work on this project.

[bezreyhan]

@timneutkens I wanted to follow up on this. Could we open this issue back up?

Since the serverless target is still going to be supported (and is currently the recommended target), it makes sense to document how it works, how to use it, and what the drawbacks are.

[brandonfriday]

I have to agree that some documentation is better than none on this, even if it's not a great option.
It was confusing for me as I'm trying to deploy a Next app with serverless framework and saw references to this target but not in Next docs.

[balazsorban44]

This issue has been automatically locked due to no recent activity. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.