Skip to main content

​
Welcome Contributors

Thanks for contributing to the Stim Webtoys Library. This guide covers the current Bun-first workflow for humans and automation contributors.
This project uses Bun 1.3+ as the primary package manager and runtime. The repo declares [email protected] in package.json.

​
Quick Start

1

Install Bun

Install Bun 1.3+ from bun.sh. The repository is configured with [email protected] in package.json.
2

Clone the Repository

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

Install Dependencies

bun install
The repository tracks bun.lock for reproducible installs. Use bun install --frozen-lockfile in CI or other reproducible-install contexts where lockfile changes must be disallowed.
Bun does not automatically run prepare scripts, so the repo includes a postinstall hook that installs Husky when npm_config_user_agent starts with bun. If that step fails, fall back to bun x husky install.
4

Start the Dev Server

bun run dev
Open http://localhost:5173 in your browser to see the toys in action.

​
Quality Checks

Use these commands before opening a PR:

​
Full Gate for JS/TS Changes

bun run check
This runs Biome check + typecheck + tests. Required for all JS/TS edits.

​
Faster Iteration Gate

When you need quicker feedback during development: 
bun run check:quick
Runs Biome check + typecheck without tests.

​
Toy Registry/Docs Consistency Check

When adding or renaming toys: 
bun run check:toys

​
Run Targeted Tests

bun run test tests/path/to/spec.test.ts
Always use bun run test (not raw bun test) so preload/importmap flags from package.json are always applied.

​
Branches, Commits, and Pull Requests

​
Branch Strategy

  • Branch from main and keep PRs focused
  • Use descriptive branch names that reflect your changes

​
Commit Messages

  • Commit messages should be sentence case with no trailing period
  • Example: Add aurora painter toy with microphone support

​
PR Descriptions

Your PR description should include:
  • Short summary of the change
  • Explicit test command list showing what you ran
  • Explicit list of docs touched (or write None)

​
Documentation Expectations

When workflows or structure change, update docs in the same PR:
  • Follow docs/DOCS_MAINTENANCE.md as the canonical docs synchronization contract
  • Treat docs/README.md as the canonical docs index and update it whenever docs are added, renamed, moved, or deleted

​
Toy-Specific Changes

For new or renamed toys, update all of the following together:
  • Toy implementation in assets/js/toys/
  • Toy metadata in assets/data/toys.json
  • Standalone page in toys/ for page-backed toys
  • docs/TOY_SCRIPT_INDEX.md and docs/toys.md
  • Tests in tests/ where behavior changed

​
Scaffold Helper

Use the scaffold helper to create new toys: 
bun run scripts/scaffold-toy.ts --slug my-toy --title "My Toy" --type module --with-test
This creates:
  • Starter module from toy development patterns
  • Metadata entry in assets/data/toys.json
  • Updates to docs/TOY_SCRIPT_INDEX.md
  • Optional minimal Bun spec

​
Choose Your Workflow Lane

Change typeMinimum checks before commitUsually add
Docs-only wording/link updatesProofread + command/path validationbun run check:quick when commands changed
JS/TS behavior changesbun run checkTargeted test run while iterating
Toy addition/rename/registration editsbun run check + bun run check:toysbun run health:toys and toy docs updates
SEO generation/check logic changesbun run check + bun run check:seobun run generate:seo to refresh artifacts
Deploy pipeline/workflow changesbun run check + local smoke (bun run dev:check)bun run pages:dev before deploy

​
Next Steps

Development Setup

Learn about the local development environment and commands

Code Quality

Explore linting, formatting, and testing practices

Build docs developers (and LLMs) love

Get started for freeTalk to us