Upgrading Your Blitz App to Blitz 2.0

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:

Update project's default imports

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

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 }

2. 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 {
      // ...
    }
  }