Skip to main content

​
Toolchain Baseline

The Stim Webtoys Library uses a modern JavaScript toolchain:
  • Package manager/runtime: Bun 1.3+ ([email protected] pinned in package.json)
  • Build/dev server: Vite
  • Lint + format: Biome
  • Typecheck: TypeScript (tsc --noEmit)
  • Tests: Bun test with preload/importmap wiring
  • Deploy tooling: Wrangler for Cloudflare Pages

​
Prerequisites

Node is supported for fallback script execution (engines.node: ^22), but use Bun for installs and scripts.

​
Installing Bun

Install Bun 1.3 or higher from bun.sh: 
curl -fsSL https://bun.sh/install | bash
Verify your installation: 
bun --version

​
Installation

​
Clone and Install

git clone https://github.com/zz-plant/stims.git
cd stims
bun install

​
Installing Dependencies

# Regular install (updates lockfile if needed)
bun install
The repository tracks bun.lock. Use bun install --frozen-lockfile in CI or other reproducible-install contexts where lockfile changes must be disallowed.

​
Core Development Commands

​
Dev Server

# Start dev server
bun run dev
# Open http://localhost:5173
Use bun run dev:host when you need the server bound to all interfaces for mobile/LAN testing.

​
Building

# Create production build
bun run build

​
Build Output

The production build outputs to dist/. Preview the build on http://localhost:4173 using Vite’s preview server with the --host flag for LAN testing.

​
Development Workflows

​
Golden-Path Recipe: JS/TS Feature

1

Start Dev Server

bun run dev
2

Implement Change

Make your code changes while the dev server is running.
3

Run Quality Checks

bun run check
For faster iteration, use bun run check:quick until final validation.

​
Golden-Path Recipe: Add/Rename Toy

1

Start Dev Server

bun run dev
2

Implement Toy

Create or modify:
  • Toy implementation in assets/js/toys/
  • Toy metadata in assets/data/toys.json
  • Standalone page in toys/ for page-backed toys
  • Update docs: docs/TOY_DEVELOPMENT.md, docs/TOY_SCRIPT_INDEX.md, docs/toys.md
  • Tests in tests/ where behavior changed
3

Run Quality Checks

bun run check
bun run check:toys

​
Golden-Path Recipe: Pages Deployment

1

Quality Check

bun run check
2

Build

bun run build
3

Test Locally

bun run pages:dev
4

Deploy

bun run pages:deploy
Or use bun run pages:deploy:reuse when deploying a build you already verified.

​
Cloudflare Pages Workflows

# Build first, then run Wrangler Pages locally
bun run pages:dev

​
Troubleshooting

​
Microphone Permissions

  • If the browser denied microphone access, re-allow it via the address bar/site settings and click the start button again
  • Hard-refreshing the page will re-trigger the prompt on most browsers
  • Switch to demo audio if you keep seeing timeouts or “blocked” errors
  • Use the YouTube audio option on toy.html to paste a video link and capture tab audio

​
WebGPU Gating

  • A WebGPU fallback warning means the browser lacked a compatible adapter or device at startup
  • Toys will fall back to WebGL when possible
  • To force a retry after toggling a browser flag or switching GPUs, refresh the page
  • WebGPU-only toys (like multi) won’t run without WebGPU support

​
Dev-Server Hosting

Avoid loading toys over file://. The modules and JSON fetches require an HTTP server, so always use the dev server, preview server, or another static host.
  • Check the served port in the terminal output (Vite defaults to 5173; preview uses 4173)
  • Connect from other devices via http://<your-ip>:<port>

​
Common Issues

IssueSolution
bun run test behaves differently from bun testAlways use bun run test so preload/importmap flags apply
Formatting/lint driftRun bun run lint:fix followed by bun run format
Typecheck errors after dependency changesRerun bun install then bun run typecheck
check:toys failures after renamingVerify toy docs and metadata updates landed together
Pages command failures locallyVerify Wrangler auth/context and rerun bun run pages:dev
navigator.gpu missing during local testingRun bun run dev:webgpu so Chromium starts with WebGPU flags

​
Helpful Scripts Reference

Here are all the key scripts from package.json: 
bun run dev              # Start Vite dev server
bun run dev:host         # Start dev server on LAN
bun run dev:webgpu       # Launch with WebGPU flags
bun run dev:check        # Dev smoke check (no browser)

​
Repository Layout

Understand the project structure:
  • assets/js/toys/ - Individual toy implementations (e.g., cube-wave.ts, spiral-burst.ts)
  • assets/js/core/ - Rendering and input helpers used by multiple toys
  • assets/js/utils/ - Small utility modules supporting core helpers and toys
  • assets/css/ - Shared styling for HTML entry points
  • assets/data/ - Static data files consumed by toys (e.g., toys.json)
  • tests/ - Bun specs validating core behaviors
  • toy.html, brand.html, etc. - Entry points loading specific toys or collections
  • docs/ - Comprehensive project documentation
  • scripts/ - Build, deployment, and utility scripts

​
Next Steps

Code Quality

Learn about linting, formatting, and testing practices

Getting Started

Review the contribution guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us