Skip to main content
Version: Next

Migration from 0.20.X to 0.21.X

To install the latest version of Wasp, open your terminal and run:

curl -sSL https://get.wasp.sh/installer.sh | sh

If you want to install Wasp 0.21.0 specifically, you can pass a version argument to the install script:

curl -sSL https://get.wasp.sh/installer.sh | sh -s -- -v 0.21.0

What's new in 0.21.X?​

New npm-based installation​

Starting from Wasp 0.21.X, the recommended way to install Wasp is via npm. This simplifies the installation process and makes it easier to manage Wasp versions. For now, both the old and new installation methods are supported, but we recommend switching to the npm-based installation.

To switch from the old installation method to the new one, simply uninstall Wasp using the old method and then install it again via npm:

wasp uninstall
npm i -g @wasp.sh/wasp-cli@latest

Better Tailwind CSS support​

With this change, we will not require you to upgrade Tailwind CSS in lockstep with Wasp anymore. You can use any version of Tailwind CSS v4 or newer in your Wasp app, and upgrade it (or not) at your own pace.

In previous versions of Wasp, we used a custom way of handling Tailwind CSS configuration files, which tightly coupled us to a specific version. Due to the new Vite installation method in version 4, we can simplify our support, and remove all custom steps. Now Tailwind CSS is just a regular dependency in your Wasp app like any other.

Merged the .wasp/out and .wasp/build directories​

In previous versions of Wasp, there were two separate directories for generated code: .wasp/out (used in development mode) and .wasp/build (used in production mode). Starting from Wasp 0.21.X, only the .wasp/out directory is used for generated code in both development and production modes. This change simplifies the project structure and reduces confusion.

Upgraded to React Router 7​

Wasp has upgraded from React Router 6 to React Router 7. The only change you should notice is that the package has been renamed from react-router-dom to react-router, so you'll need to update your package.json and imports accordingly.

Upgraded to Vitest 4​

Wasp has upgraded its testing framework from Vitest 1 all the way to Vitest 4. This brings a lot of improvements, especially in terms of performance and stability. Most users should not notice any breaking changes, but if you have custom test setups or configurations, please refer to the Vitest migration guide for more details.

How to migrate?​

To migrate your Wasp app from 0.20.X to 0.21.X, follow these steps:

1. Bump the Wasp version​

Update the version field in your Wasp file to ^0.21.0:

main.wasp
app MyApp {
  wasp: {
    version: "^0.21.0"
  },
}

2. Update your package.json​

We've rearranged our workspace architecture a bit, so you'll need to update the dependencies and workspaces fields in your package.json file.

  • In your workspaces array:
    • Remove .wasp/build/*.
    • Add .wasp/out/sdk/wasp.
  • In your dependencies object:
    • Remove the wasp dependency.
    • Rename react-router-dom to react-router (and update the version).
package.json
{
  "workspaces": [
    ".wasp/build/*",
    ".wasp/out/*"
  ],
  "dependencies": {
    "react-router-dom": "^6.26.2",
    // ... other dependencies ...
    "wasp": "file:.wasp/out/sdk/wasp"
  }
  // ... other fields ...
}

Now, we will clean up the old .wasp directory (to avoid any potential conflicts), and let npm pick up the new workspace configuration. You can do this by running the following command in your terminal:

wasp clean
wasp ts-setup # if you're using the TS Spec
wasp compile

3. Update React Router imports​

We've upgraded from React Router 6 to React Router 7. The package has been renamed from react-router-dom to react-router, so you'll need to update your imports.

Search your codebase for the string react-router-dom and update imports to react-router:

src/SomePage.tsx
import { useNavigate, useParams } from 'react-router-dom'

// ...

React Router v7 is largely backwards compatible with v6, so there shouldn't be any changes besides the name. For advanced usage, check the React Router v6 to v7 upgrade guide.

4. Upgrade Tailwind CSS to v4​

If you don't have a tailwindcss dependency in your package.json, you can skip this step.

  1. Run the Tailwind CSS upgrade tool:

    npx @tailwindcss/upgrade

    It will update any changed classes to the new name, and migrate your config file to the new CSS format.

  2. Remove the @tailwindcss/postcss plugin from your postcss.config.js file.

    postcss.config.js
    export default {
      plugins: {
        '@tailwindcss/postcss': {},
      },
    };

  3. Uninstall the @tailwindcss/postcss package and install @tailwindcss/vite.

    npm un @tailwindcss/postcss
    npm i -D @tailwindcss/vite

  4. Add the @tailwindcss/vite plugin to your vite.config.ts file.

    vite.config.ts
    import tailwindcss from '@tailwindcss/vite';
    import { defineConfig } from 'vite';

    export default defineConfig({
      plugins: [
        tailwindcss(),
      ],
    });

  5. Find the CSS file with the @import "tailwindcss" directive and add source(".") to it.

    If you used the default starter templates, the file will be src/Main.css or src/App.css. If it is in a different location, adjust the path in source() accordingly, so that it points to your src folder.

    src/Main.css
    @import "tailwindcss";

    /* ... */

If you hit any snags or would like more details, check out the official Tailwind CSS v4 upgrade guide, and our updated Tailwind documentation.

5. Update your custom Dockerfile​

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

If you have a custom Dockerfile in your project, you need to update it to reference the new .wasp/out directory instead of the removed .wasp/build directory.

This can be a quite straightforward find-and-replace operation:

  • Find .wasp/build
  • Replace with .wasp/out

6. Update your custom deployment scripts​

If you use wasp deploy fly or wasp deploy railway to deploy your app, you can skip this step.

If you have custom deployment scripts, you'll need to update them to reference the new .wasp/out directory instead of the removed .wasp/build directory.

This can be a quite straightforward find-and-replace operation:

  • Find .wasp/build
  • Replace with .wasp/out

You can check our updated deployment methods guide and CI/CD guide for reference on the correct deployment steps.

7. Upgrade Vitest tests to v4​

If you don't have test files in your project, you can skip this step.

We upgraded our testing support from Vitest v1 to Vitest v4. Most of the breaking changes are related to internal configuration, edge cases, or very advanced usage; so we recommend first to try running your tests after bumping the Wasp version, and only read through the migration guides if you encounter issues:

  1. Migration guide from Vitest v1 to v2
  2. Migration guide from Vitest v2 to v3
  3. Migration guide from Vitest v3 to v4

8. Add netlify.toml if deploying to Netlify​

If you're not deploying to Netlify, you can skip this step.

Wasp no longer generates a netlify.toml file in your project. If you're deploying to Netlify, you'll need to create this file manually in your project root.

Create a netlify.toml file with the following content:

netlify.toml
[build]
  base = "./.wasp/out/web-app"
  publish = "./build"
  command = "exit 0"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

For more details, see the Netlify deployment documentation.

9. Enjoy your updated Wasp app​

That's it!