Skip to Content
Docs

Development setup

Run Helpwren on your own machine to work on it, with a local database and demo data.

To install Helpwren for real use, see Choose how to install.

Requirements

  • Node 26 (the current LTS). The version is pinned in .nvmrc; run nvm use or the equivalent for your version manager.
  • pnpm 12. The exact version is pinned in the root package.json (packageManager). Install it with npm install --global pnpm@12, or follow the pnpm installation guide.
  • Docker, for the local database. Docker Desktop is the easiest option on macOS and Windows; any Docker-compatible runtime works. It must be running whenever you use the db: commands below.

Install

Terminal
pnpm install
pnpm exec playwright install chromium

Chromium is used to run Storybook stories as tests. It is a one-time download.

Environment variables

The app needs to know where its Supabase project is. With the local database running, this writes apps/web/.env.local for you:

Terminal
pnpm db:env

To point at another project, copy .env.example to apps/web/.env.local and fill it in. Every variable is validated at startup by the Zod schema in apps/web/src/lib/env.ts.

Run

Terminal
pnpm dev          # http://localhost:3000
pnpm storybook    # http://localhost:6006

Local database

Helpwren runs on Supabase. The Supabase CLI is a dev dependency, so pnpm install brings it, and it runs the whole stack (Postgres, Auth, Realtime, Storage and a test mailbox) in Docker on your machine. No Supabase account is needed for development.

Terminal
pnpm db:start     # start the stack; the first run downloads the images and takes a while
pnpm db:status    # print the local URLs and keys
pnpm db:reset     # rebuild the database from supabase/migrations and the seed data
pnpm db:stop      # stop the stack and keep its data
pnpm db:env       # write apps/web/.env.local for the local stack
pnpm db:test      # run the access-rule tests in supabase/tests
pnpm test:db      # run the tests that need the database: the client library and API routes
pnpm test:e2e     # run the browser tests in apps/web/e2e against the local stack
pnpm db:lint      # check the schema for mistakes
pnpm db:types     # regenerate packages/core/src/database.types.ts after a schema change

pnpm db:reset loads demo data from supabase/seed.sql: two team members (ada@example.com, an admin, and sam@example.com), a few contacts and some conversations.

Try the chat

Open http://localhost:3000/embed. It is the visitor's side, sized for a phone or the widget's frame. The demo data asks guests for a name and an email or phone number; change the guest_details row in the settings table to "email", "phone" or "none" to see the others.

To see it as a site's visitor would, through the widget:

Terminal
node examples/plain-html/serve.mjs

Then open http://127.0.0.1:4100.

Sign in to the dashboard

Open http://localhost:3000/dashboard and enter one of the demo emails. The six-digit code arrives in Mailpit, the local test mailbox, at http://127.0.0.1:54324. Keep /embed open in another window to write as a visitor and see both sides update live. Ada is an admin and can add team members under Settings, then Team. On an install with no admin yet, open http://localhost:3000/setup to create the first one, or add them from the command line:

Terminal
pnpm agent:invite you@example.com --name "Your Name" --admin

pnpm db:status also prints the address of Supabase Studio, a browser interface for the local database, and of Mailpit, which catches every email the local stack sends. Local settings live in supabase/config.toml.

Email and scheduled jobs

Email is off until a provider is set in apps/web/.env.local; see Sending email. Every email the local stack sends, including team sign-in codes, lands in Mailpit at http://127.0.0.1:54324.

To try emails and pushes locally, set CRON_SECRET and call the jobs by hand, as Scheduled jobs shows, with http://localhost:3000 as the address. Replies by email shows how to post a reply without a mail provider.

Check your work

Terminal
pnpm check

This runs the Prettier check, then lint, typecheck, tests and build through Turborepo, which is what CI runs. Turborepo caches results, so unchanged packages are skipped.

To work on one package:

Terminal
pnpm --filter @helpwren/design-system test
pnpm --filter @helpwren/web lint