Skip to content

development.md

Latest commit

 

History

History
138 lines (101 loc) · 3.7 KB

development.md

File metadata and controls

138 lines (101 loc) · 3.7 KB
Raw

Development Guide

This guide covers day-to-day Beacon development from a source checkout. For production deployment, see production.md. For dependency and toolchain update policy, see toolchain.md.

Prerequisites

  • Go 1.24.1 or newer
  • Node.js and npm for browser asset vendoring and Playwright tests
  • make
  • Optional: ClickHouse for integration and performance tests

See toolchain.md before changing pinned CI or release tooling.

Build From Source

git clone https://github.com/johnnygreco/beacon.git
cd beacon
make build
./bin/beacon up

Install the workspace binary locally:

make install-local INSTALL_DIR="$HOME/.local/bin"

Common Development Commands

Task Command
Build backend and frontend make build
Install local binary make install-local INSTALL_DIR="$HOME/.local/bin"
Run all Go tests make test
Run Go tests with race and coverage gates make test-cover
Run JavaScript lint and unit tests npm run test:frontend
Run fast backend benchmarks make perf-fast
Run performance benchmarks make perf-bench
Run browser performance tests make perf-browser
Run local performance lab smoke test make perf-lab-smoke
Run Playwright dashboard tests npm run test:e2e
Run accessibility tests npm run test:a11y
Run visual regression tests npm run test:visual
Run full release preflight make release-preflight
Publish a release make publish VERSION=x.y.z
Remove generated artifacts make clean

Most test commands keep Beacon user data intact. make clean removes build and test artifacts such as bin/, dist/, coverage files, Playwright reports, and test results.

Generated Files

Beacon embeds dashboard assets and configuration templates in the Go binary. Templ output is generated and checked into source control with the matching .templ files. Configuration template generated files are intentionally kept out of source control:

  • internal/config/templates/*.generated.go

Regenerate them with:

make generate

make build and make test run generation automatically. Use make generate-check before opening a PR to catch stale generated templates.

Coverage Gates

Run the Go coverage gate:

make test-cover

CI checks package thresholds from coverage.thresholds with scripts/check-coverage.sh. Update that file in the same change as any intentional threshold adjustment.

The generated profile can be inspected with:

go tool cover -html=coverage.txt

Frontend unit tests:

npm run test:frontend

ClickHouse Tests

Most Go tests do not need ClickHouse. Live ClickHouse integration and benchmark paths are opt-in:

beacon db up
BEACON_TEST_CLICKHOUSE=127.0.0.1:9000 go test ./internal/store ./internal/search ./internal/web
BEACON_TEST_CLICKHOUSE=127.0.0.1:9000 go test ./internal/perf -bench . -run '^$'

make perf-fast runs deterministic backend benchmarks without ClickHouse. make perf-lab-smoke installs the workspace binary, seeds a disposable ClickHouse database, serves Beacon locally, and writes reports under test-results/perf/lab/latest/.

make perf-fast
make perf-lab-smoke

Visual Checks

The dashboard has Playwright coverage for core views and screenshots.

npm run test:e2e
npm run test:visual
npm run test:visual -- --update-snapshots

Use visual updates only when intentional UI changes require new baselines.

Release Work

Release builds, checksums, install-script validation, and publishing steps live in release.md. The release sequence is:

make release-preflight
make publish VERSION=x.y.z