Acme Widgets

Example website for Software Factory Intensive training. Live at https://bryanhirsch.github.io/acme-widgets-private/.

Quick Start

Prerequisites

• Bun >=1.2 — runtime + package manager + script runner. Vite (the dev server / bundler) is installed for you when you run bun install, so you don't need to install it globally.

Install Bun

See the official install guide: https://bun.sh/docs/installation.

# macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash

# macOS via Homebrew
brew install oven-sh/bun/bun

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Verify:

bun --version       # should print 1.2.x or newer

About Vite

You don't install Vite globally for this project — it ships as a dev dependency (see package.json) and is run via the bun run scripts below. If you want to read up on it: https://vitejs.dev/guide/.

Clone and run

git clone git@github.com:bryanhirsch/acme-widgets-private.git
cd acme-widgets-private
bun install          # installs Vite and all other deps
bun run dev          # http://localhost:5173

Other useful scripts:

bun run typecheck    # tsc --noEmit
bun run build        # production build to dist/ (also writes 404.html)
bun run preview      # serve the built output on http://localhost:4173
bun run test         # Vitest, one shot
bun run test:watch   # Vitest, watch mode
bun run test:e2e     # Playwright (chromium); spins up `bun run preview`

Stack

TypeScript + React 19 + Vite 6 + Tailwind v4 + React Router v7, hosted on GitHub Pages, CI on GitHub Actions. See docs/current/STACK.md for as-built versions and conventions, and docs/decision-records/0001.ADR.TECH_STACK.md for the decision record.

Repo layout

• docs/current/ — what is true on main right now.
• docs/decision-records/ — frozen ADRs.
• docs/future/ — proposed changes drafted as ADRs.
• src/ — application source. pages/ contains the three routes; components/ contains shared chrome and the 15 widget presets; lib/widgets.ts is the CSV parser + cache.
• e2e/ — Playwright specs.
• public/data/widgets.csv — last-resort fallback for the catalog if the Google Sheet can't be reached. Editing this file does not change the live site; see below.

Editing the catalog

Widget data (prices, stock counts, descriptions) lives in a Google Sheet, not in this repo. Producers and employees edit the sheet directly; changes appear on the live site within a few minutes — no PR, no deploy.

See docs/current/EDITING_THE_CATALOG.md for the sheet location and editing rules. The architecture choice is captured in docs/decision-records/0002.ADR.DYNAMIC_WIDGET_CATALOG.md.