docs: update middleware.ts references to proxy.ts for Next.js 16 #13373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

F-47 wants to merge 1 commit into nextauthjs:main from F-47:docs/update-middleware-to-proxy

docs/pages/concepts/index.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -57,9 +57,9 @@ Yes! Check out the [TypeScript docs](/getting-started/typescript)
  
    </Accordion>

    <Accordion title="Is Auth.js compatible with Next.js 12 Middleware?">

    <Accordion title="Is Auth.js compatible with Next.js Proxy / Middleware?">

    [Next.js middleware](https://nextjs.org/docs/middleware) is supported and is recommended as of version 5. An example middleware setup can be found [here](/getting-started/session-management/protecting#nextjs-middleware).

    Yes! As of Next.js 16, `middleware.ts` has been renamed to `proxy.ts`. Auth.js supports both the new `proxy.ts` convention and the legacy `middleware.ts`. An example setup can be found [here](/getting-started/session-management/protecting#nextjs-proxy).

    </Accordion>

    </Accordions>

docs/pages/getting-started/adapters/prisma.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -65,9 +65,11 @@ if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma
  
    </Callout>

    <Callout type="warning">

      We recommend using version `@prisma/client@5.12.0` or above if using

      middleware or any other edge runtime(s). See [edge

      compatibility](#edge-compatibility) below for more information.

      We recommend using version `@prisma/client@5.12.0` or above if using proxy (or

      middleware in older Next.js versions) or any other edge runtime(s). In Next.js

      16+, `proxy.ts` runs on the Node.js runtime, so this may no longer be

      necessary. See [edge compatibility](#edge-compatibility) below for more

      information.

    </Callout>

    <Code>

    @@ -152,9 +154,9 @@ At the moment, Prisma is still working on being fully compatible with edge runti
  
    - Use the Prisma's [Accelerate](https://pris.ly/d/accelerate) feature

    - Follow our [Edge Compatibility](/guides/edge-compatibility) page as the workaround. This uses the `jwt` session strategy and separates the `auth.ts` configuration into two files.

    Using Prisma with the `jwt` session strategy and `@prisma/client@5.9.1` or above doesn't require any additional modifications, other than ensuring you don't do any database queries in your middleware.

    Using Prisma with the `jwt` session strategy and `@prisma/client@5.9.1` or above doesn't require any additional modifications, other than ensuring you don't do any database queries in your proxy (or middleware in older Next.js versions).

    Since `@prisma/client@5.9.1`, Prisma no longer throws about being incompatible with the edge runtime at instantiation, but at query time. Therefore, it is possible to import it in files being used in your middleware as long as you do not execute any queries in your middleware.

    Since `@prisma/client@5.9.1`, Prisma no longer throws about being incompatible with the edge runtime at instantiation, but at query time. Therefore, it is possible to import it in files being used in your proxy as long as you do not execute any queries in your proxy.

    ### Schema

docs/pages/getting-started/installation.mdx

-Original file line number
+Diff line change
@@ Expand Up @@
     export const { GET, POST } = handlers
     ```
-. Add optional Middleware to keep the session alive, this will update the session expiry every time its called.
+. Add optional Proxy to keep the session alive, this will update the session expiry every time its called.
-    ```ts filename="./middleware.ts"
-    export { auth as middleware } from "@/auth"
+    <Callout type="info">
+      As of Next.js 16, `middleware.ts` has been renamed to `proxy.ts`. If you are
+      using an older version of Next.js, use `middleware.ts` with `export { auth as middleware }` instead.
+    </Callout>
+    ```ts filename="./proxy.ts"
+    export { auth as proxy } from "@/auth"
     ```
       </Code.Next>
@@ Expand Down @@

docs/pages/getting-started/migrating-to-v5.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -42,7 +42,7 @@ npm install next-auth@beta
  
    - OAuth 1.0 support is deprecated.

    - The minimum required Next.js version is now [14.0](https://nextjs.org/14).

    - The import `next-auth/next` is replaced. See [Authenticating server-side](#authenticating-server-side) for more details.

    - The import `next-auth/middleware` is replaced. See [Authenticating server-side](#authenticating-server-side) for more details.

    - The import `next-auth/middleware` is replaced. See [Authenticating server-side](#authenticating-server-side) for more details. As of Next.js 16, `middleware.ts` has been renamed to `proxy.ts`.

    - When the `idToken: boolean` option is set to `false`, it won't entirely disable the ID token. Instead, it signals `next-auth` to also visit the `userinfo_endpoint` for the final user data. Previously, `idToken: false` opted out to check the `id_token` validity at all.

    ## Migration

    @@ -92,7 +92,7 @@ See the table below for a summary of the changes. Below that are `diff` examples
  
    | Where                   | v4                                                    | v5                               |

    | ----------------------- | ----------------------------------------------------- | -------------------------------- |

    | **Server Component**    | `getServerSession(authOptions)`                       | `auth()` call                    |

    | **Middleware**          | `withAuth(middleware, subset of authOptions)` wrapper | `auth` export / `auth()` wrapper |

    | **Proxy (Middleware)**  | `withAuth(middleware, subset of authOptions)` wrapper | `auth` export / `auth()` wrapper |

    | **Client Component**    | `useSession()` hook                                   | `useSession()` hook              |

    | **Route Handler**       | _Previously not supported_                            | `auth()` wrapper                 |

    | **API Route (Edge)**    | _Previously not supported_                            | `auth()` wrapper                 |

    @@ -145,27 +145,27 @@ const ClientComponent = () => {
  
    </Tabs.Tab>

    <Tabs.Tab>

    ```diff filename="middleware.ts"

    ```diff filename="proxy.ts (middleware.ts in Next.js < 16)"

    - export { default } from "next-auth/middleware"

    + export { auth as middleware } from "@/auth"

    + export { auth as proxy } from "@/auth"

    ```

    For advanced use cases, you can use `auth` as a wrapper for your Middleware:

    For advanced use cases, you can use `auth` as a wrapper for your Proxy:

    ```ts filename="middleware.ts"

    ```ts filename="proxy.ts"

    import { auth } from "@/auth"

    export default auth((req) => {

    export const proxy = auth((req) => {

      // req.auth

    })

    // Optionally, don't invoke Middleware on some paths

    // Optionally, don't invoke Proxy on some paths

    export const config = {

      matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],

    }

    ```

    Check out additional [Middleware docs](/getting-started/session-management/protecting#nextjs-middleware) for more details.

    Check out additional [Proxy docs](/getting-started/session-management/protecting#nextjs-proxy) for more details.

    </Tabs.Tab>

    <Tabs.Tab>

    @@ -258,7 +258,7 @@ While Auth.js strictly uses standard [Web APIs](https://developer.mozilla.org/en
  
    Auth.js supports two [session strategies](/concepts/session-strategies). When you are using an adapter, it will default to the `database` strategy. **Unless your database and its adapter is compatible with the Edge runtime/infrastructure, you will not be able to use the `"database"` session strategy**.

    So for example, if you are using an adapter that relies on an ORM/library that is not yet compatible with Edge runtime(s) below is an example where we force the `jwt` strategy and split up the configuration so the library doesn't attempt to access the database in edge environments, like in the middleware.

    So for example, if you are using an adapter that relies on an ORM/library that is not yet compatible with Edge runtime(s) below is an example where we force the `jwt` strategy and split up the configuration so the library doesn't attempt to access the database in edge environments, like in the proxy (or middleware for older Next.js versions).

    <Callout>

      The following filenames are only a convention, they can be named anything you

    @@ -291,24 +291,24 @@ export const { auth, handlers, signIn, signOut } = NextAuth({
  
    })

    ```

    3. In your middleware file, import the configuration object from your first `auth.config.ts` file and use it to lazily initialize Auth.js there. In effect, initialize Auth.js separately with all of your common options, but **without the edge incompatible adapter**.

    3. In your proxy file (or middleware file for older Next.js versions), import the configuration object from your first `auth.config.ts` file and use it to lazily initialize Auth.js there. In effect, initialize Auth.js separately with all of your common options, but **without the edge incompatible adapter**.

    ```ts filename="middleware.ts" {1} /NextAuth/

    ```ts filename="proxy.ts" {1} /NextAuth/

    import authConfig from "./auth.config"

    import NextAuth from "next-auth"

    // Use only one of the two middleware options below

    // 1. Use middleware directly

    // export const { auth: middleware } = NextAuth(authConfig)

    // Use only one of the two proxy options below

    // 1. Use proxy directly

    // export const { auth: proxy } = NextAuth(authConfig)

    // 2. Wrapped middleware option

    // 2. Wrapped proxy option

    const { auth } = NextAuth(authConfig)

    export default auth(async function middleware(req: NextRequest) {

      // Your custom middleware logic goes here

    export const proxy = auth(async function proxy(req: NextRequest) {

      // Your custom proxy logic goes here

    })

    ```

    The above is just an example. **The main idea**, is to separate the part of the configuration that is edge-compatible from the rest, and only import the edge-compatible part in Middleware/Edge pages/routes. You can read more about this workaround in the [Prisma docs](/getting-started/adapters/prisma), for example.

    The above is just an example. **The main idea**, is to separate the part of the configuration that is edge-compatible from the rest, and only import the edge-compatible part in Proxy/Edge pages/routes. You can read more about this workaround in the [Prisma docs](/getting-started/adapters/prisma), for example.

    Please follow up with your library/database/ORM's maintainer to see if they are planning to support the Edge runtime/infrastructure.

docs/pages/getting-started/providers/passkey.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -160,7 +160,7 @@ CREATE UNIQUE INDEX Authenticator_credentialID_key ON Authenticator(credentialID
  
    #### Edge Compatibility

    If you're using `next-auth` with Next.js and middleware, you should ensure that your database client of choice is "edge compatible". If you're using an older version of Prisma or another adapter that is not edge compatible, you'll need to make some adjustments. Check out our [edge compatibility](/guides/edge-compatibility) guide for more details. There is also Prisma specific information in the [Prisma adapter docs](/getting-started/adapters/prisma#edge-compatibility).

    If you're using `next-auth` with Next.js and a proxy (or middleware in older versions), you should ensure that your database client of choice is "edge compatible" when using Next.js versions before 16. In Next.js 16+, `proxy.ts` runs on the Node.js runtime, so edge compatibility is no longer a concern. For older versions, check out our [edge compatibility](/guides/edge-compatibility) guide for more details. There is also Prisma specific information in the [Prisma adapter docs](/getting-started/adapters/prisma#edge-compatibility).

    ### Update Auth.js Configuration

docs/pages/getting-started/session-management/protecting.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -240,12 +240,19 @@ API Routes are protected in the same way as any other route in Express, see [the
  
    </Code.Express>

    </Code>

    ### Next.js Middleware

    ### Next.js Proxy

    With Next.js 12+, the easiest way to protect a set of pages is using the middleware file. You can create a `middleware.ts` file in your root pages directory with the following contents.

    With Next.js 16+, the easiest way to protect a set of pages is using the proxy file. You can create a `proxy.ts` file in your root pages directory with the following contents.

    ```ts filename="middleware.ts"

    export { auth as middleware } from "@/auth"

    <Callout type="info">

      As of Next.js 16, `middleware.ts` has been renamed to `proxy.ts` and the

      exported function has been renamed from `middleware` to `proxy`. If you are

      using an older version of Next.js, use `middleware.ts` and export `auth` as

      `middleware` instead.

    </Callout>

    ```ts filename="proxy.ts"

    export { auth as proxy } from "@/auth"

    ```

    Then define `authorized` callback in your `auth.ts` file. For more details check out the [reference docs](/reference/nextjs#authorized).

    @@ -263,30 +270,30 @@ export const { auth, handlers } = NextAuth({
  
    })

    ```

    You can also use the `auth` method as a wrapper if you'd like to implement more logic inside the middleware.

    You can also use the `auth` method as a wrapper if you'd like to implement more logic inside the proxy.

    ```ts filename="middleware.ts"

    ```ts filename="proxy.ts"

    import { auth } from "@/auth"

    export default auth((req) => {

    export const proxy = auth((req) => {

      if (!req.auth && req.nextUrl.pathname !== "/login") {

        const newUrl = new URL("/login", req.nextUrl.origin)

        return Response.redirect(newUrl)

      }

    })

    ```

    You can also use a regex to match multiple routes or you can negate certain routes in order to protect all remaining routes. The following example avoids running the middleware on paths such as the favicon or static images.

    You can also use a regex to match multiple routes or you can negate certain routes in order to protect all remaining routes. The following example avoids running the proxy on paths such as the favicon or static images.

    ```ts filename="middleware.ts"

    ```ts filename="proxy.ts"

    export const config = {

      matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],

    }

    ```

    Middleware will protect pages as defined by the `matcher` config export. For more details about the matcher, check out the [Next.js docs](https://nextjs.org/docs/pages/building-your-application/routing/middleware#matching-paths).

    The proxy will protect pages as defined by the `matcher` config export. For more details about the matcher, check out the [Next.js docs](https://nextjs.org/docs/app/api-reference/file-conventions/proxy).

    <Callout>

      You should not rely on middleware exclusively for authorization. Always ensure

      You should not rely on the proxy exclusively for authorization. Always ensure

      that the session is verified as close to your data fetching as possible.

    </Callout>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update middleware.ts references to proxy.ts for Next.js 16 #13373

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

docs: update middleware.ts references to proxy.ts for Next.js 16 #13373

Are you sure you want to change the base?

Uh oh!

docs: update middleware.ts references to proxy.ts for Next.js 16 #13373

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!