Get started with Stim Webtoys
This guide will help you install dependencies, start the dev server, and open your first toy locally.The Stim Webtoys Library uses Bun 1.3+ as the package manager and runtime. Make sure you have Bun installed before proceeding.
Prerequisites
Before you begin, you’ll need:- Bun 1.3+: Install from bun.sh for the fastest install/test cycle
- A modern web browser: Chrome, Firefox, Edge, or Safari with WebGL support
- Git: To clone the repository
The repository records
[email protected] in package.json via the packageManager field for reproducible installs.Installation
Install dependencies
Install all required dependencies using Bun:The repository tracks
bun.lock for reproducible installs. If you need to respect the lockfile exactly (for CI or debugging):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.Start the dev server
Launch the development server:The server will start on
http://localhost:5173. Open this URL in your browser to see the toy library.Open a toy
Once the dev server is running, you can:
- Visit the landing page:
http://localhost:5173to browse all toys - Open a specific toy:
http://localhost:5173/toy.html?toy=spiral-burst - Try the toy index:
http://localhost:5173/toy.html
Your browser may prompt for microphone access. Grant permission to enable audio-reactive features, or click the demo audio option to explore without a mic.
Development workflows
Serve a production build
To test a production build locally:dist/ on port 4173 using Vite’s --host flag, so you can load the build from other devices on your LAN.
WebGPU development
If you need a WebGPU-focused local session:Mobile and LAN testing
To test on mobile devices or other machines on your network:http://<your-ip>:5173.
Common commands
Here are the most useful commands for day-to-day development:| Task | Command | Description |
|---|---|---|
| Start dev server | bun run dev | Launch Vite dev server on localhost |
| Start dev server (LAN) | bun run dev:host | Bind to all interfaces for device testing |
| Build for production | bun run build | Create optimized build in dist/ |
| Preview build | bun run preview | Serve production build locally |
| Run tests | bun run test | Execute Bun test suite |
| Lint code | bun run lint | Check code quality with Biome |
| Format code | bun run format | Auto-format with Biome |
| Type check | bun run typecheck | Run TypeScript type checker |
| Full quality check | bun run check | Run lint, typecheck, and tests |
All JavaScript dependencies are bundled locally with Vite, so everything works offline without hitting a CDN.
Troubleshooting
Microphone permissions
Browser denied microphone access
Browser denied microphone access
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.
Use demo audio instead
Use demo audio instead
Switch to demo audio if you keep seeing timeouts or “blocked” errors—the UI exposes a fallback button for a pre-mixed track so you can keep exploring without mic input.
YouTube audio option
YouTube audio option
Use the YouTube audio option on
toy.html to paste a video link and capture tab audio when you want a shared playback source instead of live mic input.WebGPU gating
- To force a retry (for example, after toggling a browser flag or switching GPUs), refresh the page—WebGPU detection resets and will attempt the adapter/device handshake again.
- WebGPU-only toys (like
multi) won’t run without WebGPU; expect them to stay idle or prompt you to pick another toy until the capability probe succeeds.
Module loading issues
Always usebun run dev, bun run preview, or another static host—never load toys over file://.
Next steps
Browse toys
Explore the full collection of toys and their features
Audio setup
Learn about microphone permissions and audio sources
Performance tips
Optimize quality settings for your device
Development guide
Set up your environment for contributing