Devtools
@atolljs/devtools is the observability surface for atoll apps: a live dashboard of every pool, worker, and island, plus task waterfalls, network traffic, shared-memory writes, and heap sampling. In the browser it needs no backend: events travel over a same-origin BroadcastChannel to a dashboard the vite plugin serves on your app's own origin.
npm install @atolljs/devtoolsOr let the CLI do both steps : atoll add devtools installs the package and writes the init module for your host (browser, Node, or the Angular variant).
Enable it
import { initDevtools } from '@atolljs/devtools';
initDevtools({ session: { name: 'my-app', framework: 'react' } });framework is optional: it puts your shell's mark on the app map's main-thread hub. Name your worker clients too (connectWorker({ name: 'search' })): the name becomes the runner's id on the map, search-w for one dedicated worker or search-p for a pool.
That's the whole setup, and it costs nothing until invited. initDevtools is a no-op unless the page was opened with ?__atoll_devtools in the URL. With the param it starts collecting events and mounts the floating overlay; without it no collection, no broadcast, no overlay, and workers install no probes.
my-app/?__atoll_devtools → devtools on
my-app/ → zero cost, nothing installedWhat you get
- The overlay flyout: a draggable, resizable panel anchored to a corner of your app. Its default tab is the app map: your session drawn as an atoll: main thread at the center, pools (P) inside, workers on the rim. A worker hosting one island is drawn as that island, its real framework mark; a worker shared by several islands is a ring holding one node per island; a plain worker is a W. Nested workers link back to the island that spawned them. Click any node to open its inspector; the other tabs carry compact versions of every table.
- The full page: open
/__atoll/on your dev server or built app (or full page ↗ from the flyout, which opens on the view you were looking at) for the complete dashboard: task waterfalls, main-thread jank, fetch inspection, live shared-memory values, the reactivity graph, audits, and the raw event log. - Live controls: the dashboard can talk back. Kill a worker, inject delays and failures into a pool, edit an island's props, set watchpoints on shared memory.
- Worker correlation for free: a fetch, a memory write, or a crash inside a worker is attributed to the exact worker that did it, with no devtools code in your worker files.
Try it here. Every live demo embedded in these docs runs with devtools on: look for the atoll devtools button in a demo's corner, click it, and the flyout opens the app map for that demo. The demo's ↗ link opens it full-page with devtools active too.
Options
| Option | Type | Notes |
|---|---|---|
enabled | boolean | Override the ?__atoll_devtools gate, force on or off |
overlay | boolean | object | Flyout, default on in a browser; false to skip it |
overlay.position | string | 'topleft' | 'topcenter' | 'topright' | 'bottomleft' | 'bottomcenter' | 'bottomright', default 'bottomright' |
overlay.width / height | number | Initial flyout size, default 760×580 |
overlay.src | string | Dashboard URL the flyout iframes, default /__atoll/?mini=1 |
overlay.startOpen | boolean | Start expanded, default: the remembered state, else collapsed |
overlay.persist | boolean | string | Remember position, size and open state in localStorage, default on; a string is the storage key |
overlay.hotkey | string | false | Shortcut that toggles the flyout, default 'Alt+Shift+D' |
session.name | string | Session label shown in the dashboard |
session.framework | string | Your shell's framework ('react', 'vue', 'svelte', 'solid', 'angular', …), drawn on the app map's main-thread hub |
transport | 'auto' | 'broadcast' | 'websocket' | Default 'auto', BroadcastChannel in a browser, WebSocket elsewhere |
url | string | Aggregate server address, implies the WebSocket transport |
network | boolean | Wrap fetch() to log requests, default on |
memory | boolean | Sample JS heap, default on |
jank | boolean | Report long frames and a once-a-second frame rate from the browser main thread, default on |
connectDevtools takes the same session, transport, url, network, memory and jank options, without the URL gate or the overlay.
initDevtools({
session: { name: 'my-app' },
overlay: { position: 'topleft' },
});A tour of the views
Every view opens with a one-line note on what it shows and what feeds it. When several sessions are connected, views follow the session selected in the sidebar.
- Dashboard: the app map over four tabs. Overview has KPI cards, a per-second task throughput chart, and an attention feed of respawns, worker errors and failed tasks. Pools, Workers and Islands are the entity tables. Clicking a worker opens the worker inspector (its own task lane, heap chart, fetches and errors). Clicking an island opens the island inspector with three tabs: Elements (the island's real DOM tree; hover a node to outline it in your page), Props (every props change, diffed against the previous one) and Events (what the island emitted, with payloads).
- Tasks: a waterfall of every task call per worker slot (queue wait, then run, colored by outcome) and per-task aggregates; click a task to drill in.
- Performance: main-thread long frames with their slowest scripts, frame rate over the last 60 seconds, and message cost: the estimated size of task arguments, task results, and island op batches crossing
postMessage. While the tab is hidden, only frames with at least 100ms of script are kept; they're drawn gray as background work and don't count as jank. - Network: per-second channel traffic plus a log of real
fetch()calls from the main thread and workers; click one for headers, body previews, and a timing breakdown. - Memory: Values shows your shared-memory fields live, with snapshots to diff against and watchpoints. Shared-memory writes shows write rates per field and which worker wrote last. JS heap charts heap per session and per context.
- Reactivity: a graph from each shared-memory field through the watchers that cross threads to the slices and effects that read it, one lane per thread.
- Audits: live recommendations (oversized messages and island batches, saturated, idle or oversized pools, main-thread blocking, heavy work while the tab is hidden, low frame rate, task errors, timeouts and queue-full rejections, crash loops, heap pressure, shared-memory write storms, slow or failing requests, pools spawned before devtools, untagged islands, islands on a page that isn't cross-origin isolated), each with the evidence, a fix, and links to the entities involved. Mute a rule you don't care about.
- Log: the raw event stream with text, session and event-type filters, including atoll's own log lines at the level set with
setLogLevel.
Live controls
The worker and island inspectors carry controls that run inside your app. They are available while the session is live and the app has the matching command registered; a disabled control's tooltip says why.
- Kill worker: crashes the worker through its real crash path. In-flight calls reject with
WorkerCrashedErrorand the worker respawns if the client allows it: an easy way to test your recovery code. - Chaos: add a delay before every call, fail a share of calls (
chaos: injected failure), or time out a share of them through the real timeout path. It applies to the whole client until you clear it. - Edit props: edit an island's props as JSON and apply them. Callbacks appear as
"[fn]"; leave the placeholder and the original callback stays wired. - Push / Poll: switch an island's transport mode.
- Watchpoints (Memory › Values): pick a field and a rule (
change,> n,< n,>= n,<= n,== v,!= v) and every matching write is logged with its value. Writes from workers are checked when the main thread sees the change, so a fast burst reports its latest value.
Pools and islands started inside another worker show up everywhere but can't be controlled: their handles live in that worker.
Browser Performance panel
With devtools on, atoll also records User Timing measures, so a Chrome Performance recording shows its work in an atoll track group next to your frames: atoll task <taskId> on the main thread (one track per worker client), atoll run <taskId> inside the worker, and atoll replay <instance> for each island DOM update. The dashboard's flyout runs on your page's main thread, so its own rendering counts toward jank: measure with the full page open instead.
Record, export, replay
The dashboard keeps a rolling capture of recent events. ● Rec starts an explicit recording; Export downloads the recording (or the rolling capture) as JSON, just the selected session when one is selected. Import (or drop the file on the window) replays it: every view rebuilds as it was, with play, speed, and a scrubber. Replayed sessions are marked ⏺ and never send commands to a live app. Attach a recording to a bug report and anyone can open it in their own dashboard.
Keyboard and links
| Key | Action |
|---|---|
Ctrl+K / ⌘K | Command palette: jump to any view, island, worker, pool, or command |
g then a letter | Go to a view (d Dashboard, t Tasks, p Performance, n Network, m Memory, r Reactivity, a Audits, l Log) |
[ / ] | Previous / next sub-tab |
/ | Focus the view's filter box |
? | All shortcuts and what each view is for |
Alt+Shift+D | Show or hide the flyout, from your page or inside it |
The address hash tracks the current view and inspector, for example /__atoll/#/memory?session=…, so a reload or a shared link opens the same spot. In the flyout the hash never adds entries to your page's history.
Chrome DevTools panel
The same dashboard can live inside Chrome DevTools as an atoll panel for the inspected tab, so you don't need the flyout or a second tab. Updates are pushed as they happen: a small content script joins your page's devtools channel only while the panel is open, and stays idle otherwise.
Because that script is declared for every site, Chrome shows a Read and change all your data on all websites warning when you install the extension. It never reads the page itself, only the atoll devtools channel. Tabs that were already open when you installed it need a reload before the panel can connect.
The extension isn't on the Chrome Web Store yet: it's built from the atoll repository and loaded unpacked, as described in its README. It works in Chrome 114+ and other Chromium browsers such as Edge. Your app still needs devtools on (?__atoll_devtools with initDevtools()). Inside DevTools the palette also opens with Ctrl+Shift+K, since DevTools claims Ctrl+K. Sessions from the aggregate server and Node apps don't appear there; use the standalone dashboard for those.
Export to OpenTelemetry
Send the same telemetry to Jaeger, Tempo, Honeycomb, Grafana, or an OpenTelemetry Collector. The exporter speaks OTLP/HTTP JSON with no extra dependencies, and runs alongside the dashboard or on its own:
import { exportOtel } from '@atolljs/devtools/otel';
const otel = exportOtel({ endpoint: 'http://localhost:4318', serviceName: 'my-app' });
// on shutdown (Node): await otel.close();Task calls, island round trips, and fetches become spans; task outcomes, durations, queue wait, heap, long frames, and shared-memory writes become metrics; SDK logs and worker crashes become log records. To forward everything the aggregate server receives instead, start it with npx atoll-devtools --otlp http://localhost:4318. Each task call is its own trace: spans aren't parented to your app's own traces.
The aggregate server
BroadcastChannel scoping is structural: the local dashboard sees only your app's origin, which is the point. When you actually want several apps (or Node processes, which have no BroadcastChannel) in one view, opt into the standalone server:
npx atoll-devtools # dashboard at http://127.0.0.1:4780
// in each app:
connectDevtools({ url: 'ws://127.0.0.1:4780/events' });The aggregate adds what a page can't: cross-origin sessions in one map, and post-mortem retention: ended sessions stay inspectable for 30 minutes (pin one to keep it longer). The overlay still works; it always shows the local broadcast view.
Deploying in production
The dashboard is a static page, so there are two ways to put it in front of a deployed app:
Same-origin, zero backend. Ship the dashboard app as part of your site at /__atoll/. With the vite plugin this is automatic: when your app bundles @atolljs/devtools, vite build emits the dashboard into <outDir>/__atoll/, already set to listen on BroadcastChannel, so the flyout keeps working. Opt out, or force it on and move it:
atoll({ devtools: { build: false } }) // never ship /__atoll/
atoll({ devtools: { build: true, dir: 'debug/devtools' } })Without vite, copy node_modules/@atolljs/devtools/app/ to /__atoll/ yourself and add the flag before </head>:
<script>window.__ATOLL_TRANSPORT="broadcast"</script>Then ?__atoll_devtools and the overlay work exactly like development, and same-origin scoping is structural: the dashboard can only hear apps on your origin. Serve your app's COOP/COEP headers on /__atoll/ too (the vite dev server does this for you; a static host or vite preview needs them configured, the latter via preview.headers), or the flyout renders blank. If your app is served under a sub-path, point the flyout at it: overlay: { src: import.meta.env.BASE_URL + '__atoll/?mini=1' }.
Hosted aggregate. For cross-origin sessions and Node processes in one view, run the standalone server where you can reach it and point apps at it (url implies the WebSocket transport):
// devtools-server: behind your proxy's TLS + auth
import { createDevtoolsServer } from '@atolljs/devtools/server';
createDevtoolsServer({ host: '0.0.0.0', port: 4780 });
// in each deployed app:
initDevtools({
transport: 'websocket',
url: 'wss://devtools.internal.example.com/events',
session: { name: 'checkout-web' },
overlay: { src: 'https://devtools.internal.example.com/?mini=1' },
});The cross-origin overlay.src works because the aggregate dashboard reads its own server's /view socket, not the page's BroadcastChannel. Two cautions: the server ships with no authentication (loopback is the designed deployment: put auth and TLS in front when you host it), and ?__atoll_devtools still activates in production builds: under the aggregate topology, gate on enabled instead so visitors can't stream events to your server by appending the param.
Node.js apps
Node takes the WebSocket path automatically: no window, so no BroadcastChannel. The standalone server is the dashboard; the env var is the gate (there's no URL to carry the param):
// src/devtools.ts: a dedicated module, imported FIRST from
// your entry so devtools is on before any pool spawns.
import { initDevtools } from '@atolljs/devtools/node';
initDevtools({ session: { name: 'my-api' } });
// main.ts: import order matters: ESM evaluates imports before
// the entry body, and pools spawn inside sibling modules or
// NestFactory.create.
import './devtools';npx atoll-devtools # dashboard → http://127.0.0.1:4780
ATOLL_DEVTOOLS=1 npm run start # the app streams to itExpress, Fastify, Nest, or plain http: anything using atoll pools shows up as a runtime: 'node' session, with the same per-worker attribution (worker_threads workers forward events over their message channel just like browser workers). Any Node version works: the client uses the global WebSocket on ≥ 22 and falls back to a bundled dependency-free client below it. Heap charts populate via process.memoryUsage(): per worker, not just main.
Two things Node doesn't get: the overlay flyout and /__atoll/ (no page to host them, the server is the UI), and inbound-HTTP instrumentation, the network view covers the fetch() calls your app makes, not the requests it serves.
Notes
- Call
initDevtools()before pools spawn. Workers decide whether to report to devtools when they start: a worker spawned before devtools is on stays silent for its lifetime (the Pool spawned before devtools audit flags it). - Off means off. Without the URL param nothing is collected or broadcast, and workers install no fetch or memory probes, so there's no overhead on hot paths like shared-memory writes.
fetchonly. The network view coversfetch()on main thread and in workers; XHR isn't instrumented.- Per-worker heap is engine-dependent. It populates where the engine exposes memory APIs inside workers; the main-thread cluster breakdown uses
performance.measureUserAgentSpecificMemory. - Same cross-origin isolation rules as the rest of atoll: see Hosting & headers if the flyout renders blank behind strict COOP/COEP.