Skip to content

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.md
index 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 rest
cd 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
```
## Architecture
diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
index 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 cache
uses: actions/cache@v3
with:
- 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:deploy
env:
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres?schema=public
DATABASE_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 test
env:
DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres?schema=public
CLICKHOUSE_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 typecheck
build-api:
permissions:
diff --git a/CLAUDE.md b/CLAUDE.md
index 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) and
ClickHouse (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 than
inventing a workaround.
## ClickHouse
diff --git a/README.md b/README.md
index 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 install
cp .env.example .env
echo "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 terminal
diff --git a/package.json b/package.json
index 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/*",