diff --git a/packages/next/README.md b/packages/next/README.md index 36f82870..d94d5a4e 100644 --- a/packages/next/README.md +++ b/packages/next/README.md @@ -1593,23 +1593,26 @@ Note: we recommend putting `.next`, or your [custom dist folder](https://github.
Examples
-Serverless deployment dramatically improves reliability and scalability by splitting your application into many entrypoints. In case of Next.js an entrypoint is a page in the `pages` directory. +Serverless deployment dramatically improves reliability and scalability by splitting your application into smaller parts (also called [**lambdas**](https://zeit.co/docs/v2/deployments/concepts/lambdas/)). In the case of Next.js, each page in the `pages` directory becomes a serverless lambda. -To enable building serverless functions you have to enable the `serverless` build `target` in `next.config.js`: +There are [a number of benefits](https://zeit.co/blog/serverless-express-js-lambdas-with-now-2#benefits-of-serverless-express) to serverless. The referenced link talks about some of them in the context of Express, but the principles apply universally: serverless allows for distributed points of failure, infinite scalability, and is incredibly affordable with a "pay for what you use" model. + +To enable **serverless mode** in Next.js, add the `serverless` build `target` in `next.config.js`: ```js // next.config.js module.exports = { - target: 'serverless' -} + target: "serverless", +}; ``` -The serverless target will output a single file per page, this file is completely standalone and doesn't require any dependencies to run: +The `serverless` target will output a single lambda per page. This file is completely standalone and doesn't require any dependencies to run: - `pages/index.js` => `.next/serverless/pages/index.js` - `pages/about.js` => `.next/serverless/pages/about.js` @@ -1622,27 +1625,29 @@ export function render(req: http.IncomingMessage, res: http.ServerResponse) => v - [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) - [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) -- `void` refers to the function not having a return value. Calling the function will finish the request. +- `void` refers to the function not having a return value and is equivalent to JavaScript's `undefined`. Calling the function will finish the request. -Next.js provides low-level APIs for Serverless as hosting platforms have different function signatures. In general you will want to wrap the output of a Next.js Serverless build with a compatability layer. +#### One Level Lower + +Next.js provides low-level APIs for serverless deployments as hosting platforms have different function signatures. In general you will want to wrap the output of a Next.js serverless build with a compatability layer. For example if the platform supports the Node.js [`http.Server`](https://nodejs.org/api/http.html#http_class_http_server) class: ```js -const http = require('http') -const page = require('./.next/serverless/about.js') -const server = new http.Server((req, res) => page.render(req, res)) -server.listen(3000, () => console.log('Listening on http://localhost:3000')) +const http = require("http"); +const page = require("./.next/serverless/about.js"); +const server = new http.Server((req, res) => page.render(req, res)); +server.listen(3000, () => console.log("Listening on http://localhost:3000")); ``` For specific platform examples see [the examples section above](#serverless-deployment). -To summarize: +#### Summary -- Low-level API for implementing Serverless deployment -- Every page in the `pages` directory becomes a serverless function -- Creates the smallest possible Serverless function (50Kb base zip size) -- Optimized for fast cold start of the function +- Low-level API for implementing serverless deployment +- Every page in the `pages` directory becomes a serverless function (lambda) +- Creates the smallest possible serverless function (50Kb base zip size) +- Optimized for fast [cold start](https://zeit.co/blog/serverless-ssr#cold-start) of the function - The serverless function has 0 dependencies (they are included in the function bundle) - Uses the [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) and [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) from Node.js - opt-in using `target: 'serverless'` in `next.config.js`