🚀Announcing Flightcontrol - Easily Deploy Blitz.js and Next.js to AWS 🚀
Back to Documentation Menu

Usage Guide - Next.js 13 with Blitz Toolkit

Topics

Jump to a Topic

Migration Guide

Blitz does not require any breaking changes with the major upgrade of Next 12 âž” Next 13 for usage with the pages directory. You can even continue to use the old blitz layout with all your files in app. But you'll need to rename that directory if you want to use the new Next.js app router.

The migration guide provided by the Next.js Team can then be followed to completely upgrade your Next 12 application

Upgrading Guide

https://nextjs.org/docs/upgrading#upgrading-from-12-to-13

Codemods

https://nextjs.org/docs/advanced-features/codemods

Support with the App Router (Beta)

To support the new paradigm of Next that uses React Server Side Components, the following methods and hooks have been implemented to work in the new app directory

Required changes

Add the new use client directive to the following files:

  1. src/blitz-client.(ts|js)
  2. All Files with usage of useQuery, useInfiniteQuery, usePaginatedQuery, useMutation, Hydrate and other React Query client side hooks.

What not to change:

/pags/api/rpc/[[...blitz]].ts stays in the /pages folder.

Recommendations

  • For Blitz apps that have their pages at /src/pages it is recommended to colocate the app directory at /src/app. However, a root /app App directory is also supported. More on the new NextJS file structure at "Project Organization and File Colocation".

BlitzProvider

This provider should wrap the app and should be placed at the (root)/layout.ts file.

Setup 

// src/blitz-client.ts

"use client"
import {AuthClientPlugin} from "@blitzjs/auth"
import {setupBlitzClient} from "@blitzjs/next"
import {BlitzRpcPlugin} from "@blitzjs/rpc"
import { authConfig } from './blitz-auth-config'

export const {withBlitz, BlitzProvider} = setupBlitzClient({
  plugins: [
    AuthClientPlugin(authConfig),
    BlitzRpcPlugin({}),
  ],
})

The authConfig needs to be in a separate file that is imported in blitz-client.ts as well as blitz-server.ts:

// src/blitz-auth-config.ts
import { AuthPluginClientOptions } from '@blitzjs/auth'

export const authConfig: AuthPluginClientOptions = {
  cookiePrefix: "blitz-auth-with-next-app",
}

In root layout.ts file

// src/layout.ts
import { BlitzProvider } from "src/blitz-client"

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <head>
        ...
      </head>
      <body>
        <BlitzProvider>
          ...
        </BlitzProvider>
      </body>
    </html>
  )
}

Blitz Auth

getBlitzContext

This function will use the cookies and headers provided by the server component and returns the current session.

API
getBlitzContext() => Ctx
Usage

Example Usage in React Server Component in app directory in Next 13

Setup

// src/blitz-server.ts
export const { ... , useAuthenticatedBlitzContext} = setupBlitzServer({
  ...
})

In a RSC page or layout

import {getBlitzContext} from "src/blitz-server"
import getCurrentUser from "src/users/queries/getCurrentUser"

export default async function Home() {
  const ctx = await getBlitzContext()
  const user = await getCurrentUser(null, ctx)
  return(
    <>
        ...
    </>
  )
}
useAuthenticatedBlitzContext

  1. This hook is implemented as the replacement of the BlitzPage Security Auth Utilities provided for the pages directory to work with React Server Components in the Next 13 app directory

  2. It can be used in any asynchronous server component be it in page.ts or in the layouts in layout.ts

API
useAuthenticatedBlitzContext({
  redirectTo,
  redirectAuthenticatedTo,
  role,
}: {
  redirectTo?: string | RouteUrlObject
  redirectAuthenticatedTo?: string | RouteUrlObject | ((ctx: Ctx) => string | RouteUrlObject)
  role?: string | string[]
}): Promise<void>
Explaintation of each parameter
  1. redirectTo

The URL or Route object passed to this parameter will be used to redirect unauthenticated users (logged-out) and the users whose roles does not satisfy the required roles mentioned in the roles parameter

  1. role

This parameter takes a role (as string) or multipe roles to be used to authorize user access to a particular page or layout

  1. redirectAuthenticatedTo

The URL or Route object passed to this parameter will be used to redirect authenticated (logged-in) users.

Usage

Example Usage in React Server Component in app directory in Next 13

Setup

// src/blitz-server.ts
export const { ... , useAuthenticatedBlitzContext} = setupBlitzServer({
  ...
})

In a RSC Page or Layout

import {useAuthenticatedBlitzContext} from "src/blitz-server"
...
await useAuthenticatedBlitzContext({
    redirectTo: "/auth/login",
    role: ["admin"],
    redirectAuthenticatedTo: "/dashboard",
})

Blitz RPC

The following method are to be used to invoke a resolver in a react server component

Using invoke

Let's say there is a requirement to query a resolver in the (root)/page.js file to check the details of the current user

First import the invoke function from the blitz-server file.

Note we cannot directly import invoke from @blitzjs/rpc due to the necessity to run the required middleware in order to make it work effectively.

Setup

// src/blitz-server.ts
import {RpcServerPlugin} from "@blitzjs/rpc"
...
export const {... , invoke} = setupBlitzServer({
  plugins: [
    ...
    RpcServerPlugin({}),
  ]
  ...
})

In a RSC Page or Layout

import {invoke} from "src/blitz-server"
import getCurrentUser from "src/users/queries/getCurrentUser"

Now, we can directly invoke the resolver using the invoke function

const user = await invoke(getCurrentUser, null)
Idea for improving this page? Edit it on GitHub.
Blitz Auth with Next.js
@blitzjs/next