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; runnvm useor the equivalent for your version manager. - pnpm 12. The exact version is pinned in the root
package.json(packageManager). Install it withnpm 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
pnpm install
pnpm exec playwright install chromiumChromium 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:
pnpm db:envTo 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
pnpm dev # http://localhost:3000
pnpm storybook # http://localhost:6006Local 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.
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 changepnpm 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:
node examples/plain-html/serve.mjsThen 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:
pnpm agent:invite you@example.com --name "Your Name" --adminpnpm 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
pnpm checkThis 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:
pnpm --filter @helpwren/design-system test
pnpm --filter @helpwren/web lint