Migration from 0.21.X to 0.22.X

import InstallInstructions from './_install-instructions.md' import LegacyInstallerMigration from './_legacy_installer_migration.md'

What's new in 0.22.X?

Node.js minimum version bumped to 22.22.2

Wasp now requires Node.js 22.22.2 or higher due to the March 2026 Node.js security releases. If you're on an older Node.js 22.x version, upgrade before updating Wasp.

Docker base image upgraded to Alpine 3.23

The Dockerfile generated by wasp build now uses Alpine 3.23 (previously 3.20). If you have a custom Dockerfile that installs packages, check that those packages are still available on Alpine 3.23.

Upgraded Zod to v4

Wasp now uses Zod v4 for environment variable validation. If you have custom env validation schemas, you may need to update them to be compatible with the latest Zod API. Check the Zod v4 announcement for details on what changed.

How to migrate?

1. Upgrade Node.js to 22.22.2 or higher

Make sure you have Node.js 22.22.2 or higher installed. You can check your current version with:

node -v

If you need to upgrade, we recommend using nvm:

nvm install 22.22.2

2. Bump the Wasp version

Update the version field in your Wasp config to ^0.22.0:

app MyApp {
  wasp: {
    version: "^0.22.0"
  },
  // ...
}

3. Update your app.head tags to be valid React

If you don't have app.head defined in your Wasp file, you can skip this step.

We now use React to output the base index.html for your client app, as we set the groundwork for SSR support in the future. This means that the contents of app.head are now rendered as React JSX instead of raw HTML.

To make sure all tags in app.head are valid React JSX, check that every tag is either self-closing (e.g. <meta ... />) or has a matching closing tag (e.g. <script>...</script>). In JSX, even void HTML elements (like <link>, <meta>, and <base>) need a trailing />.

Wasp will print an error on compilation if it encounters any invalid JSX in app.head, so you can use that as a guide to fix any issues.

Also, if you have any <script defer> tags in app.head, you should replace defer with async, due to a bug in React, or you will get hydration warnings.

For example, if your app.head looked like this before:

app MyApp {
  // ...
  head: [
    // highlight-next-line
    "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto\">",
    // highlight-next-line
    "<meta name=\"description\" content=\"My App\">",
    // highlight-next-line
    "<script defer src=\"https://example.com/script.js\"></script>"
  ]
}

You should update it to:

app MyApp {
  // ...
  head: [
    // highlight-next-line
    "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css?family=Roboto\" />",
    // highlight-next-line
    "<meta name=\"description\" content=\"My App\" />",
    // highlight-next-line
    "<script async src=\"https://example.com/script.js\"></script>"
  ]
}

4. Update your env validation schemas

If you don't have app.client.envValidationSchema or app.server.envValidationSchema defined in your Wasp file, you can skip this step.

Review your schemas for compatibility with Zod v4. Most schemas will work without changes, but some deprecated APIs have been removed. Refer to the Zod v4 migration guide for details.

5. Update Alpine packages in your Dockerfile

If you don't have a Dockerfile in your project, you can skip this step.

If you have install any additional packages in your Dockerfile, make sure those packages are available and compatible in Alpine 3.23. You can check the Alpine package repository at pkgs.alpinelinux.org to verify availability and update your Dockerfile accordingly. Most users won't need to make any changes here.