Tutorial 7: Testing Your Instrument

This tutorial covers the full development loop — from running your instrument locally to seeing it live in Tango with hot-reload.

Prerequisites

• Your instrument scaffolded with bunx github:MartinGonzalez/tango-create (or manually)
• Tango desktop app running on port 4243
• Bun v1.0+

1. Start dev mode

From your instrument directory:

bun run dev

This does the following on startup:

1. Clears Bun’s module cache and runs bun install (ensures latest tango-api)
2. Builds frontend (src/index.tsx → dist/index.js) and backend if present
3. POSTs to http://localhost:4243 to register with the running Tango app
4. Watches src/ for changes — rebuilds and hot-reloads automatically

You should see output like:

Syncing dependencies...
Build complete in 42ms — frontend: ok, backend: ok
Connected to Tango — hot-reload active
Watching src/ for changes...

2. See it in Tango

Open the Tango app. Your instrument appears in the sidebar with a [dev] badge. Click it to see your panels render.

If Tango was already open, the instrument hot-reloads automatically — no restart needed.

3. Make changes

Edit any file in src/. The watcher picks up the change, rebuilds, and tells Tango to reload your instrument. The feedback loop is near-instant.

What triggers a rebuild

File changed	What happens
src/**/*.tsx, src/**/*.ts	Rebuild + hot-reload
package.json	Runs bun install → rebuild → hot-reload
bun.lock / bun.lockb	Runs bun install → rebuild → hot-reload

What does NOT trigger a rebuild

• Files outside src/ (unless package.json or lockfile)
• Files in node_modules/, dist/, or .git/

4. Validate your manifest

Before publishing, check that your manifest and project structure are correct:

bun run validate

This catches common issues: missing required fields, invalid permissions, broken entry points. Fix any errors before distributing your instrument.

5. Production build

To produce a one-off build without watching:

bun run build

Output lands in dist/. This is what gets loaded when your instrument is installed by other users.

Debugging tips

Instrument doesn’t appear in Tango

• Make sure Tango is running on port 4243
• Check that bun run dev connected successfully (look for “Connected to Tango” in output)
• Run bun run validate to check for manifest errors

Backend actions not working

• Confirm your package.json manifest has backendEntrypoint set
• Check that src/backend.ts exports a defineBackend default export
• Look at Tango’s console output for backend error logs

Hot-reload not picking up changes

• Make sure you’re editing files inside src/
• Check that the watcher is still running (hasn’t crashed)
• Try stopping and restarting bun run dev

Dependency issues

If you get import errors after updating tango-api:

rm -rf node_modules bun.lock bun.lockb
bun install
bun run dev

Updating tango-api

When a new tango-api version is released, update the tag in your package.json:

{
  "dependencies": {
    "tango-api": "github:MartinGonzalez/tango-api#v0.0.2-rc46"
  }
}

If bun dev is already running, it detects the package.json change, runs bun install, and hot-reloads automatically.

Next steps

Your instrument is working locally. To share it with others:

1. Push your instrument to a GitHub repository
2. Add a tango.json at the repo root pointing to your instrument
3. Users can add your repo as a source in Tango’s instrument browser and install it directly