add Middleware, NEXTAUTH_SECRET, Deployment sections

docs/configuration/options.md

@@ -18,9 +18,13 @@ If your Next.js application uses a custom base path, specify the route to the AP
 _e.g. `NEXTAUTH_URL=https://example.com/custom-route/api/auth`_
 
 :::note
-On [Vercel](https://vercel.com) deployments, we will read the `VERCEL_URL` environment variable, so you won't need to define `NEXTAUTH_URL`.
+**We automatically detect when you deploy to [Vercel](https://vercel.com)** so **you don't have to define this variable**.
 :::
 
+### NEXTAUTH_SECRET
+
+Used to encrypt the NextAuth.js JWT, and to hash [E-mail one-time](/adapters/models#verification-token) tokens. This is the default value for the [`secret`](/options#secret) option.
+
 ### NEXTAUTH_URL_INTERNAL
 
 If provided, server-side calls will use this instead of `NEXTAUTH_URL`. Useful in environments when the server doesn't have access to the canonical URL of your site. Defaults to `NEXTAUTH_URL`.
@@ -57,20 +61,22 @@ See the [providers documentation](/configuration/providers/oauth) for a list of
 
 A random string is used to hash tokens, sign/encrypt cookies and generate cryptographic keys.
 
-If not specified in development, it uses a hash for all configuration options, including OAuth Client ID / Secrets for entropy. Although if the user does not use such a provider, the configuration might be guessed.
+If you set [`NEXTAUTH_SECRET`](#nextauth_secret) as an environment variable, you don't have to define this option.
+
+If no value specified specified in development (and there is no `NEXTAUTH_SECRET` variable either), it uses a hash for all configuration options, including OAuth Client ID / Secrets for entropy.
 
-You can quickly create a valid secret on the command line via this `openssl` command.
+:::warning
+Not providing any `secret` or `NEXTAUTH_SECRET` will throw [an error](/errors#no_secret) in production.
+:::
+
+You can quickly create a good value on the command line via this `openssl` command.
 
 ```bash
 $ openssl rand -base64 32
 ```
 
-:::warning
-The default behaviour is volatile, and it is strongly recommended you explicitly specify a value. If `secret` is omitted in production, an error is thrown.
-:::
-
 :::tip
-If you rely on the default secret generation in development, you might notice JWT decryption errors, since the secret changes whenever you change your configuration. Defining a secret will make this problem go away.
+If you rely on the default secret generation in development, you might notice JWT decryption errors, since the secret changes whenever you change your configuration. Defining a secret will make this problem go away. We will likely make this option mandatory even in development in the future.
 :::
 
 ---
@@ -123,7 +129,7 @@ By default JSON Web Tokens are encrypted (JWE). We recommend you keep this behav
 
 ```js
 jwt: {
-  // A secret to use for key generation. Defaults to the top-level `secret`.
+  // A secret to use for JWT encryption. Use `NEXTAUTH_SECRET` environment variable instead.
   secret: 'INp8IvdIyeMcoGAgFGoA61DdBglwwSqnXJZkgz8PSnw',
   // The maximum age of the NextAuth.js issued JWT in seconds.
   // Defaults to `session.maxAge`.
@@ -154,23 +160,25 @@ You can use the built-in `getToken()` helper method to verify and decrypt the to
 ```js
 import { getToken } from "next-auth/jwt"
 
-const secret = process.env.JWT_SECRET
+const secret = process.env.NEXTAUTH_SECRET
 
-export default async (req, res) => {
+export default async function handler(req, res) {
+  // if using `NEXTAUTG_SECRET` env variable, we detect it, and you won't actually need to `secret`
+  // const token = await getToken({ req })
   const token = await getToken({ req, secret })
   console.log("JSON Web Token", token)
   res.end()
 }
 ```
 
-_For convenience, this helper function is also able to read and decode tokens passed in an HTTP Bearer header._
+_For convenience, this helper function is also able to read and decode tokens passed from the `Authorization: 'Bearer token'` HTTP header._
 
 **Required**
 
 The getToken() helper requires the following options:
 
 - `req` - (object) Request object
-- `secret` - (string) JWT Secret
+- `secret` - (string) JWT Secret. Use `NEXTAUTH_SECRET` instead.
 
 You must also pass _any options configured on the `jwt` option_ to the helper.
 
@@ -277,7 +285,7 @@ events: {
   async signIn(message) { /* on successful sign in */ },
   async signOut(message) { /* on signout */ },
   async createUser(message) { /* user created */ },
-  async updateUser(message) { /* user updated - e.g. their email was verified */ },
+  async updateUser(message) { /* user updated - e.g. their email was verified */ },
   async linkAccount(message) { /* account (e.g. Twitter) linked to a user */ },
   async session(message) { /* session is active */ },
   async error(message) { /* error in authentication flow */ }

docs/deployment.md

@@ -0,0 +1,20 @@
+# Deployment
+
+Deploying NextAuth.js only requires a few steps.
+
+# Vercel
+
+1. Expose [System Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables).
+2. Create `NEXTAUTH_SECRET` environment variable. The value should be something random, eg.: `openssl rand -base64 32` or https://generate-secret.vercel.app/32
+3. Add your provider's client ID and client secret to environment variables. *(Skip this step if not using an [OAuth Provider](/configuration/providers/oauth))*
+4. Deploy!
+
+## Securing a preview deployment
+
+Securing a preview deployment (with an OAuth provider) has some caveats, as most providers only allow a single redirect/callback URL, or you cannot set the value before publishing the site. Here are a few ways you can still use NextAuth.js to secure your Preview Deployments
+
+### Using the Credentials Provider
+
+...
+
+https://github.com/nextauthjs/docs/issues/19

docs/faq.md

@@ -108,7 +108,7 @@ Yes! Check out the [TypeScript docs](/getting-started/typescript)
 </summary>
 <p>
 
-Support for [Next.js Middleware](https://nextjs.org/docs/middleware) is under development, and there is a proof-of-concept for simple token validation/redirect. For more information or if you have feedback, visit the following issue https://github.com/nextauthjs/next-auth/issues/3037
+[Next.js Middleware](https://nextjs.org/docs/middleware) is supported. Head over to the [this page](/getting-started/next#middleware)
 
 </p>
 </details>

docs/getting-started/next.md

@@ -0,0 +1,39 @@
+# Next.js
+
+## Middleware
+
+You can use a Next.js Middleware with NextAuth.js to protect your site.
+
+Next.js 12 has introduced [Middleware](https://nextjs.org/docs/middleware). It is a way to run logic before accessing any page, even when they are static. On platforms like Vercel, the speed is guaranteed by executing Middleware at the [Edge](https://nextjs.org/docs/api-reference/edge-runtime)
+
+### API
+
+TODO:
+
+### Caveats
+
+- Currently only supports session verification, as as parts of the sign-in logic code need to run in a Node.js environment. In the future though, we would like to make sure that NextAuth.js can run fully at the [Edge](https://nextjs.org/docs/api-reference/edge-runtime)
+- Only supports the `"jwt"` [session strategy](/options#session). We need to wait until databases at the Edge become mature enough to ensure a fast experience. (If you know of an Edge-compatible database, we would like if you proposed a new [Adapter](http://localhost:3000/tutorials/creating-a-database-adapter))
+
+### Examples
+
+#### Authentication for entire site
+
+```js title="pages/_middleware.js"
+export { default } from "next-auth/middleware"
+```
+
+With this one line, when someone tries to load any of your pages, they will have to be logged-in first. Otherwise, they are redirected to your login page.
+
+#### Authorization for certain pages
+
+```js title="pages/admin/_middleware.js"
+import { withAuth } from "next-auth/middleware"
+
+export default withAuth({
+  authorized: ({ token }) => token?.role === "admin"
+})
+```
+
+With the above code, you just made sure that only user's with the `admin` role can access any of the pages under thge `/admin` route. (Including nested routes as well, like `/admin/settings` etc.).
+

docs/warnings.md

@@ -29,6 +29,10 @@ These warnings are displayed on the terminal.
 
 In development, we generate a `secret` based on your configuration for convenience. This is volatile and will throw an error in production. [Read more](https://next-auth.js.org/configuration/options#secret)
 
+#### TWITTER_OAUTH_2_BETA
+
+Twitter OAuth 2.0 is currently in beta as certain changes might still be necessary. This is not covered by semver. See the docs https://next-auth.js.org/providers/twitter#oauth-2
+
 ## Adapter
 
 ### ADAPTER_TYPEORM_UPDATING_ENTITIES

sidebars.js

@@ -11,6 +11,7 @@ module.exports = {
         "getting-started/rest-api",
         "getting-started/typescript",
         "getting-started/upgrade-v4",
+        "getting-started/next",
       ],
     },
     {
@@ -72,5 +73,6 @@ module.exports = {
     },
     "warnings",
     "errors",
+    "deployment",
   ],
 }