Add docs for Serverless target

packages/next/README.md

@@ -1585,6 +1585,65 @@ Note: `NODE_ENV` is properly configured by the `next` subcommands, if absent, to
 
 Note: we recommend putting `.next`, or your [custom dist folder](https://github.com/zeit/next.js#custom-configuration), in `.gitignore` or `.npmignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy, excluding `.next` or your custom dist folder.
 
+### Serverless deployment
+
+<details>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/zeit/now-examples/tree/master/nextjs">Now.sh</a></li>
+  </ul>
+</details>
+
+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.
+
+To enable building serverless functions you have to enable the `serverless` build `target` in `next.config.js`:
+
+```js
+module.exports = {
+  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:
+
+- `pages/index.js` => `.next/serverless/pages/index.js`
+- `pages/about.js` => `.next/serverless/pages/about.js`
+
+The signature of the Next.js Serverless function is similar to the Node.js HTTP server callback:
+
+```ts
+export function render(req: http.IncomingMessage, res: http.ServerResponse) => void
+```
+
+- [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.
+
+Example usage with [`http.Server`](https://nodejs.org/api/http.html#http_class_http_server):
+
+```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'))
+```
+
+Next.js provides low-level APIs for serverless as platforms have different function signatures. These APIs allow the user to implement Next.js on any serverless platform.
+
+Generally, you will want to wrap the Next.js serverless build output to interoperate between your deployment platform and the Next.js serverless function.
+
+Examples of automatically created Serverless deployments:
+
+- [Now v2 with `@now/next` builder](https://github.com/zeit/now-examples/tree/master/nextjs)
+
+To summarize:
+
+- Every page becomes a serverless function
+- The serverless function has 0 dependencies (they're all inlined)
+- Uses the req and res coming from Node.js
+- opt-in using target: 'serverless' in next.config.js
+- Does not load next.config.js when executing the function, note that this means `publicRuntimeConfig` / `serverRuntimeConfig` are not supported.
+
 ## Browser support
 
 Next.js supports IE11 and all modern browsers out of the box using [`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html). In order to support IE11 Next.js adds a global `Promise` polyfill. In cases where your own code or any external NPM dependencies you are using requires features not supported by your target browsers you will need to implement polyfills.