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

Upgrading Your Blitz App to Blitz 2.0

Topics

Jump to a Topic

If you have an existing Blitz.js app, and would like to upgrade it to the Blitz 2.0 (Toolkit), you can use our codemods package. You can install it globally with:

yarn global add @blitzjs/codemod

# or

pnpm add -g @blitzjs/codemod

# or

npm i -g @blitzjs/codemod

Then, inside your Blitz app, you can run:

@blitzjs/codemod upgrade-legacy

You can also use npx insetad of installing the package globally:

npx @blitzjs/codemod upgrade-legacy

After running the above command, your Blitz app will be upgraded to the Blitz 2.0. If you face any issues with the codemods — let us know! We'd appreciate the feedback.

Manual Upgrade Steps

Below, we're going to list down the steps performed by the codemod in case you want to do some of them or all of them manually. Also, in case something goes wrong with the codemod tool, you can follow these steps to upgrade your app:

Rename the blitz.config.ts file to next.config.js

Inside of the config file, you'll also need to wrap the config with withBlitz function imported from @blitzjs/next:

const { withBlitz } = require("@blitzjs/next")

module.exports = withBlitz()

Update dependencies in package.json

  1. Update react, react-dom to the latest versions.
  2. Install @blitzjs/next@alpha, @blitzjs/rpc@latest, @blitzjs/auth@latest.
  3. Set blitz version to alpha.
  4. Upgrade next to the latest version.

Update project's named imports

Now, for most of the things previously imported from blitz package, you'd need to update the import to the new packages. Use the following list as a reference:

ImportSource Package
GetServerSidePropsnext
InferGetServerSidePropsTypenext
GetServerSidePropsContextnext
useRouterQuery:next/router
useRouternext/router
Routernext/router
Linknext/link
Imagenext/image
Scriptnext/script
Documentnext/document
DocumentHeadnext/document
Htmlnext/document
Mainnext/document
Headnext/head
Appnext/app
dynamicnext/dynamic
noSSRnext/dynamic
getConfignext/config
setConfignext/config
ErrorBoundary@blitzjs/next
ErrorFallbackProps@blitzjs/next
useParam@blitzjs/next
Routes@blitzjs/next
ErrorComponent@blitzjs/next
AppProps@blitzjs/next
BlitzPage@blitzjs/next
BlitzLayout@blitzjs/next
invokeWithMiddleware@blitzjs/rpc
resolver@blitzjs/rpc
getAntiCSRFToken@blitzjs/rpc
useQuery@blitzjs/rpc
usePaginatedQuery@blitzjs/rpc
useInfiniteQuery@blitzjs/rpc
useMutation@blitzjs/rpc
queryClient@blitzjs/rpc
getQueryKey@blitzjs/rpc
getInfiniteQueryKey@blitzjs/rpc
invalidateQuery@blitzjs/rpc
setQueryData@blitzjs/rpc
useQueryErrorResetBoundary@blitzjs/rpc
QueryClient@blitzjs/rpc
dehydrate@blitzjs/rpc
invoke@blitzjs/rpc
passportAuth@blitzjs/auth
sessionMiddleware@blitzjs/auth
simpleRolesIsAuthorized@blitzjs/auth
getSession@blitzjs/auth
setPublicDataForUser@blitzjs/auth
SecurePassword@blitzjs/auth
hash256@blitzjs/auth
generateToken@blitzjs/auth
useAuthenticatedSession@blitzjs/auth
useRedirectAuthenticated@blitzjs/auth
useSession@blitzjs/auth
useAuthorize@blitzjs/auth

Update project's default imports

There are also some default imports that you'll need to update. Use the following list as a reference:

Default ImportSource Package
Linknext/link
Imagenext/image
Headnext/head

Create blitz-server.ts and blitz-client.ts

To configure the plugins, you'd need to add the following files to your project:

  1. blitz-server.ts:
import { setupBlitzServer } from "@blitzjs/next"
import { AuthServerPlugin, PrismaStorage } from "@blitzjs/auth"
import { db } from "db"
import { simpleRolesIsAuthorized } from "@blitzjs/auth"

const { gSSP, gSP, api } = setupBlitzServer({
  plugins: [
    AuthServerPlugin({
      cookiePrefix: "blitz-app",
      storage: PrismaStorage(db),
      isAuthorized: simpleRolesIsAuthorized,
    }),
  ],
})

export { gSSP, gSP, api }
  1. blitz-client.ts:
import { AuthClientPlugin } from "@blitzjs/auth"
import { setupBlitzClient } from "@blitzjs/next"
import { BlitzRpcPlugin } from "@blitzjs/rpc"

export const { withBlitz } = setupBlitzClient({
  plugins: [
    AuthClientPlugin({
      cookiePrefix: "blitz-app",
    }),
    BlitzRpcPlugin(),
  ],
})

Create API Route for the Zero-API Layer

To setup the Zero-API layer, you'd need to create a pages/api/rpc/[[blitz]].ts file with the following content:

import { rpcHandler } from "@blitzjs/rpc"
import { api } from "app/blitz-server"

export default api(rpcHandler())

Move app/pages to the root of your app

Instead of having pages inside of the app directory, you'll need to add them to the top level of your project.

Remove babel.config.js

It's not needed anymore.

Move all pages to pages directory

Having pages in separate directories in not supported with Next.js. They now have to be consolidated in the top level pages directory.

Move API Routes to pages/api directory

All your API Routes have to be inside of the pages/api directory.

Wrap your App component with withBlitz

To use Blitz on the client, you also have to use the withBlitz function in your App component.

import { withBlitz } from "app/blitz-client"

function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

export default withBlitz(App)

Wrapping getServerSideProps, getStaticProps, and API Routes

If you want to access the Blitz context inside of the getServerSideProps, getStaticProps, and API Routes, you'll need to wrap them with corresponding functions: gSSP, gSP, and api imported from @blitzjs/next.

To learn more about it, follow the @blitzjs/next docs.

Replacing queryClient with getQueryClient function

If you're using queryClient in your code, you can replace it with the following code:

import { getQueryClient } from "@blitzjs/rpc"

const queryClient = getQueryClient()

types.ts changes

In your types.ts file, you'll need to change the module that is being augmented:

- declare module "@blitzjs/auth" {
+ declare module "@blitzjs/auth" {
    export interface Session {
      // ...
    }
  }

Idea for improving this page? Edit it on GitHub.