Wasp Application Runner

A robust script to run your Wasp application, 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.

Usage

Global dependency:

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

run-wasp-app dev

Local dependency:

npm i -D @wasp.sh/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.sh/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.sh organization
npm login

3. Publish to npm Registry

# Publish the package publicly
npm publish --access public