OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
ralph(M13-004): CI and docs on bun: setup-bun + bun install --frozen-lockfile in docker-build.yml, cache keyed on bun.lock, every pnpm instruction in CLAUDE.md / README / docs rewritten
ralphea8c2539de01
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.mdindex a9cf654c1..cf5295c5b 100644--- a/.claude/CLAUDE.md+++ b/.claude/CLAUDE.md@@ -6,34 +6,34 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co## Project Overview-Openpanel is an open-source web/product analytics platform (Mixpanel alternative). It's a **pnpm monorepo** with apps, packages, tooling, and SDKs.+Openpanel is an open-source web/product analytics platform (Mixpanel alternative). It's a **bun monorepo** with apps, packages, tooling, and SDKs.## Common Commands```bash# Development-pnpm dev # Run apps/api (ROLE=all, port 3333) + apps/start dashboard (port 3000) in parallel-pnpm dev:public # Run public/docs site only-pnpm dock:up / dock:down # Start/stop Docker (PostgreSQL, Redis, ClickHouse)+bun run dev # Run apps/api (ROLE=all, port 3333) + apps/start dashboard (port 3000) in parallel+bun run dev:public # Run public/docs site only+bun run dock:up / dock:down # Start/stop Docker (PostgreSQL, Redis, ClickHouse)# Code quality-pnpm check # Lint (Biome via Ultracite) + dependency-cruiser (check:deps)-pnpm fix # Auto-fix lint/format issues-pnpm typecheck # Typecheck all packages+bun run check # Lint (Biome via Ultracite) + dependency-cruiser (check:deps)+bun run fix # Auto-fix lint/format issues+bun run typecheck # Typecheck all packages# Testing-pnpm test # vitest run — packages/* and apps/* (excluding apps/start, packages/core)+bun run test # @openpanel/core, @openpanel/db, @openpanel/api and start's own suites, then root vitest for the restcd packages/core && bun test # core's own suite (ADR-010; bun:test cannot run under vitest)-pnpm vitest run <path> # Run a single vitest test file+bunx vitest run <path> # Run a single vitest test file# Database-pnpm codegen # Generate the Prisma client + core's geo/bot/ASN data-pnpm migrate # Run Prisma migrations (dev)-pnpm migrate:deploy # Deploy migrations (production - never run this)+bun run codegen # Generate the Prisma client + core's geo/bot/ASN data+bun run migrate # Run Prisma migrations (dev)+bun run migrate:deploy # Deploy migrations (production - never run this)# Docker utilities-pnpm dock:ch # ClickHouse CLI-pnpm dock:redis # Redis CLI+bun run dock:ch # ClickHouse CLI+bun run dock:redis # Redis CLI```## Architecturediff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.ymlindex 837f52d6b..d2b0de868 100644--- a/.github/workflows/docker-build.yml+++ b/.github/workflows/docker-build.yml@@ -84,30 +84,27 @@ jobs:# "webidl.util.markAsUncloneable is not a function".node-version-file: ".nvmrc"- - name: Install pnpm- uses: pnpm/action-setup@v4-- - name: Get pnpm store directory- shell: bash- run: |- echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV+ - name: Install bun+ uses: oven-sh/setup-bun@v2+ with:+ bun-version: 1.4.0- - name: Setup pnpm cache+ - name: Setup bun cacheuses: actions/cache@v3with:- path: ${{ env.STORE_PATH }}- key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}+ path: ~/.bun/install/cache+ key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}restore-keys: |- ${{ runner.os }}-pnpm-store-+ ${{ runner.os }}-bun-- name: Install dependencies- run: pnpm install+ run: bun install --frozen-lockfile- name: Codegen- run: pnpm codegen+ run: bun run codegen- name: Migrate database- run: pnpm migrate:deploy+ run: bun run migrate:deployenv:DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres?schema=publicDATABASE_URL_DIRECT: postgresql://postgres:postgres@localhost:5432/postgres?schema=public@@ -115,7 +112,7 @@ jobs:SELF_HOSTED: "true"- name: Run tests- run: pnpm test+ run: bun run testenv:DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres?schema=publicCLICKHOUSE_URL: http://localhost:8123/openpanel@@ -123,18 +120,18 @@ jobs:# ADR-008: dependency-cruiser is the second layer keeping the dissolved# validation/constants/common/json packages from growing back (M11-009).- # Run standalone, not via `pnpm run check`, because `check` also runs+ # Run standalone, not via `bun run check`, because `check` also runs# `ultracite check` over a repo that has never been bulk-formatted (see# .claude/CLAUDE.md) and is not green today for reasons unrelated to# dependency boundaries.- name: Check dependency boundaries- run: pnpm run check:deps+ run: bun run check:deps# - name: Run Biome- # run: pnpm lint+ # run: bun run lint# - name: Run TypeScript checks- # run: pnpm typecheck+ # run: bun run typecheckbuild-api:permissions:diff --git a/CLAUDE.md b/CLAUDE.mdindex d3fb55bdc..d04d5c843 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -14,7 +14,7 @@ and nothing here should reach it. Local Postgres / ClickHouse / Redis only.## Environment-- **No docker.** `pnpm dock:up` will fail. Postgres (5432), Redis (6379) and+- **No docker.** `bun run dock:up` will fail. Postgres (5432), Redis (6379) andClickHouse (8123) are already running on localhost, started by another user.Do not try to start, stop or install them.- **No sudo.** Anything needing root is a human task. Say so; do not attempt it.@@ -24,15 +24,15 @@ and nothing here should reach it. Local Postgres / ClickHouse / Redis only.## Commands```bash-pnpm install-pnpm codegen # prisma client; needs .env-pnpm run typecheck-pnpm check # ultracite + check:deps-pnpm test+bun install+bun run codegen # prisma client; needs .env+bun run typecheck+bun run check # ultracite + check:deps+bun run test```-`typecheck` and `test` fail until `.env` exists and `pnpm codegen` has run. If a-task depends on them and they are not ready, report `BLOCKED` rather than+`typecheck` and `test` fail until `.env` exists and `bun run codegen` has run.+If a task depends on them and they are not ready, report `BLOCKED` rather thaninventing a workaround.## ClickHousediff --git a/README.md b/README.mdindex 4a4c56bfb..f4e4adc10 100644--- a/README.md+++ b/README.md@@ -98,20 +98,19 @@ You can find the how to [here](https://openpanel.dev/docs/self-hosting/self-host- Docker- Docker Compose-- Node-- pnpm+- Bun### Start```bash-pnpm install+bun installcp .env.example .envecho "API_URL=http://localhost:3333" > apps/start/.env-pnpm dock:up-pnpm codegen-pnpm migrate:deploy # once to setup the db-pnpm dev+bun run dock:up+bun run codegen+bun run migrate:deploy # once to setup the db+bun run dev```You can now access the following:@@ -119,5 +118,5 @@ You can now access the following:- Dashboard: https://localhost:3000- API: https://api.localhost:3333- Bullboard (queue): http://localhost:9999-- `pnpm dock:ch` to access clickhouse terminal-- `pnpm dock:redis` to access redis terminal+- `bun run dock:ch` to access clickhouse terminal+- `bun run dock:redis` to access redis terminaldiff --git a/package.json b/package.jsonindex 322c629d5..3c40bb638 100644--- a/package.json+++ b/package.json@@ -5,6 +5,10 @@"private": true,"license": "MIT","author": "Carl-Gerhard Lindesvärd",+ "engines": {+ "bun": ">=1.4.0",+ "node": ">=24.19.0"+ },"workspaces": {"packages": ["apps/*",