DEV Community: Ilia Kolebaev

I shipped one SDK for React, Vue, Angular, Svelte and vanilla JS. Each framework broke it differently

Ilia Kolebaev — Tue, 27 Oct 2026 13:00:00 +0000

I maintain an analytics SDK for Figma plugins. Plugin authors use whatever UI framework they like, so the SDK has five front doors: React, Vue, Angular, Svelte and plain TypeScript.

I did not want five SDKs. I wanted one, with five small wrappers. This post is about where the line between them ended up, and the one thing in each framework that would not fit behind it.

What the core owns

Everything that is hard lives in @tode-sdk/core:

a singleton that holds the config and sends events
a queue for events tracked before the config arrives
the handshake that fetches the config from the plugin's sandbox
a WebSocket that measures session length, with reconnect and backoff

None of that code imports a framework. It is two files, about 900 lines together, and its tests run without any framework installed.

What an adapter is allowed to do

Each adapter does the same four things:

Listen for the config message from the plugin.
Ask for the config, in case it was sent before the listener existed.
When the config arrives, take a handle on the shared session socket.
Expose two values, isReady and wsState, in the shape the framework expects, and clean up when the framework says so.

Step 4 is the only part that differs. Here is the Vue version of steps 1 to 3, which is the plainest of the five:

onMounted(() => {
  window.addEventListener('message', handleMessage);
  requestConfigFromPlugin();
});

onUnmounted(() => {
  window.removeEventListener('message', handleMessage);
  sessionSocket?.destroy();
});

The adapters run from 184 lines (Vue) to 336 (vanilla), comments included. If I find myself writing an if about reconnects inside an adapter, it is in the wrong package.

React: function identity and stale callbacks

The hook returns trackAction. People put it in dependency arrays:

const { trackAction } = useTode();

useEffect(() => {
  trackAction('settings_opened');
}, [trackAction]);

If the hook builds a new function on each render, that effect runs on each render, and the plugin sends an event every time anything changes on screen. So the functions are defined once at module level and the hook hands out the same ones every time:

const trackAction = (name, options) => tode.trackAction(name, options);

export function useTode() {
  // ...
  return { tode, isReady, wsState, trackAction, trackActionWithMetric };
}

The second React problem runs the other way. The hook accepts an onWebSocketStateChange callback, and people pass an inline arrow. The socket outlives renders, so it would keep calling the arrow from the first render forever, with the first render's state inside it. The hook reads the callback through a ref that it updates on every render:

const onStateChangeRef = useRef(onWebSocketStateChange);
onStateChangeRef.current = onWebSocketStateChange;

React is also the reason the socket is reference-counted in the core. Five components calling useTode() should be one session, so each hook instance takes a handle and the connection closes when the last handle is released.

Vue: nothing

ref, readonly, onMounted, onUnmounted. The Vue adapter is the shortest of the five and has no workaround in it. The only choice was to return the refs wrapped in readonly() so nobody sets isReady by hand.

Angular: two things

The first is the build. I build every package with tsup, and the Angular compiler is not part of that. A plain @Injectable({ providedIn: 'root' }) decorator, left uncompiled, needs @angular/compiler at runtime. Apps built ahead of time do not ship it, so the service fails to inject.

The fix is to write by hand what the decorator would have compiled to:

export class TodeService implements OnDestroy {
  static ɵprov = ɵɵdefineInjectable({
    token: TodeService,
    providedIn: 'root',
    factory: () => new TodeService(ɵɵinject(NgZone)),
  });
}

I am not happy about this one. The ɵ prefix is how Angular marks its private API. It works on the version I test against, and it is the part of the SDK I expect to break first.

The second thing is the zone. The session socket pings every 5 seconds. Inside Angular's zone, every one of those timers triggers change detection across the whole plugin UI, for a ping the UI does not care about. So the socket is created outside the zone, and only real state changes step back in:

this.ngZone.runOutsideAngular(() => {
  this.sessionSocket = acquireSessionSocket({
    onStateChange: (state) =>
      this.ngZone.run(() => this.wsStateSubject.next(state)),
  });
  this.sessionSocket.start();
});

Svelte: a store has no lifecycle

The Svelte adapter is a store, because a store works in any component and in plain .ts files. A store does not know when the component using it is destroyed, so the caller has to say so:

<script>
  import { createTodeStore } from '@tode-sdk/figma-svelte';
  import { onDestroy } from 'svelte';

  const todeStore = createTodeStore();
  onDestroy(() => todeStore.destroy());
</script>

That line is easy to forget. A forgotten destroy() means a ping timer and a reconnect loop that keep running. As a safety net the store also listens for beforeunload and destroys itself there.

Vanilla: the listener that arrives too late

The vanilla adapter is a class with on('ready', ...). It starts itself in the constructor by default, and that created a race with its own API:

const client = new TodeClient();
client.on('ready', () => { /* never called */ });

If the config was already available, ready fired inside the constructor, before the next line had a chance to subscribe. The start is now deferred by one microtask:

if (this.config.autoStart) {
  queueMicrotask(() => {
    if (!this._destroyed) this.start();
  });
}

One microtask is enough for the synchronous code after new to attach its listeners.

Releasing six packages

All six packages share one version number and go out together. The build runs core first and the adapters after it, since they compile against it.

Independent versions would let each adapter move at its own pace. I kept one number anyway. With one number, "which version are you on" has one answer, and nobody can combine a new adapter with an old core.

What I cannot promise

The peer dependency ranges are wide: React 16.8 and up, Vue 3, Angular 14 and up, Svelte 3 and up. Those floors come from the oldest API each adapter uses.

The tests only run against the versions pinned in each package, currently Svelte 5 and Angular 19. Nothing automated exercises the older versions inside those ranges. The README says so, and I would rather say it than claim support I have not checked.

Was the split worth it

A bug in the reconnect logic gets fixed once, in one file, for all five frameworks. That alone pays for the split.

The cost is that the core has to offer hooks that only one framework needs. Reference counting exists because of React. The logPrefix option exists so each adapter can label its own console output. The core is a little more general than any single adapter would want.

The code is MIT licensed: github.com/kolebayev/tode-sdk. The service it reports to is tode, analytics for Figma plugins.

If you maintain a library with adapters for several frameworks, I am curious which framework gave you the most trouble, and whether you version the packages together.

Why Google Analytics breaks inside a Figma plugin, and what I built instead

Ilia Kolebaev — Tue, 20 Oct 2026 13:00:00 +0000

I make Figma plugins. The numbers Figma gives me about them are installs and likes on the Community page. Neither one says whether anybody opened the plugin this week, or which of its buttons they pressed.

The usual answer on the web is Google Analytics. Paste the gtag snippet into a plugin's ui.html, open the console, and you get this:

SecurityError: Failed to read the 'cookie' property from 'Document':
Cookies are disabled inside 'data:' URLs.

The snippet is fine. The place it runs in is the problem, and that place turned out to be interesting enough that I ended up writing my own SDK for it. This post is about what I ran into.

A plugin is two programs

The first program is the main code, usually code.ts. It runs in a sandbox next to the document. It has the figma API and fetch. It has no DOM, no window and no document.

The second program is the UI. You pass an HTML string to figma.showUI(), and Figma loads that string into an iframe. The page gets a data: URL, so its origin is null.

Cookies, localStorage and IndexedDB all belong to an origin. A null origin owns none of them, and reading any of them throws. That is the error above.

The two programs cannot call each other. They talk through postMessage, and that is the only channel.

So the half that knows who the user is (the sandbox, through figma.currentUser) cannot see a click. The half that sees every click (the iframe) cannot remember anything and does not know who is clicking.

Web analytics assumes one page with a cookie jar. I had two halves and no jar.

Problem 1: the key is on one side, the buttons on the other

I wanted the developer to write the API key once. The sandbox is the right place for it, because the Figma data is there too:

// code.ts
import { tode } from '@tode-sdk/core';

figma.showUI(__html__);
await tode.init({ apiKey: 'your-api-key' });

init() reads the user id, the plugin id, the editor type (Figma, FigJam, Dev Mode, Slides) and posts all of it to the iframe in one message:

figma.ui.postMessage({ type: 'TODE_DATA', message: config });

The UI adapter listens for that message and configures itself. After that, both halves can send events with the same identity.

That is the happy path. It has a hole in it.

Problem 2: the first message gets lost

figma.showUI() returns before the iframe has loaded anything. If init() is fast and the UI bundle is slow, the config is posted to a page with no listener yet. Nobody hears it, the UI never becomes ready, and no error appears anywhere.

The same thing happens when a plugin closes its UI and calls showUI() again later. The new iframe starts empty.

The fix is a handshake that starts from the UI. When an adapter attaches its listener, it asks:

window.parent.postMessage(
  { pluginMessage: { type: 'TODE_UI_READY' }, pluginId: '*' },
  '*',
);

The sandbox answers by posting the config again. One detail matters here. Most plugins already set figma.ui.onmessage for their own messages, and assigning it a second time would overwrite their handler. figma.ui.on('message', ...) adds a listener next to it and leaves theirs alone, so the SDK uses that.

The plugin's own handler still receives the TODE_UI_READY message. It has to ignore message types it does not know, which a well-written handler does anyway.

Problem 3: events that fire before the SDK is ready

A common first event is "plugin opened". It fires on mount, before the config has crossed over from the sandbox.

My first version told developers to wrap every call in if (isReady). That is a rule people forget, and the event they lose is the most important one.

Now the SDK keeps early events in a queue with the time they happened, and sends them when the config arrives:

if (this._isReady && this._apiKey) {
  await this.send(event);
  return;
}
if (this._queue.length >= MAX_QUEUED_EVENTS) return; // 50
this._queue.push(event); // event.timestamp was set at call time

The cap is 50. If something calls trackAction in a loop while the SDK is not ready, I would rather drop events than grow an array forever inside someone else's plugin.

Problem 4: how long is a session

On a website, session length comes from page views with timestamps and a timeout. A plugin has no pages. It has a panel that is open for a while and then is gone.

I did not want to depend on an unload event firing in an iframe that Figma can remove at any moment. So I turned the question around. The UI opens a WebSocket when it becomes ready and holds it. The server writes down when the socket opened. When the socket closes, for any reason, the server writes one session row with the duration.

A closed panel, a closed tab and a crashed browser all look the same to the server: the socket is gone. No goodbye message is needed.

The client sends ping every 5 seconds. If the server hears nothing for 60 seconds, it ends the session itself, so a dead connection cannot inflate the numbers.

That covers a panel someone opens and closes. Three other cases needed more work.

The first is laptop sleep. People leave a plugin open, close the lid and come back hours later. The socket is dead and the panel is still on screen. The SDK reconnects with backoff (1s, 2s, 4s, capped at 30s) and never gives up while the UI is open. It also listens for the browser's online event and retries at once when the network is back.

The second follows from the first. Each reconnect is a new session row on the server. Every connection carries the same session_id, generated once per UI load, so the rows can be grouped later.

The third is React. Five components calling useTode() used to mean five sockets and five sessions for one person. The socket is now shared and reference-counted. The first caller opens it, and it closes when the last holder is gone.

Problem 5: analytics must never break the plugin

If my server is down, a designer's export button still has to work. So nothing in the SDK throws. init() and trackAction() catch everything and log to the console.

The sandbox made this harder than I expected. It has fetch, and it has no AbortController. Its fetch ignores signal. A request that hangs cannot be cancelled there, which means await tode.init() could block a plugin's startup.

The workaround is a race against a timer:

if (typeof AbortController === 'undefined') {
  const timeout = new Promise<never>((_, reject) => {
    timer = setTimeout(() => reject(new Error('Timed out')), 10_000);
  });
  return Promise.race([fetch(url, rest), timeout])
    .finally(() => clearTimeout(timer));
}

The request itself may still be hanging somewhere. The plugin has stopped waiting for it, and that is the part I care about.

Counting people without a cookie

A cookie exists on the web because the page does not know who you are. A plugin does. figma.currentUser.id is stable for a Figma account, and you get it by adding one line to the manifest:

{
  "permissions": ["currentuser"],
  "networkAccess": {
    "allowedDomains": [
      "https://processing.usetode.dev",
      "wss://processing.usetode.dev"
    ]
  }
}

That id is enough to tell a new user from a returning one, which is where retention comes from. The SDK sends the id and nothing else about the person: no name, no email, no file contents.

Country is looked up on the server from the request IP. The IP is not stored.

Without the currentuser permission, figma.currentUser is null. The SDK sends an empty value in that case and events still arrive. You lose unique users and keep everything else.

What it looks like from the plugin side

After all of that, the part a plugin developer writes is small:

import { useTode } from '@tode-sdk/figma-react';

function ExportButton() {
  const { trackAction, trackActionWithMetric } = useTode();

  const onExport = async () => {
    const layers = await exportSelection();
    trackAction('export_clicked');
    trackActionWithMetric('layers_exported', layers.length);
  };

  return <button onClick={onExport}>Export</button>;
}

There are adapters for React, Vue, Angular, Svelte and plain TypeScript. They are thin. The queue, the handshake and the socket all live in the core package, so I only fix each bug once.

What I have not solved

There is no way to learn from plugin code that an event failed to deliver. Failures go to console.error and that is all. I chose silence over callbacks because I did not want analytics error handling in people's plugins, and I am still not sure it was the right call.

Sessions need a UI. A plugin that runs a command with no panel has no iframe to hold a socket, so it gets events and no session length.

And a reconnect still shows up as a separate row on the server. The shared session_id makes it fixable, and I have not built the merge yet.

If you want to look at the code

The SDK is MIT licensed and lives at github.com/kolebayev/tode-sdk. The service behind it is tode. It has a free plan for one plugin, and the paid plans are how I cover the servers.

If you came here for the Google Analytics error and want the long answer, I wrote up what the Measurement Protocol can and cannot do inside a plugin.

I would like to hear from people who build extensions for other hosts, like VS Code, Chrome or Sketch. How do you find out whether anyone uses what you shipped?

I measure session length with a WebSocket that carries no data

Ilia Kolebaev — Tue, 13 Oct 2026 13:00:00 +0000

I run a small analytics service for Figma plugins. One of the numbers people want from it is session length: how long the plugin panel stayed open.

The answer I ended up with is a WebSocket that sends nothing useful. It opens when the panel opens. It closes when the panel closes. The server subtracts one timestamp from the other.

This post is the client, the server, and the places where that simple idea needed patching.

The two usual ways

The first is an unload event. When the page goes away, send one last request with the duration. The whole measurement then depends on that last request leaving a page that is being destroyed. My code runs in an iframe inside Figma, and Figma removes that iframe whenever the user closes the plugin. I did not want my numbers to depend on what happens in that moment.

The second is a heartbeat. The client POSTs "still here" every few seconds, and the server stores the latest time. This works. It also means the server never learns that a session ended. It only stops hearing about it, so you need a job that scans for sessions that went quiet and closes them.

A WebSocket gives the server the missing piece. When the connection ends, the server's read call returns an error. The end of the session becomes an event the server receives, and no job has to go looking for it.

The client

Here is the core of it, trimmed:

const sessionId =
  `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;

function connect() {
  const query = new URLSearchParams({ ...params, session_id: sessionId });
  const socket = new WebSocket(`${url}?${query}`);

  socket.onopen = () => {
    attempts = 0;
    pingTimer = setInterval(() => {
      if (socket.readyState === WebSocket.OPEN) socket.send('ping');
    }, 5000);
  };

  socket.onclose = () => {
    clearInterval(pingTimer);
    scheduleReconnect();
  };
}

Everything the server needs travels in the query string: the API key, the user id, the plugin id. The browser WebSocket constructor has no way to set request headers, so the query string is the only place for it.

The only message the client ever sends is the text ping, every 5 seconds.

The server

The server is Go. Each socket gets a goroutine, and the whole measurement is a defer:

func (s *Server) session(c *websocket.Conn, info KeyInfo, r *http.Request) {
    start := s.now()
    q := r.URL.Query()

    defer func() {
        c.Close(websocket.StatusNormalClosure, "")
        dur := float32(s.now().Sub(start).Seconds())
        e := EventFromQuery(q, start)
        e.SessionDuration = &dur
        s.writer.Enqueue(e)
    }()

    deadline := start.Add(s.opts.WSMax) // 24h
    for {
        idle := s.now().Add(s.opts.WSIdle) // 60s
        if deadline.Before(idle) {
            idle = deadline
        }
        ctx, cancel := context.WithDeadline(context.Background(), idle)
        typ, msg, err := c.Read(ctx)
        cancel()
        if err != nil {
            return
        }
        if typ == websocket.MessageText && string(msg) == "ping" {
            // answer "pong", return if the write fails
        }
    }
}

The loop has one exit, and that exit is "the read failed". A clean close fails the read. A dropped network fails the read after the idle deadline. A session that hits 24 hours fails the read on the hard deadline. All three land in the same defer, which writes one row with the start time and the duration.

Nothing is written when the socket opens. A session that is still running does not exist in the database yet.

Why ping at all

TCP does not tell you promptly that the other side vanished. If a laptop lid closes, no close frame is sent, and the server can go on believing the connection is alive for a long time.

So the client pings every 5 seconds, and the server gives up after 60 seconds of silence. Without this, one sleeping laptop would produce a session that lasts all night.

The cost is accuracy at the tail. A session that dies silently is counted until the idle deadline fires, so it comes out up to a minute longer than it was. A session that ends with a normal close is exact. I decided a minute of error on the rare case was acceptable. A shorter idle window would cut it, at the price of ending real sessions on a slow network.

Reconnecting

Connections drop for boring reasons: Wi-Fi changes, a proxy times out, I deploy a new server build. The client retries with exponential backoff.

const delay = Math.min(1000 * 2 ** attempts, 30_000);
attempts += 1;
setTimeout(connect, delay);

That is 1s, 2s, 4s, and so on up to 30s. It never stops trying while the panel is open. A plugin can sit open through hours of laptop sleep, and a retry limit would mean the rest of that session is never recorded.

Waiting out a 30 second backoff after the network returns is wasteful, so the client also listens for the browser's online event and reconnects at once:

window.addEventListener('online', () => {
  if (ws) return;
  clearTimeout(reconnectTimer);
  attempts = 0;
  connect();
});

The price of reconnecting

Every reconnect is a new socket, and the server writes one row per socket. One person with a flaky connection becomes five short sessions.

I have only half fixed this. The session_id at the top of the client code is generated once per page load and sent with every connection, so the rows that belong together can be found. The query that merges them is not written yet. Today the dashboard counts them separately.

Deploys

When I restart the server, every open socket would die without its defer finishing if the process exited first. So shutdown closes each connection on purpose and waits for the goroutines:

for _, c := range conns {
    c.Close(websocket.StatusGoingAway, "Server shutting down")
}
// wait up to 5 seconds for the session goroutines to write their rows

The sessions get recorded up to the moment of the deploy. The clients see a close, back off for a second and connect to the new process.

One socket per page

The SDK has a React hook. Call the hook in five components and a naive version opens five sockets, which the server counts as five sessions for one person.

The socket is shared and reference-counted. The first holder opens it. Each later holder gets a handle to the same connection. The connection closes when the last handle is released.

destroy() {
  current.holders -= 1;
  if (current.holders > 0) return;
  shared = null;
  current.socket.destroy();
}

A side effect I did not plan

An open socket is decent evidence that a real UI is open somewhere. The ingest server uses that. Events for a user id with no session seen in the last 30 minutes get a lower daily cap than events for a user with a live one. Someone replaying requests against the HTTP endpoint with a copied API key hits that cap quickly.

What this costs

One open connection per open panel, and one goroutine per connection on the server. For a tool people keep open while they work, the number of connections equals the number of people using it right now, which is also a number I want to see.

It needs a UI. A plugin that runs a command and exits has no page to hold a socket, so it gets no session length at all.

And it measures "the panel was open". Whether the person was looking at it is a different question that I do not try to answer.

Code

The client is in the open-source SDK: github.com/kolebayev/tode-sdk, file packages/core/src/sessionSocket.ts. The service is tode.

The first post in this series covers the rest of the SDK and why Google Analytics cannot run in a Figma plugin in the first place.

If you measure session length some other way, especially in an embedded context like an extension or a widget, I would like to know how you handle the session that never says goodbye.