Kick off the readme

Author: sdras

README.md

@@ -0,0 +1,221 @@
+![Next.js on Netlify Build Plugin](nextonnetlify.png)
+
+<p align="center">
+  <a aria-label="npm version" href="https://www.npmjs.com/package/next-on-netlify">
+    <img alt="" src="https://img.shields.io/npm/v/next-on-netlify">
+  </a>
+  <a aria-label="MIT License" href="https://img.shields.io/npm/l/next-on-netlify">
+    <img alt="" src="https://img.shields.io/npm/l/next-on-netlify">
+  </a>
+  <a aria-label="npm downloads" href="https://www.npmjs.com/package/next-on-netlify">
+    <img alt="" src="https://img.shields.io/npm/dt/next-on-netlify">
+  </a>
+  <a aria-label="Tested with Cypress" href="https://www.cypress.io/">
+    <img alt="" src="https://img.shields.io/badge/tested%20with-Cypress-04C38E.svg">
+  </a>
+</p>
+
+
+`next-on-netlify` is a utility for enabling server-side rendering in Next.js on Netlify. It wraps your application in a tiny compatibility layer, so that pages can use Netlify Functions to be server-side rendered.
+
+**TL;DR: You can enable SSR in your Next.js applications with 3 simple steps, listed [here](#setup)!**
+
+- Demo: https://next-on.netlify.com/
+- Example repository: https://github.com/netlify-labs/next-on-netlify-demo
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+  - [1. Set Next.js target to serverless](#1-set-nextjs-target-to-serverless)
+  - [2. Add postbuild hook](#2-add-postbuild-hook)
+  - [3. Configure Netlify](#3-configure-netlify)
+- [Optional Extras](#optional-extras)
+  - [Preview Locally](#preview-locally)
+  - [Custom Netlify Redirects](#custom-netlify-redirects)
+  - [Custom Netlify Functions](#custom-netlify-functions)
+- [Caveats](#caveats)
+  - [Preview Mode](#preview-mode)
+  - [Fallbacks for Pages with `getStaticPaths`](#fallbacks-for-pages-with-getstaticpaths)
+- [Credits](#credits)
+- [Showcase](#showcase)
+
+
+## Installation
+
+```
+npm install --save next-on-netlify
+```
+
+## Setup
+
+#### 1. Set Next.js target to serverless
+
+We must build our Next.js app as a serverless app. You can read more about serverless Next.js [here](https://nextjs.org/docs/api-reference/next.config.js/build-target#serverless-target).
+
+It's super simple. Just create a `next.config.js` file and write the following:
+
+```js
+// next.config.js
+
+module.exports = {
+  // Target must be serverless
+  target: "serverless",
+};
+```
+
+If binaries are needed in the deployment the following configuration is needed ([Prisma](https://github.com/prisma/prisma) is an example):
+
+```js
+// next.config.js
+
+module.exports = {
+  // Target must be experimental-serverless-trace
+  // Your build time will be longer with this option
+  target: "experimental-serverless-trace",
+};
+```
+
+#### 2. Add postbuild hook
+
+The next-on-netlify package adds the `next-on-netlify` command. When we run this command, some magic happens to prepare our Next.js app for hosting on Netlify\*.
+
+We want the next-on-netlify command to run after we build our NextJS application. So let's add a postbuild hook to our package.json file:
+
+```json
+{
+  "name": "my-nextjs-app",
+  "scripts": {
+    "dev": "next",
+    "build": "next build",
+    "postbuild": "next-on-netlify"
+  },
+  ....
+}
+```
+
+\*If you're curious about the "magic", check out the well-documented [`next-on-netlify.js` file](https://github.com/netlify/next-on-netlify/blob/master/next-on-netlify.js).
+
+#### 3. Configure Netlify
+
+We're almost done! We just have to tell Netlify how to build our Next.js app, where the functions folder is located, and which folder to upload to its CDN. We do that with a `netlify.toml` file and the following instructions:
+
+```toml
+[build]
+  command   = "npm run build"
+  functions = "out_functions"
+  publish   = "out_publish"
+```
+
+We're done. Let's deploy 🚀🚀🚀
+
+## Optional Extras
+
+#### Preview Locally
+
+I recommend you still use `next dev` to build and preview your application locally.
+
+But if you want to emulate the Netlify deployment on your computer, you can also run `next-on-netlify` locally and then use `netlify-cli` to preview the result.
+
+First, install the latest version of `netlify-cli` (you can also [look at package.json](https://github.com/netlify/next-on-netlify/blob/master/package.json) to see the version that next-on-netlify has been tested against):
+
+```bash
+npm install -g netlify-cli
+```
+
+Then, add the following `[dev]` block to your `netlify.toml`:
+
+```toml
+# netlify.toml
+
+# [build]
+#   ...
+
+[dev]
+  functions = "out_functions"
+  publish   = "out_publish"
+  # We manually set the framework to static, otherwise Netlify automatically
+  # detects Next.js and redirects do not work.
+  # Read more: https://github.com/netlify/cli/blob/master/docs/netlify-dev.md#project-detection
+  framework = "#static"
+```
+
+Lastly, add the following lines to your `.gitignore`:
+
+```shell
+# .gitignore
+
+# Files generated by next-on-netlify command
+/out_publish/
+/out_functions/
+```
+
+Now you're all set.
+
+From now on, whenever you want to preview your application locally, just run:
+
+1. `npm run build`: This will run `next build` to build your Next.js app and `next-on-netlify` to prepare your Next.js app for compatibility with Netlify
+1. `netlify dev`: This will emulate Netlify on your computer and let you preview your app on `http://localhost:8888`.
+
+#### Custom Netlify Redirects
+
+You can define custom redirects in a `_redirects` and/or in your `netlify.toml` file.
+The precedence of these rules are:
+
+- `_redirects`
+- `next-on-netlify` redirects
+- `netlify.toml`
+
+[Read more about Netlify redirects here](https://docs.netlify.com/routing/redirects/).
+
+#### Custom Netlify Functions
+
+`next-on-netlify` creates one Netlify Function for each of your
+SSR pages and API endpoints. It is currently not possible to create custom Netlify Functions. Let me know if you have a need for this feature and we can add it.
+
+## Caveats
+
+### Preview Mode
+
+[Next.js Preview Mode](https://nextjs.org/docs/advanced-features/preview-mode) does not work on pages that are pre-rendered (pages with `getStaticProps`). Netlify currently does not support cookie-based redirects, which are needed for supporting preview mode on pre-rendered pages. Preview mode works correctly on any server-side-rendered pages (pages with `getInitialProps` or `getServerSideProps`). See: [Issue #10](https://github.com/netlify/next-on-netlify/issues/10)
+
+### Fallbacks for Pages with `getStaticPaths`
+
+[Fallback pages](https://nextjs.org/docs/basic-features/data-fetching#fallback-true) behave differently with `next-on-netlify` than they do with Next.js. On Next.js, when navigating to a path that is not defined in `getStaticPaths`, it first displays the fallback page. Next.js then generates the HTML in the background and caches it for future requests.
+
+With `next-on-netlify`, when navigating to a path that is not defined in `getStaticPaths`, it server-side renders the page and sends it directly to the user. The user never sees the fallback page. The page is not cached for future requests.
+
+For more on this, see: [Issue #7](https://github.com/netlify/next-on-netlify/issues/7#issuecomment-636883539)
+
+
+## Credits
+
+This package is maintained by [Lindsay Levine](https://github.com/lindsaylevine), [Finn Woelm](https://github.com/FinnWoelm), and [Cassidy Williams](https://github.com/cassidoo).
+
+📣 Shoutout to [@mottox2](https://github.com/mottox2) (a pioneer of hosting Next.js on Netlify) and [@danielcondemarin](https://github.com/danielcondemarin) (author of serverless-next.js for AWS). The two were big inspirations for this package.
+
+🙌 Big "thank you" to the following people for their contributions, support, and beta testing:
+
+- [@spencewood](https://github.com/spencewood)
+- [@alxhghs](https://github.com/alxhghs)
+- [@gamliela](https://github.com/gamliela)
+- [@wei](https://github.com/wei)
+- [@laugharn](https://github.com/laugharn)
+- [@rajington](https://github.com/rajington)
+- [@etrepum](https://github.com/etrepum)
+- [@jonasbuntinx](https://github.com/jonasbuntinx)
+- [@joostmeijles](https://github.com/joostmeijles)
+
+
+## Showcase
+
+The following sites are built with `next-on-netlify`:
+
+![opinionatedreact.com](https://raw.githubusercontent.com/netlify/next-on-netlify/master/assets/showcase-opinionatedreact.png)  
+[opinionatedreact.com](https://opinionatedreact.com/) ([via Twitter](https://twitter.com/NikkitaFTW/status/1302667952920162309))
+
+![missionbit.org](https://raw.githubusercontent.com/netlify/next-on-netlify/master/assets/showcase-missionbit.png)  
+[missionbit.org](https://www.missionbit.org/) ([#18](https://github.com/netlify/next-on-netlify/pull/18#issuecomment-643828966))
+
+Are you building something awesome with `next-on-netlify`? 🔥 Let us know and we will feature it here :)
+