This tutorial walks through the smallest useful end-to-end workflow for the current JavaScript runtime: write a script, run it through the live runner, press hardware controls, and watch the retained UI update on the device.

The important idea is that your script does not talk to the serial transport directly. It mutates state and retained UI objects, and the Go runtime owns rendering, flushing, and pacing. This layering exists because the Loupedeck Live transport is sensitive to timing and framing — letting JavaScript own the writer would recreate the exact problems the Go refactor was built to remove.

What you'll build

You will build a tiny page with four tiles:

• a title tile
• a live counter tile
• a hint tile
• an exit hint tile

Button1 increments the counter. The Circle button still exits the runner, which makes the example easy to start and stop.

Prerequisites

Before you start, make sure the hardware and repository state are sane. The live runner expects a real Loupedeck Live connected over USB serial, and stale processes can temporarily keep the serial device busy.

You need:

• this repository checked out
• a connected Loupedeck Live
• go test ./... passing in the repo
• no other process currently owning the device

A quick validation loop:

go test ./...

If the hardware is busy, stop older loupedeck run sessions or other example/dev-tool runs before continuing.

Step 1 — Write a minimal reactive script

The current runtime exposes modules through require(...). For a first script, the most useful pair is:

• require("loupedeck/state") for reactive values
• require("loupedeck/ui") for pages, tiles, and hardware events

Create a file such as /tmp/loupedeck-button1-counter.js with this content:

const state = require("loupedeck/state");
const ui = require("loupedeck/ui");

const count = state.signal(0);

ui.page("counter", page => {
  page.tile(0, 0, tile => {
    tile.text("BUTTON1");
  });

  page.tile(1, 0, tile => {
    tile.text(() => `COUNT ${count.get()}`);
  });

  page.tile(2, 0, tile => {
    tile.text("PRESS");
  });

  page.tile(3, 0, tile => {
    tile.text("CIRCLE EXIT");
  });
});

ui.onButton("Button1", () => {
  count.update(v => v + 1);
});

ui.show("counter");

Why this shape works:

• state.signal(0) creates the mutable counter state cell
• tile.text(() => ...) binds retained tile text to reactive state — when the signal changes, only that tile is re-rendered and sent to the hardware
• ui.onButton("Button1", ...) registers a hardware callback
• ui.show("counter") makes the page active so the renderer can flush it

If you skip ui.show(...), the page exists but nothing becomes active, so the live runner has no active page to flush.

Step 2 — Run the script on the device

The live hardware entry point is cmd/loupedeck, with the hardware runner exposed as the run subcommand. It loads the script into the owned goja runtime, attaches the host runtime to the deck, and flushes retained UI to the main display on a timer.

Run:

go run ./cmd/loupedeck run \
  --script /tmp/loupedeck-button1-counter.js \
  --duration 0 \
  --log-events

Why these flags matter:

• --script points at the JS file to execute
• --duration 0 means "run until interrupted" instead of timing out
• --log-events prints high-level button, touch, and knob events so you can verify what the hardware delivered

When the script starts cleanly, you should see initial draw activity and then a log line similar to:

INFO Loupedeck JS live runner started script=/tmp/loupedeck-button1-counter.js duration=0s flush_interval=16ms

Step 3 — Interact on the hardware

At this point, the top row of the main display should show the four tiles you defined. Press Button1 a few times.

What should happen in practice:

• the counter tile changes from COUNT 0 to COUNT 1, COUNT 2, and so on
• the log prints high-level button events
• the runner keeps going until you press Circle or interrupt it from the terminal

The important semantic detail is that the button callback does not mutate pixels directly. It mutates count, which re-runs the bound text closure, which marks the tile dirty, which the retained renderer flushes on the next tick. Only the changed tile is re-rendered — the other three tiles are untouched, saving bandwidth and CPU.

Step 4 — Stop the run cleanly

Press Circle to exit, or stop the process from the terminal with Ctrl-C.

If you want to keep Circle for your own script logic instead of exit behavior, disable the default exit hook:

go run ./cmd/loupedeck run \
  --script /tmp/loupedeck-button1-counter.js \
  --duration 0 \
  --exit-on-circle=false \
  --log-events

This matters for scripts like examples/js/02-counter-button.js, which intentionally use Circle as the application input.

Step 5 — Use the built-in example pack

Once the first custom script works, switch to the repository examples. These match the current implementation, and several have been validated on real hardware.

Examples in the repo:

Try the page-switcher example:

go run ./cmd/loupedeck run \
  --script ./examples/js/06-page-switcher.js \
  --duration 0 \
  --log-events

Step 6 — Custom pixel content with per-tile surfaces

The retained tile path (tile.text(), tile.icon()) handles text and simple labels. For anything custom — charts, meters, patterns, custom fonts — use a per-tile surface.

A per-tile surface is a 90×90 pixel buffer you draw into from JavaScript. When it changes, only that tile is re-rendered and sent to the hardware. This is much faster than redrawing the entire 360×270 display.

The tile.draw() shorthand

The easiest way to draw custom content on a tile is tile.draw(fn). It auto-creates a per-tile surface if needed and passes it to your drawing function:

const ui = require("loupedeck/ui");

ui.page("demo", page => {
  page.tile(0, 0, tile => {
    tile.draw(s => {
      s.clear(0);
      s.fillRect(0, 0, 90, 8, 100);  // accent bar
      s.text("HELLO", { x: 0, y: 30, width: 90, height: 20, center: true });
    });
  });
});

The tile.surface() pattern (for animation updates)

When you need to redraw the surface on each frame (e.g., animation), create the surface separately and keep a reference so you can modify it later:

const gfx = require("loupedeck/gfx");
const ui = require("loupedeck/ui");
const anim = require("loupedeck/anim");

const tileSurface = gfx.surface(90, 90);

ui.page("meter", page => {
  page.tile(0, 0, tile => {
    tile.surface(tileSurface);
  });
});

const level = state.signal(50);

// Redraw the tile surface when the level changes
anim.loop(100, () => {
  tileSurface.batch(() => {
    tileSurface.clear(0);
    const h = Math.round(level.get() * 0.8);
    tileSurface.fillRect(10, 80 - h, 70, h, 180);
  });
  // Only tile (0,0) is re-rendered — 32KB instead of 389KB
});

ui.show("meter");

Multi-line and wrapped text

Both tile.text() and surface.text() support newlines and word wrapping:

// Multi-line text with \n
tile.text("LINE 1\nLINE 2");

// Word-wrapped text (wraps to tile width)
tile.text("Very long label text", { wrap: true });

// Multi-line surface text with line gap
surface.text("ABOVE\nBELOW", {
  x: 0, y: 0, width: 90, center: true,
  lineGap: 4,  // 4 extra pixels between lines
});

// Word-wrapped surface text
surface.text("This is a very long label", {
  x: 4, y: 0, width: 90, center: true,
  wrapWidth: 82,  // wrap at 82 pixels (90 - 8 padding)
});

Key points about per-tile surfaces:

• Create a gfx.surface(90, 90) — the tile is 90×90 pixels
• Assign it with tile.surface(tileSurface), or use tile.draw(fn) for the shorthand
• Draw into it with surface.text(), surface.fillRect(), surface.line(), etc.
• Always use surface.batch(fn) when making multiple drawing calls — this coalesces change notifications so the tile is only re-rendered once
• When the surface changes, only that tile is re-rendered — other tiles are unaffected
• Use tile.invalidate() to explicitly mark a tile dirty (usually not needed — surface changes auto-mark the tile)

When to use per-tile vs. display-level surfaces:

How the runtime thinks about your script

The current JavaScript API is easiest to understand as a layered system:

script
-> require("loupedeck/ui"), require("loupedeck/state"), require("loupedeck/anim")
-> owned goja runtime
-> pure-Go reactive runtime and retained UI model
-> retained tile renderer (per-tile dirty tracking)
-> live runner flush loop
-> package-owned display/writer/transport stack
-> hardware

That layering is why the API feels high-level even though the device transport is fragile. JavaScript talks to state, pages, tiles, and animations. Go keeps ownership of transport and rendering policy.

Two rendering paths explained

The system has two rendering paths with different invalidation behavior:

Retained tile path (fast, per-tile):

signal.set(value) → reactive flush → tile.BindText() closure re-runs
→ tile.SetText() → markDirtyTile() → only that tile is dirty
→ renderer.Flush() → renderTile() → 90×90 pixels sent

Display-level surface path (flexible, full-display):

surface modification → markChanged() → display.markDirty()
→ renderer.Flush() → renderDisplay() → 360×270 pixels sent

Per-tile surface path (flexible + fast):

tileSurface modification → markChanged() → tile.markDirty()
→ renderer.Flush() → renderTile() → 90×90 pixels sent

For most scenes, the per-tile surface path gives you the custom drawing flexibility of surfaces with the per-tile efficiency of the retained path.

Complete example: animated pulse with per-tile surface

This example combines animation, reactive state, and per-tile surface drawing:

const state = require("loupedeck/state");
const ui = require("loupedeck/ui");
const gfx = require("loupedeck/gfx");
const anim = require("loupedeck/anim");
const easing = require("loupedeck/easing");

const pulse = state.signal(0);
const tileSurface = gfx.surface(90, 90);

ui.page("pulse-meter", page => {
  page.tile(0, 0, tile => {
    tile.surface(tileSurface);
  });
  page.tile(1, 0, tile => {
    tile.text(() => `${Math.round(easing.inOutCubic(pulse.get()) * 100)}%`);
  });
});

anim.loop(1200, t => {
  pulse.set(t);

  // Redraw the meter tile surface
  const level = easing.inOutCubic(t);
  const h = Math.round(level * 70);
  tileSurface.batch(() => {
    tileSurface.clear(0);
    tileSurface.fillRect(10, 80 - h, 70, h, 180);
    tileSurface.line(10, 10, 80, 10, 40);
  });
});

ui.show("pulse-meter");

Run it:

go run ./cmd/loupedeck run \
  --script /tmp/pulse-meter.js \
  --duration 10s \
  --log-events

Current limitations you should know up front

The current runtime is useful, but it is still the first real slice rather than the final platform.

Important current constraints:

• the JS-facing UI targets the main 4×3 tile grid and the left/right side displays
• tile.icon(...) currently stores a string and the placeholder renderer draws that string as text; it is not yet a full SVG/icon asset pipeline in the JS layer
• timers are host-owned internally, but they are not yet exposed as JS setTimeout / setInterval
• there is no JS assets module yet
• scripts do not get raw transport access, by design
• the goja VM is treated as single-threaded and all callbacks are serialized through the owner runner

These constraints are not accidents. They preserve the transport and rendering boundaries that keep the system stable.

Troubleshooting

See Also

• Loupedeck JavaScript runtime API reference — Detailed reference for modules, methods, events, and live-runner behavior
• examples/js/ — Built-in example scripts that match the current implementation
• cmd/loupedeck/main.go — The main CLI entry point
• cmd/loupedeck/cmds/run/command.go — The live hardware runner used in this tutorial
• runtime/js/module_ui/module.go — JS-facing page, tile, and event bindings
• runtime/js/module_gfx/module.go — JS-facing surface and font bindings
• runtime/js/module_state/module.go — JS-facing reactive state bindings