Skip to main content
Version: Next

Migration from 0.26 to 0.27

What's new in 0.27?​

Node.js 26​

Wasp now requires Node.js 26 or later, the current LTS line. It enables the Temporal API by default and removes some long-deprecated APIs. Check out Node.js's release notes for the full list of changes.

New npm organization​

Wasp's npm packages moved from the @wasp.sh organization to @wasp. The Wasp CLI is now published as @wasp/cli, and the Wasp Spec is @wasp/spec.

Prisma 6​

Wasp now uses Prisma 6. Check out Prisma's upgrade guide for the full list of changes.

Testing with your own Vitest setup​

Wasp no longer installs and runs Vitest for you. You set it up like in any other Vite app, so you choose the versions of Vitest and the testing libraries.

The wasp/client/test helpers for rendering components and mocking queries and APIs still work. Read more in the testing docs.

Smaller Docker images​

The server's Docker image now contains only the files the server needs at runtime, instead of the whole node_modules folder. This makes the image about half the size.

Wasp finds those files by analyzing the server's imports. Some packages load their files in a non-standard way that this analysis can't follow, and you might need to list them in server.traceDeps.

The build steps are also ordered so that a code change reuses the installed dependencies, which makes rebuilding the image after a code change faster.

Error handling​

Wasp now handles errors in one consistent way on the server and the client.

The server answers every failed request itself. It sends an HttpError you throw as is, and it turns any other error into a generic response that hides the error's details in production.

The server and the client share a single HttpError class, which you import from wasp/errors. Failed Operations and auth actions throw it on the client, so you check for it the same way on both sides.

Wasp logs every unexpected error in the same format and says where it happened. On the server, that now includes uncaught exceptions and unhandled promise rejections, and an unhandled promise rejection no longer stops the server.

The new server.onError and client.onError functions receive those unexpected errors, so you can send them to an error tracking service. Read more in the server config and client config docs.

How to migrate?​

1. Upgrade Node.js to 26.13.1 or later​

Wasp 0.27 requires Node.js >= 26.13.1 (previously >= 24.22.1). The new Wasp CLI refuses to run on older versions, so upgrade before continuing:

node -v
# If below 26.13.1, upgrade:
nvm install 26

If you deploy with the Dockerfile Wasp generates, your server image moves to node:26.13.1-alpine3.23 when you rebuild it. If you use a custom Dockerfile, a CI workflow, or a platform that picks its own Node.js version, make sure it runs 26.13.1 or newer.

Wasp also requires @types/node to match the Node.js major version. Update it in your package.json:

package.json
{
"devDependencies": {
"@types/node": "^24.0.0"
}
}

Node.js 26 is a new major version with breaking changes. Check out Node.js's release notes to see if any of them affect your app.

2. Switch to the new Wasp CLI package​

The Wasp CLI is now published as @wasp/cli instead of @wasp.sh/wasp-cli. Uninstall the old package first, otherwise npm fails with an EEXIST error when installing the new one:

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

3. Rename @wasp.sh/spec to @wasp/spec​

Wasp's packages moved from the @wasp.sh npm scope to @wasp. Rename the Wasp Spec dependency in your package.json:

package.json
{
"devDependencies": {
"@wasp.sh/spec": "file:.wasp/spec"
}
}

Then replace @wasp.sh/spec with @wasp/spec everywhere else in your project. That covers the imports in main.wasp.ts and any other *.wasp.ts files, and mentions in files like AGENTS.md or CLAUDE.md:

main.wasp.ts
import { app, page, route } from "@wasp.sh/spec";

4. Bump the Wasp version​

Update the version field in your Wasp config to ^0.27.0.

main.wasp.ts
export default app({
wasp: { version: "^0.26.0" },
// ...
});

And run the following command to update the Wasp libraries in your project:

wasp install

5. Update your Vitest setup​

The wasp test command is gone, and Wasp no longer installs testing libraries or configures Vitest for you. The wasp/client/test helpers (renderInContext and mockServer) stay, but they now need vitest, msw, and @testing-library/react in your project's devDependencies.

Follow the part that matches your app.

If you don't use wasp test client​

Wasp no longer needs vitest, so you can remove it from your project:

  1. If your vite.config.ts imports defineConfig from vitest/config, import it from vite instead, and remove the test section. Otherwise, Vite can't load your config after you remove vitest.

    vite.config.ts
    import { defineConfig } from "vitest/config";
    import { wasp } from "wasp/client/vite";

    export default defineConfig({
    plugins: [wasp()],
    test: {
    exclude: ["./e2e-tests/**"],
    },
    });
  2. Remove vitest from your devDependencies:

    package.json
    {
    "devDependencies": {
    "vitest": "^4.1.9",
    "vite": "^8.1.0"
    }
    }
  3. Remove the vitest/globals and @testing-library/jest-dom references from src/vite-env.d.ts, if you have them:

    src/vite-env.d.ts
    /// <reference types="vite/client" />
    /// <reference types="vitest/globals" />
    /// <reference types="@testing-library/jest-dom" />

If you use wasp test client​

  1. Install Vitest and the testing libraries your tests use:

    npm install -D vitest jsdom @testing-library/react @testing-library/jest-dom msw

    Wasp's testing helpers need Vitest 5 and MSW 3, so this also upgrades Vitest if your project is on an older version. If your tests use Vitest features that changed, check Vitest's migration guide.

  2. Set up Vitest in your vite.config.ts with Wasp's waspTestConfig helper. It sets the options Wasp used to set for you:

    vite.config.ts
    import { defineConfig } from "vite";
    import { wasp } from "wasp/client/vite";

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

    Wasp used to make test, expect, and the other test functions available globally. If your tests use them without importing them, pass globals: true to waspTestConfig:

    vite.config.ts
    test: waspTestConfig({
    setupFiles: ["./src/test/setup.ts"],
    }),

    Keep the vitest/globals types in src/vite-env.d.ts, so TypeScript knows about the globals when Wasp type-checks your tests:

    src/vite-env.d.ts
    /// <reference types="vite/client" />
    /// <reference types="vitest/globals" />

    Or import them from vitest in each test file instead:

    src/utils.test.ts
    import { add } from "./utils";

    test("adds numbers", () => {
    expect(add(1, 2)).toBe(3);
    });
  3. Create the setup file you referenced in setupFiles. It adds the DOM matchers, like toBeInTheDocument(), and removes what a test rendered when the test ends:

    src/test/setup.ts
    import "@testing-library/jest-dom/vitest";
    import { cleanup } from "@testing-library/react";
    import { afterEach } from "vitest";

    afterEach(() => {
    cleanup();
    });

    The import "@testing-library/jest-dom/vitest" line also adds the types for the DOM matchers, so you can remove the @testing-library/jest-dom reference from src/vite-env.d.ts:

    src/vite-env.d.ts
    /// <reference types="vite/client" />
    /// <reference types="vitest/globals" />
    /// <reference types="@testing-library/jest-dom" />
  4. Run your tests with Vitest instead of wasp test client. Add a test script to your package.json, or change it if it runs wasp test client:

    package.json
    {
    "scripts": {
    "test": "wasp test client"
    }
    }

    Your tests import the Wasp SDK, so generate it first with wasp compile, or keep wasp start running in another terminal:

    wasp compile
    npm test

Read more in the testing docs.

6. Upgrade to Prisma 6​

Update the Prisma packages in your package.json:

package.json
{
"dependencies": {
"@prisma/client": "5.19.1" // if already present
},
"devDependencies": {
"prisma": "5.19.1"
}
}

Then run:

wasp install
wasp db migrate-dev

Prisma 6 changed how some things are stored in the database, so wasp db migrate-dev creates a new migration if your app needs one. Prisma 6 also has a few breaking changes in Prisma Client. Check Prisma's upgrade guide to see if any of them affect your app.

7. Check relative paths in your server code​

The server now runs with your project's root directory as its working directory, instead of .wasp/out/server. In the Docker image, that's /app instead of /app/.wasp/out/server.

If your server code reads or writes files using relative paths, they now resolve from the project root. If you worked around the old behavior (e.g. with paths like ../../../src/data/countries.json), remove the workaround. If you deploy with Docker and mount a volume at a path inside /app/.wasp/out/server, move it to the matching path inside /app.

8. Check the packages your server loads at runtime​

If you didn't add any npm packages to your app yourself, you can skip this step. The packages Wasp uses work out of the box.

Otherwise, check if any of the packages your server uses serve or load files from their own folder, like swagger-ui-express.

The Docker image now contains only the files Wasp finds by following the server's imports. A package that loads files in a non-standard way misses them in the image. A common case is a package that serves static assets from its own folder (e.g. swagger-ui-express), which would fail in production.

List such packages in server.traceDeps to copy all of their files:

main.wasp.ts
export default app({
// ...
server: {
traceDeps: ["swagger-ui-dist*"],
},
})

9. Install the system dependencies your app needs​

If your app doesn't run Python on the server, you can skip this step.

The generated Dockerfile no longer installs python3 in the final image, because the Wasp server doesn't use it. If your app runs Python, install it in a custom Dockerfile:

Dockerfile
RUN apk add --no-cache python3

10. Update your custom Dockerfile​

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

The generated Dockerfile changed. Run wasp dockerfile to print it with your custom Dockerfile appended at the bottom, and check that your steps still apply to the new stages.

The final stage (server-production) no longer contains the /app/node_modules folder. It only has the server's bundle and the packages the bundle uses, in /app/.wasp/out/server. If your steps use other packages (for example, through npx), copy the full node_modules from the server-builder stage:

Dockerfile
COPY --from=server-builder /app/node_modules /app/node_modules

11. Import HttpError from wasp/errors​

The server and the client now use the same HttpError class, so it moved from wasp/server to wasp/errors. Update your imports:

src/queries.ts
import { HttpError } from "wasp/server"

12. Update how you read errors on the client​

On the client, failed operations and auth actions now throw an HttpError, the same class you throw on the server. It replaces WaspHttpError from wasp/client/api, and it differs in two ways:

  • Its data is the data you passed on the server. Before, data held the whole response body, so you had to read error.data.data.
  • It is part of the documented public API, so you can rely on checking for it with instanceof.
src/SignupPage.tsx
try {
await signup({ username, password })
} catch (error: any) {
if (error.statusCode === 422) {
setErrorMessage(error.data.data.message)
}
}

13. Pass HttpError data in the options​

HttpError's third argument is now an options object, and the data is one of its options, next to headers and cause:

src/queries.ts
throw new HttpError(403, "Not allowed", { reason: "NOT_OWNER" })

Its status code is also available as status now. statusCode still works, but it is deprecated.

14. Move your error tracking to onError​

This step is only for apps that send errors to an error tracking service, like Sentry.

Wasp now answers failed requests itself, so an Express error handler you add in setupFn, like Sentry.setupExpressErrorHandler(app), no longer receives them. Capture the errors in the new server.onError function instead:

src/serverSetup.ts
import * as Sentry from "@sentry/node";
import type { ServerSetupFn } from "wasp/server";

Sentry.init({ dsn: process.env.SENTRY_SERVER_DSN });

export const setupServer: ServerSetupFn = async ({ app }) => {
Sentry.setupExpressErrorHandler(app);
};
main.wasp.ts
export default app({
// ...
server: {
setupFn: setupServer,
},
});

On the client, client.onError also receives the errors that an error tracker can't see on its own, like an error thrown while rendering a page.

If you use Sentry, follow the updated Sentry guide for the full setup on both sides.

15. Enjoy your updated Wasp app​

That's it!