build: migrate client and backend to pnpm workspace

.dockerignore

@@ -4,6 +4,8 @@
 # emitting into a dist the context no longer carries.
 .git
 **/node_modules
+**/.env
+**/.env.*
 **/*.tsbuildinfo
 client/.next
 server/dist

.github/dependabot.yml

@@ -1,11 +1,6 @@
 version: 2
 updates:
   - package-ecosystem: "npm"
-    directory: "/client"
-    schedule:
-      interval: "daily"
-
-  - package-ecosystem: "npm"
-    directory: "/server"
+    directory: "/"
     schedule:
       interval: "daily"

.github/workflows/test.yml

@@ -60,54 +60,45 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: npm
-          cache-dependency-path: |
-            shared/package-lock.json
-            server/package-lock.json
-
-      # server depends on @rybbit/shared via `file:../shared`, which resolves to
-      # the package's built `dist/` — so shared must be built before install.
-      - name: Install and build shared
-        working-directory: shared
-        run: |
-          npm ci
-          npm run build
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install server dependencies
-        working-directory: server
-        run: npm ci --legacy-peer-deps
+        run: pnpm --filter rybbit-backend... install --frozen-lockfile
+
+      - name: Build server and shared
+        run: pnpm build:server
 
       - name: Run server tests
-        working-directory: server
-        run: npm run test:run
+        run: pnpm --filter rybbit-backend test:run
 
   client:
     name: Client
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
+      - uses: pnpm/action-setup@v4
+
       - uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: npm
-          cache-dependency-path: |
-            shared/package-lock.json
-            client/package-lock.json
-
-      - name: Install and build shared
-        working-directory: shared
-        run: |
-          npm ci
-          npm run build
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install client dependencies
-        working-directory: client
-        run: npm ci --legacy-peer-deps
+        run: pnpm --filter client... install --frozen-lockfile
+
+      - name: Build shared
+        run: pnpm --filter @rybbit/shared build
 
       - name: Run client tests
-        working-directory: client
-        run: npm test
+        run: pnpm --filter client test:run
+
+      - name: Build client
+        run: pnpm --filter client build

.github/workflows/translate.yml

@@ -21,16 +21,20 @@ jobs:
         with:
           fetch-depth: 1
 
+      - uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 24
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd client && npm ci
+        run: pnpm --filter client... install --frozen-lockfile
 
       - name: Extract messages
-        run: cd client && node scripts/extract-messages.mjs
+        run: pnpm --filter client extract
 
       - name: Check for untranslated strings
         id: changes
@@ -70,16 +74,20 @@ jobs:
         with:
           fetch-depth: 1
 
+      - uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 24
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd client && npm ci
+        run: pnpm --filter client... install --frozen-lockfile
 
       - name: Extract messages
-        run: cd client && node scripts/extract-messages.mjs
+        run: pnpm --filter client extract
 
       - name: Run Claude Code
         uses: anthropics/claude-code-action@v1

.nvmrc

@@ -0,0 +1 @@
+24

CLAUDE.md

@@ -4,11 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Commands
 
-- Client: `cd client && npm run dev` (NextJS with Turbopack on port 3002)
-- Server: `cd server && npm run dev` (TypeScript backend)
-- Lint: `cd client && npm run lint` or `cd server && npm run build`
-- TypeCheck: `cd client && tsc --noEmit` or `cd server && tsc`
-- Database: `cd server && npm run db:generate` (generate migration files after schema changes; applied with `npm run db:migrate`)
+The root pnpm workspace contains `client`, `server`, and `shared`; docs is separate.
+Run `pnpm install` at the root. Root `pnpm dev`, `pnpm build`, `pnpm test`, and
+`pnpm typecheck` build shared code before running the apps.
+
+- Client: `pnpm dev:client` (NextJS with Turbopack on port 3002)
+- Server: `pnpm dev:server` (TypeScript backend)
+- Lint: `cd client && pnpm run lint` or `pnpm build:server`
+- TypeCheck: `pnpm --filter client typecheck` or `pnpm --filter rybbit-backend typecheck`
+- Database: `cd server && pnpm run db:generate` (generate migration files after schema changes; applied with `pnpm run db:migrate`)
 
 ## Code Conventions
 

CONTRIBUTE.md

@@ -41,6 +41,67 @@ Pull requests are welcome! Please keep in mind:
 - Include relevant context or links to issues/discussions.
 - PRs will be reviewed and merged by the maintainers once they meet quality standards and align with the project direction.
 
+### Local development
+
+The application is a pnpm workspace containing `client/`, `server/`, and `shared/`.
+The docs app and React Native SDK are separate projects and keep their own tooling.
+Use Node.js 24 (`nvm use`) and the pnpm version pinned in the root `package.json`:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+Configure the backend environment and its Postgres, ClickHouse, and Redis services
+before starting the app. The client runs on port 3002 and the backend on port 3001.
+`pnpm dev` builds shared code first, then starts its TypeScript watcher alongside
+both apps. The backend's existing dev command compiles once; restart it after
+backend changes.
+
+Run these commands from the repository root:
+
+| Command             | Purpose                                                  |
+| ------------------- | -------------------------------------------------------- |
+| `pnpm dev:client`   | Start the client and shared-code watcher                 |
+| `pnpm dev:server`   | Start the backend and shared-code watcher                |
+| `pnpm build`        | Build shared code, then both apps                        |
+| `pnpm build:client` | Build shared code and the client                         |
+| `pnpm build:server` | Build shared code and the backend, including the tracker |
+| `pnpm test`         | Build shared code and run both test suites once          |
+| `pnpm typecheck`    | Build shared code and type-check both apps               |
+| `pnpm lint`         | Run the client's ESLint command                          |
+
+The root test command runs one package at a time with four workers to bound the
+memory used by the backend's in-memory Postgres tests.
+
+Package scripts also work inside their respective directories. Build `shared`
+first with `pnpm --filter @rybbit/shared build` when running a package directly
+from a fresh checkout. Add dependencies to the package that uses them, for example
+`pnpm --filter client add <package>` or `pnpm --filter rybbit-backend add <package>`.
+Commit the root `pnpm-lock.yaml`; do not generate npm lockfiles for these packages.
+Dependency overrides and allowed dependency build scripts live in
+`pnpm-workspace.yaml`.
+
+Both Dockerfiles use the repository root as their build context and require
+BuildKit (enabled by default in current Docker versions):
+
+```bash
+docker build -f client/Dockerfile \
+  --build-arg NEXT_PUBLIC_BACKEND_URL=https://analytics.example.com \
+  -t rybbit-client .
+docker build -f server/Dockerfile -t rybbit-backend .
+```
+
+Use your deployment's public backend URL. Docker Compose supplies this build
+argument from `BASE_URL`; local `.env` files are excluded from Docker images.
+
+The client image uses Next.js standalone output. The backend image uses
+`pnpm deploy --legacy --prod` to create a portable package while keeping normal
+workspace symlinks for local development. Its production dependencies include
+Drizzle Kit because container startup applies migrations. Database commands are
+explicit operations; installs, builds, and tests do not apply migrations.
+
 ---
 
 ## Join Our Community

README.md

@@ -42,6 +42,8 @@ There are two ways to start using Rybbit:
 
 📚 Explore our [documentation](https://rybbit.com/docs) to learn more about installation, configuration, and usage.
 
+To work on the client and backend locally, see the [pnpm workspace setup](CONTRIBUTE.md#local-development).
+
 <hr>
 
 ## ✨ Key Features

client/AGENTS.md

@@ -4,15 +4,17 @@ Guidance for agents working in the `client` package. Keep changes scoped to this
 
 ## Commands
 
-Run commands from `client/`.
-
-- `npm run dev` - start the Next.js dev server on port 3002.
-- `npm run build` - create a production build.
-- `npm run lint` - run ESLint.
-- `npx tsc --noEmit` - type-check without emitting files.
-- `npm run format` - run Prettier over client source files.
-- `npm run format:check` - check formatting.
-- `npm run extract` - extract next-intl messages.
+Run package commands from `client/`. Install dependencies at the repository
+root with `pnpm install`. The root `pnpm dev:client` and `pnpm build:client`
+commands build `shared` first; use them on a fresh checkout. Docs is separate.
+
+- `pnpm run dev` - start the Next.js dev server on port 3002.
+- `pnpm run build` - create a production build.
+- `pnpm run lint` - run ESLint.
+- `pnpm exec tsc --noEmit` - type-check without emitting files.
+- `pnpm run format` - run Prettier over client source files.
+- `pnpm run format:check` - check formatting.
+- `pnpm run extract` - extract next-intl messages.
 
 ## Stack
 
@@ -69,7 +71,7 @@ Use `buildApiParams()` for analytics requests that depend on time range, timezon
 
 - Use `useTranslations()` from next-intl for user-facing strings.
 - Keep locale keys consistent across `messages/*.json`.
-- Run `npm run extract` when adding or changing translatable UI text.
+- Run `pnpm run extract` when adding or changing translatable UI text.
 
 ## Conventions
 
@@ -83,7 +85,7 @@ Use `buildApiParams()` for analytics requests that depend on time range, timezon
 
 For most client changes, run:
 
-1. `npm run lint`
-2. `npx tsc --noEmit`
+1. `pnpm run lint`
+2. `pnpm exec tsc --noEmit`
 
-Run `npm run build` for route, config, bundling, or Next.js behavior changes.
+Run `pnpm run build` for route, config, bundling, or Next.js behavior changes.

client/CLAUDE.md

@@ -4,11 +4,14 @@ This file provides guidance to Claude Code when working in the `/client` directo
 
 ## Commands
 
-- `npm run dev` – Start dev server (Next.js + Turbopack, port 3002)
-- `npm run build` – Production build
-- `npm run lint` – ESLint
-- `npm run format` – Prettier format
-- `tsc --noEmit` – Type-check without emitting
+Install with `pnpm install` at the repository root. Root `pnpm dev:client` and
+`pnpm build:client` build `shared` first. Commands below run from `client/`.
+
+- `pnpm run dev` – Start dev server (Next.js + Turbopack, port 3002)
+- `pnpm run build` – Production build
+- `pnpm run lint` – ESLint
+- `pnpm run format` – Prettier format
+- `pnpm exec tsc --noEmit` – Type-check without emitting
 
 ## Stack