Local development

Prerequisites

Node.js 22 (nvm use 22), pnpm 9 (corepack enable)
Docker (for PostgreSQL and S3-compatible storage for session recordings) — or any PostgreSQL 14+
instance plus an S3 bucket

Setup

pnpm install
cp .env.example .env && cp .env .env.local 2>/dev/null; cp .env apps/web/.env
# edit SESSION_SECRET in both .env files
pnpm db:up            # postgres on localhost:55433 + S3 (SeaweedFS) on localhost:59000 with bucket guidely-replays
pnpm db:migrate       # applies prisma migrations (creates the schema)
pnpm db:seed          # demo workspace, two sample projects, guides, analytics
pnpm build:packages   # builds shared, runtime, sdk, adapters, editor, embed
pnpm dev:web          # dashboard on http://localhost:3000

Demo login: demo@guidely.app / demo1234 (also editor@ and viewer@guidely.app).

Sample applications (install the SDK from the workspace, pointing at the seeded project keys):

pnpm dev:demo-react    # http://localhost:3001  (Next.js, @guidelytech/react)
pnpm dev:demo-svelte   # http://localhost:3002  (SvelteKit, @guidelytech/svelte)
pnpm worker            # pg-boss worker: daily rollups, retention, cleanup

Scripts

Command	What it does
`pnpm build`	Build every package and app (turbo)
`pnpm typecheck` / `pnpm lint`	Type check / lint all packages
`pnpm test`	Unit tests (vitest) for all packages
`pnpm --filter @guidelytech/web test:integration`	API + database tests (use a separate `<database>_test` database, created with the `pg_trgm` extension on first run; recordings go to the local S3)
`pnpm test:e2e`	Playwright suite (needs the seeded DB; starts web + demo apps automatically)
`pnpm db:reset`	Drop, migrate and reseed
`pnpm --filter @guidelytech/web db:studio`	Prisma Studio
`pnpm --filter @guidelytech/web admin:grant <email> [--revoke]`	Make an existing user a platform admin (opens `/admin`)

Repository tour

See docs/architecture.md. Server code lives in apps/web/src/server (services are plain async functions taking an Actor; routes under src/app/api/v1 only parse/validate/respond). UI lives in apps/web/src/app/app/[projectId]/**.

Database migrations

Change apps/web/prisma/schema.prisma, then pnpm db:migrate (prisma migrate dev --name <change>).
Commit the generated folder under apps/web/prisma/migrations.
Production: pnpm db:deploy (prisma migrate deploy) before starting the new build.