Skip to main content
Version: Next

Migration from 0.17.X to 0.18.X

What's new in 0.18.0?​

Wasp now requires Node.js >=22.12​

We've updated our Node.js version requirement to Node.js 22.12 or higher, ahead of the upcoming LTS releases in October 2025.

The jump from Node.js 20 to 22 brings significant performance improvements, new features (like stable fetch or require(esm)), and overall enhanced security.

These releases are light on breaking changes and we expect the vast majority (if not all) of Wasp apps to run on the new version, unchanged.

Wasp now uses Vite 7​

Wasp has upgraded to Vite 7 internally, which brings performance improvements and improved compatibility. You can now also use newer plugins in your Vite configuration that take advantage of Vite 7 features.

This upgrade contains no known breaking changes for Wasp apps and we expect most of them to upgrade without any code changes.

Wasp Tailwind Configuration Now Uses ESM​

Wasp has transitioned from CommonJS (CJS) to ECMAScript Modules (ESM) for Tailwind configuration files. This affects both the import/export syntax and file extensions (.cjs ➝ .js).

Wasp simplified the bash completion setup​

You no longer need to generate a separate file for bash completion. Instead, you can add bash completion directly to your shell configuration.

Additionally, we've added the missing db commands to bash completion.

How to migrate?​

To migrate your Wasp app from 0.16.X to 0.17.X, follow these steps:

1. Install Node.js 22.12 or higher​

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

node -v

If you followed our Quick Start tutorial, you can use nvm use 22 to upgrade your Node.js version. If you installed Node.js some other way, you can check their official installation guide for more guidance.

2. Convert CJS Syntax to ESM​

Update your tailwind.config.cjs file to use ESM:

tailwind.config.cjs
const { resolveProjectPath } = require('wasp/dev')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [resolveProjectPath("./src/**/*.{js,jsx,ts,tsx}")],
  theme: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
};

Same for the postcss.config.cjs file:

postcss.config.cjs
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

3. Rename Tailwind Configuration Files​

Update the Tailwind configuration files' extensions from .cjs to .js:

  • tailwind.config.cjs ➝ tailwind.config.js
  • postcss.config.cjs ➝ postcss.config.js

4. Check your compatibility with Vite 7​

Wasp now uses Vite 7 for better performance and stability. This includes some breaking changes, but we don't expect Wasp apps to be affected by them. If you are using Vite features directly in your app, you should check the migration guides for v5, v6, and v7. We expect most Wasp apps to be unaffected by these changes.

The only manual change you need to make is to update your package.json file:

package.json
{
  // ...
  "devDependencies": {
    // ...
    "vite": "^4.3.9"
  }
}

5. Update you Wasp bash completions (if you used them before)​

Wasp simplified how bash completions work. Instead of maintaining a separate file, you can now enable completions with a single line in your shell configuration.

To update:

  1. Delete the old wasp-completion file.

Previously, we asked you to generate a wasp-completion file in a folder of your choice:

wasp completion:generate > <your-chosen-directory>/wasp-completion"

This file is no longer necessary and we can delete it.

  1. Update your shell configuration

Before, you had to source the wasp-completion file, now we can just call complete directly:

source <your-chosen-directory>/wasp-completion

6. Enjoy your updated Wasp app​

That's it!