pnpm dev starts the shared package in watch mode, the API and the web app together through Turborepo.
Prerequisites
Start the development services
postgres:18-alpine on host port 5433 and redis:8-alpine on host port 6380, both bound to 127.0.0.1 so a locally running API can reach them without exposing either service on the network. Their container ports remain 5432 and 6379. The development database uses the password asobeast, which is fine because nothing is exposed beyond your machine. Never reuse it in a deployment.
These services run as the asobeast-dev Compose project, with their own containers and their own volumes. A self hosted stack started from docker-compose.yml on the same machine keeps its data separately, so starting, resetting or removing the development services never touches it.
Install and run
1
Install the workspace
2
Create the local environment files
AUTH_SECRET in apps/api/.env to at least 32 characters. Generate one with openssl rand -hex 32. The API refuses to boot without it.3
Apply migrations and seed
4
Run everything
@asobeast/shared rebuilds on change.Commands
Every command runs from the repository root.Browser tests
Install the browser once before the first Playwright run.node:http mock API runs on port 4100 and serves both server side prefetching and browser fetches, so no PostgreSQL, Redis or store request is involved. Playwright reuses a running dev server locally and builds the production bundle in continuous integration.
Test email alerts locally
Run a throwaway SMTP sink and point the API at it.SMTP_HOST=localhost, SMTP_PORT=1025 and SMTP_FROM=asobeast <alerts@localhost> in apps/api/.env, add an email alert on the settings page, and read the messages at http://localhost:8025.
Repository layout
@asobeast/shared. Prisma generated types never leave apps/api, and packages never import each other by relative path.
All store traffic crosses the StoreProvider boundary in apps/api/src/store-providers/. No other module imports a scraper library, which contains a parser breakage to one file.
Contributing
Commits follow Conventional Commits in the formtype(scope): subject, enforced by a commit-msg hook. Feature work is open on the 1.x line, and what constrains it is the compatibility promise rather than a freeze: the HTTP contract, the @asobeast/shared contract types and the MCP tool surface stay compatible throughout 1.x. See Upgrade and roll back for what that covers.
Read CONTRIBUTING.md before opening a pull request.