Wasp Application Runner

A robust script to run your Wasp application (programmatically), including automated database setup and migrations. There are two modes:

• dev: Runs the Wasp app in development mode using wasp start.
• build: Builds the Wasp app for production using wasp build and runs it.

When installed, it provides a run-wasp-app command that can be used to run your Wasp app.

It runs the app, the database, installs all the deps, performs the db migrations, starts a Mailcrab SMTP server for testing email in development, waits before app is actually reachable over HTTP before returning "ready", and kills everything cleanly on exit so no processes are left behind.

Motivation and application

We created Wasp App Runner (WAR) in order to enable easier running of e2e tests for Wasp apps, and that is its main application at the moment.

It is not used only by the Wasp Team internally though: it ships as a dev dep of example apps in this repo and also of OpenSaas template, they all use it for running e2e tests, and therefore Wasp users are also users of WAR. They are not building it themselves though: instead, all these apps pull the published version of WAR from npm.

NOTE: What's bad currently is that it is not obvious to users which WAR version to use with what Wasp version.

NOTE: In the future, ideally, WAR would not be needed any more, as Wasp CLI itself would make running Wasp apps for this use case easier, and the rest would be covered by the thin script for running e2e tests that would be scaffolded again by the Wasp CLI.

Usage

Global dependency:

npm install -g @wasp/wasp-app-runner

run-wasp-app dev

Local dependency:

npm i -D @wasp/wasp-app-runner

npx run-wasp-app dev

You can also use it in npm scripts without the npx prefix, since node_modules/.bin is automatically added to the PATH inside scripts:

Example package.json:

{
  // ...
  "scripts": {
    "run-dev": "run-wasp-app dev",
  },
  // ...
}

One time usage:

npx @wasp/wasp-app-runner dev

Options

npx run-wasp-app <mode> [--path-to-app <path>] [--wasp-cli-cmd <command>] [--db-image <image>]

You must pass the <mode> as an argument, which can be either dev or build.

| Option | Description | Example | | ---------------- | ------------------------------------------------------ | ----------------- | | --path-to-app | Path to your Wasp application directory (default: ".") | ./my-wasp-app | | --wasp-cli-cmd | Wasp CLI command (default: wasp) | wasp-cli | | --db-image | Custom PostgreSQL Docker image (default: postgres) | postgis/postgis |

Postgres Configuration

Check the ./db/postgres.ts file to see the Postgres configuration used.

If Postgres is used, the script automatically sets the DATABASE_URL env variable for the server app:

DATABASE_URL=postgresql://postgres:devpass@localhost:5432/postgres

Custom database image

You can override the Docker image used for Postgres via --db-image. If not provided, the default postgres is used.

Examples: --db-image postgres:15, --db-image pgvector/pgvector:pg16, --db-image postgis/postgis:14-3.2.

[!NOTE] The same requirements as in wasp start db apply for the Postgres image used. See Wasp docs for more details.

Env variables

When using the dev mode:

• If the app you are trying to run has .env.server or .env.client env files defined, the wasp start will use them as expected.

When using the build mode:

• run-wasp-app will use the .env.server file when running the server container with Docker locally (which is not done usually by Wasp).
• .env.client will not be used when building the client, the REACT_APP_API_URL is hard-coded to http://localhost:3001.

Development

When developing, you can run the script directly from the local directory without installing it globally:

npm install
npm run start -- <mode> [--path-to-app <path>] [--wasp-cli-cmd <command>] [--db-image <image>]

npm run start runs npm run build to build the TypeScript code and then runs the ./bin/index.js script.

Publishing

To publish a new version of wasp-app-runner, follow these steps:

1. Update Package Version

Using npm version command:

# For patch releases (bug fixes)
npm version patch

# For minor releases (new features)
npm version minor

# For major releases (breaking changes)
npm version major

2. Authenticate with npm

# Login to npm with an account that has access to the @wasp organization
npm login

3. Publish to npm Registry

# Publish the package publicly
npm publish --access public

4. Ensure new published version is used in the apps

Check that any apps in this repo are using this newer version of wasp-app-runner.