Skip to main content
Version: Next

Migration from 0.25 to 0.26

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

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

You can install Wasp 0.26 specifically by passing the version to the install script:

npm i -g @wasp.sh/wasp-cli@0.26

What's new in 0.26?​

Running multiple Wasp apps side by side​

wasp start now decides which ports the client and the server run on. If the default ports (3000 and 3001) are taken, it moves the app to free ones instead of failing, so you can run several Wasp apps side by side.

This is great for using agents in parallel worktrees, as each one won't conflict with the other.

You can also pick the ports yourself:

wasp start --client-port 4000 --server-port 4001
wasp build start --client-port 4000 --server-port 4001

In development, setting the ports manually in the env vars or the Vite config now fails, and you should use these new CLI flags. In production, the PORT variable is now required.

How to migrate?​

1. Bump the Wasp version​

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

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

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

wasp install

2. Update your TypeScript config​

Due to wasp/sdk package changes, we require some changes to your TypeScript configuration.

In tsconfig.src.json, update the include field:

tsconfig.src.json
{
  "compilerOptions": {
    // ...
  },
  "include": ["src"]
}

3. Stop setting the dev ports and URLs yourself​

Wasp now picks the ports your app runs on in development and derives its URLs from them, so it fails if you also set them.

If your vite.config.ts sets server.port or server.strictPort, remove it:

vite.config.ts
export default defineConfig({
  server: {
    port: 4000,
  },
  plugins: [wasp()],
});

You should also remove PORT, WASP_SERVER_URL and WASP_WEB_CLIENT_URL from your .env.server if you were setting those manually:

.env.server
PORT=4001
WASP_SERVER_URL=http://localhost:4001
WASP_WEB_CLIENT_URL=http://localhost:4000
JWT_SECRET=my-secret

And REACT_APP_API_URL from your .env.client if present:

.env.client
REACT_APP_API_URL=http://localhost:4001
REACT_APP_NAME=My App

To keep running on those ports, pass them to wasp start or wasp build start instead:

wasp start --client-port 4000 --server-port 4001

Wasp fills in the URLs for you from the ports it picked, so you no longer have to keep them in sync by hand.

info

Your deployed app still uses these environment variables, so don't remove them from your deploy configuration. Wasp only takes them over in development, where it is the one starting your app.

4. Set PORT in deployment​

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

PORT used to fall back to 3001 when you didn't set it. It no longer has a default, so the server refuses to start without it.

Most deployment platforms set PORT for you, but it's worth it to check it in their documentation or your deployment configuration.

Server env vars
PORT=3001

5. Update your custom Dockerfile​

If you are using a custom Dockerfile, due to wasp/sdk package changes, you'll have to add a one new additional line to it:

Dockerfile
# ...
COPY sdk .wasp/out/sdk
COPY libs .wasp/out/libs
# ...

4. Update Fly database deployment flags​

If you use database sizing options with wasp deploy fly launch or wasp deploy fly create-db, rename them as follows:

BeforeAfter
--vm-size--db-vm-size
--initial-cluster-size--db-initial-cluster-size
--volume-size--db-volume-size

6. Enjoy your updated Wasp app​

That's it!