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.
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:
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()
package.json
react
, react-dom
to the latest versions.@blitzjs/next@alpha
, @blitzjs/rpc@latest
,
@blitzjs/auth@latest
.blitz
version to alpha
.next
to the latest version.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:
Import | Source Package |
---|---|
GetServerSideProps | next |
InferGetServerSidePropsType | next |
GetServerSidePropsContext | next |
useRouterQuery : | next/router |
useRouter | next/router |
Router | next/router |
Link | next/link |
Image | next/image |
Script | next/script |
Document | next/document |
DocumentHead | next/document |
Html | next/document |
Main | next/document |
Head | next/head |
App | next/app |
dynamic | next/dynamic |
noSSR | next/dynamic |
getConfig | next/config |
setConfig | next/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 |
There are also some default imports that you'll need to update. Use the following list as a reference:
Default Import | Source Package |
---|---|
Link | next/link |
Image | next/image |
Head | next/head |
blitz-server.ts
and blitz-client.ts
To configure the plugins, you'd need to add the following files to your project:
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 }
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(),
],
})
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())
app/pages
to the root of your appInstead of having pages inside of the app
directory, you'll need to add
them to the top level of your project.
babel.config.js
It's not needed anymore.
pages
directoryHaving pages in separate directories in not supported with Next.js. They
now have to be consolidated in the top level pages
directory.
pages/api
directoryAll your API Routes have to be inside of the pages/api
directory.
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)
getServerSideProps
, getStaticProps
, and API RoutesIf 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.
queryClient
with getQueryClient
functionIf 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
changesIn 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 {
// ...
}
}