I ran into this while building Temploracraft, a résumé tool that takes an uploaded document and turns it into structured data the application can edit.

The input is genuinely unpredictable: two-column PDFs, tables that aren't really tables, and dates written in about fourteen different formats. The output has to be strict, because every extracted field lands in a form that a person is going to look at. When the model gets a date wrong, the user notices in about two seconds.

This article is about the layer that sits between "the model returned some text" and "my application has data it can trust." It covers the three mechanisms for constraining output, why designing the schema first beats writing a longer prompt, how to build a retry loop that doesn't set money on fire, and what to do about the failures that no retry will ever fix.

Table of Contents

• Prerequisites

• Why Prompting for JSON Isn't Enough

• The Three Ways to Constrain Output

• Start with the Schema, Not the Prompt

• Validation Is Two Jobs, Not One

• Building a Retry Loop That Doesn't Burn Tokens

• Streaming Structured Output

• The Failures You Can't Retry Away

• What This Actually Costs

• When You Don't Need Any of This

• Wrapping Up

• References

Prerequisites

To follow along comfortably, you'll want a few things in place:

• Working knowledge of TypeScript: The examples use type inference and generics lightly, and you should be able to read a type annotation without pausing.

• You have called a language model API at least once: You don't need to be an expert, but you should know what a system prompt is and roughly what a token is.

• Familiarity with JSON Schema is helpful but not required: I explain the parts that matter as they come up.

• Node.js 18 or later if you want to run the examples, since they use the native fetch and async iterators.

The code samples use Zod for schema definition and the Anthropic SDK for model calls, but every technique here translates directly to other validation libraries and other providers. The ideas matter more than the specific packages.

Why Prompting for JSON Isn't Enough

The first instinct when you need structured data is to ask for it politely. You write something like "Respond with valid JSON matching this shape, and do not include any other text," you paste an example, and it works. It keeps working through development. It works in your demo.

The problem is that a language model generates one token at a time based on probability, and your instruction is only one influence among many. It competes with the model's training, the shape of the input document, and whatever the model produced in the preceding few hundred tokens. Most of the time your instruction wins. Occasionally it does not.

Here are failures I've actually collected from a production extraction pipeline, all from a model that was explicitly told to return strict JSON:

• The model wrapped the response in a Markdown code fence, despite being told twice not to.

• It returned "2019 - Present" as a single string where the schema defined separate startDate and endDate fields.

• It invented an endDate of "2024-12-31" for a role the document clearly marked as current.

• It returned the string "null" instead of an actual null.

• It emitted seven bullet points for a role where the schema set a maximum of five.

• It truncated mid-object because the response hit the output token limit.

Notice that these aren't all the same kind of failure. The code fence and the truncation are syntax problems, and you can often fix them locally without calling the model again. The merged date string and the extra bullets are schema problems, where the JSON parses fine but doesn't match the shape you need. The invented end date is a semantic problem, where the output is both valid JSON and schema-conformant but factually wrong about the source document.

Those three categories need three different responses, and conflating them is the most common architectural mistake I see in extraction code. The rest of this article is largely about separating them.

The Three Ways to Constrain Output

Before writing any validation code, it's worth understanding what the API itself can enforce for you. There are three mechanisms, and they give you meaningfully different guarantees.

JSON mode is the weakest of the three. You set a flag such as response_format: { type: "json_object" }, and the provider guarantees the response will be syntactically valid JSON. That's genuinely useful, because it eliminates the code fence and truncation problems in one move. What it doesn't do is guarantee anything about the shape. You can get valid JSON with the wrong keys, the wrong types, or a completely different structure than you asked for.

Tool calling is the mechanism I reach for most often. You describe a function with a JSON Schema for its parameters, then force the model to call it. The model returns arguments matching that schema rather than free text. Support is broad, the schema travels with the request so you're not duplicating it in the prompt, and providers tend to constrain the output more aggressively than they do in plain JSON mode.

Here's what that looks like with the Anthropic SDK:

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tools: [
    {
      name: "emit_resume",
      description: "Return the parsed resume as structured data.",
      input_schema: jsonSchema,
    },
  ],
  tool_choice: { type: "tool", name: "emit_resume" },
  messages: [{ role: "user", content: resumeText }],
});

const block = response.content.find((b) => b.type === "tool_use");
const candidate = block?.input;

The tool_choice field is the important part. Without it the model decides whether to call the tool, and sometimes it will just answer in prose instead. Forcing the specific tool removes that branch entirely.

Constrained decoding is the strongest option and the least widely available. Instead of asking the model to follow a schema, the runtime masks the token sampler at every step so that tokens which would produce invalid output can't be selected at all. Invalid output becomes impossible rather than unlikely.

OpenAI exposes a version of this through strict structured outputs, and if you run models locally you can use GBNF grammars in llama.cpp or a library such as Outlines.

The tradeoff is that constrained decoding can push the model into awkward corners. If the schema demands a field the document genuinely doesn't contain, the model can't decline, so it fills the slot with something. You've traded a parsing failure for a hallucination, which is harder to detect. I make required fields nullable for exactly this reason, which I'll come back to shortly.

My default is tool calling with a nullable-heavy schema, plus validation on top. That combination gives most of the benefit without the issues.

Start with the Schema, Not the Prompt

The instinct when output quality is poor is to write a longer prompt. More examples, more emphasis, and more capital letters. This helps a little and scales badly, because the prompt is prose and prose isn't enforceable.

A better approach is to treat the schema as the primary artifact and let everything else derive from it. Define it once, and use that single definition to generate the TypeScript type, the JSON Schema sent to the API, and the runtime validator. When the shape changes, all three change together, and there's no way for them to drift apart.

With Zod that looks like this:

import { z } from "zod";

const YearMonth = z
  .string()
  .regex(/^\d{4}-\d{2}$/, "Expected a YYYY-MM date");

const Role = z.object({
  company: z.string().min(1),
  title: z.string().min(1),
  startDate: YearMonth,
  endDate: YearMonth.nullable(),
  bullets: z.array(z.string().min(1)).min(1).max(5),
});

const Resume = z.object({
  name: z.string().min(1),
  email: z.string().email().nullable(),
  roles: z.array(Role),
});

export type Resume = z.infer<typeof Resume>;

Three details in there are doing real work.

The YearMonth regex is narrower than z.string(), and that narrowness is the point. A bare string field invites the model to return "January 2019" or "2019 - Present" or "01/2019", and all of those pass validation. Constraining the format at the schema level means the mismatch surfaces immediately instead of three layers deeper in your date-handling code.

The endDate field is nullable rather than optional. This is the single change that most improved extraction quality for me. An optional field lets the model quietly omit it, and you can't distinguish "the document did not say" from "the model forgot." A nullable field forces an explicit decision, and null is a meaningful answer that means the role is current.

The max(5) on bullets encodes a product constraint directly into the contract rather than trimming the array afterward. If the model exceeds it, you want to know, because it usually means the model is padding rather than extracting.

To send the schema to the API, derive the JSON Schema from the same definition:

import { zodToJsonSchema } from "zod-to-json-schema";

const jsonSchema = zodToJsonSchema(Resume, { target: "openApi3" });

One habit worth adopting: write a .describe() on any field where the name alone is ambiguous. Those descriptions end up in the JSON Schema, which means they reach the model as part of the tool definition, which means they function as targeted, structured prompt instructions attached to exactly the field they concern.

const Role = z.object({
  company: z.string().min(1),
  title: z.string().min(1).describe("The person's job title, not the team name"),
  startDate: YearMonth,
  endDate: YearMonth.nullable().describe("null if this role is current"),
  bullets: z
    .array(z.string().min(1))
    .min(1)
    .max(5)
    .describe("Verbatim from the document. Do not rewrite or summarise."),
});

That last description eliminated an entire class of failure for me, where the model would helpfully improve the wording of a person's own bullet points.

Validation Is Two Jobs, Not One

Once the response comes back, it's tempting to run schema.parse() and consider the job done. Zod will tell you whether the shape is right, and if it is, you move on.

But shape validation and semantic validation are different jobs, and only the first one is free. Zod can tell you that endDate is a string matching YYYY-MM. It can't tell you that the end date falls before the start date, or that the date is in the future, or that a role listed as current also has an end date. Those are all schema-valid and all wrong.

So run two passes. The first is structural and comes from the schema. The second is a plain function that encodes what you know about the domain:

function findSemanticProblems(resume: Resume): string[] {
  const problems: string[] = [];
  const currentMonth = new Date().toISOString().slice(0, 7);

  for (const role of resume.roles) {
    if (role.startDate > currentMonth) {
      problems.push(`${role.company}: start date is in the future`);
    }
    if (role.endDate && role.endDate < role.startDate) {
      problems.push(`${role.company}: end date precedes start date`);
    }
  }

  const currentRoles = resume.roles.filter((r) => r.endDate === null);
  if (currentRoles.length > 1) {
    problems.push("More than one role is marked as current");
  }

  return problems;
}

None of this is clever code, and that's rather the point. It's ordinary business logic that happens to be checking a model's work rather than a user's. Write it as you discover failures, and treat each new check as a permanent regression test for a mistake the model made once.

There's a useful asymmetry here. Semantic problems are often better surfaced to the user than retried, because the model frequently can't do better with the information available. If a document genuinely lists two current roles, that's what the document says, and asking the model again won't change it.

Building a Retry Loop That Doesn't Burn Tokens

When validation fails, the naïve fix is to call the model again with the same prompt and hope for a different sample. That works often enough to feel reasonable and is wasteful enough to notice on the bill, because you're paying full input cost for a request that has already mostly succeeded.

Two changes make a large difference.

The first is to attempt a local repair before spending anything. A meaningful share of failures are cosmetic, and you can fix them with string handling:

function salvage(raw: string): string {
  let text = raw.trim();

  // Strip a Markdown fence the model added despite instructions.
  const fenced = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
  if (fenced) text = fenced[1];

  // Drop any prose before the first brace or after the last one.
  const start = text.indexOf("{");
  const end = text.lastIndexOf("}");
  if (start !== -1 && end > start) text = text.slice(start, end + 1);

  return text;
}

The second is that when you do call the model again, you should send a repair request rather than a fresh attempt. Include the original prompt, the output that failed, and the specific validation errors. The model has already done the hard extraction work, and you're asking it to fix a small number of named problems rather than start over. Repairs converge faster and produce shorter outputs, which means they cost less.

async function requestRepair(
  originalPrompt: string,
  badOutput: string,
  error: z.ZodError,
): Promise<string> {
  const issues = error.issues
    .map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
    .join("\n");

  const response = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 4096,
    messages: [
      { role: "user", content: originalPrompt },
      { role: "assistant", content: badOutput },
      {
        role: "user",
        content:
          `That output failed validation with these problems:\n${issues}\n\n` +
          `Return the corrected JSON only. Keep everything that was already correct.`,
      },
    ],
  });

  return response.content[0].type === "text" ? response.content[0].text : "";
}

Putting it together, the full loop separates the failure classes and caps the spend:

type Outcome<T> =
  | { ok: true; value: T; attempts: number }
  | { ok: false; error: string; attempts: number };

async function extract<T>(
  schema: z.ZodType<T>,
  prompt: string,
  maxAttempts = 3,
): Promise<Outcome<T>> {
  let lastRaw = "";
  let lastError: z.ZodError | null = null;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    lastRaw =
      attempt === 1
        ? await callModel(prompt)
        : await requestRepair(prompt, lastRaw, lastError!);

    let candidate: unknown;
    try {
      candidate = JSON.parse(salvage(lastRaw));
    } catch {
      continue; // Syntax failure. Try again without a schema error to report.
    }

    const result = schema.safeParse(candidate);
    if (result.success) {
      return { ok: true, value: result.data, attempts: attempt };
    }
    lastError = result.error;
  }

  return {
    ok: false,
    error: lastError?.message ?? "Output was never parseable",
    attempts: maxAttempts,
  };
}

Two things about this loop are deliberate. It returns the attempt count, which you should log, because attempts per success is the single most useful health metric for an extraction pipeline. And it caps attempts at three. If three tries haven't produced valid output, a fourth rarely helps, and by then you're better off degrading gracefully than continuing to pay.

One more distinction worth respecting: a rate limit error and a schema validation error aren't the same failure and shouldn't share a retry policy. Rate limits want exponential backoff, because the problem is timing. Schema failures want an immediate repair request, because the problem is content, and waiting changes nothing.

Streaming Structured Output

Streaming and structured output pull against each other. Streaming exists so the user sees progress before the response finishes, but you can't parse a JSON object until the closing brace arrives. If your extraction takes twelve seconds, the best options are to show a spinner for twelve seconds or find a way to stream something meaningful.

There are two reasonable approaches.

The first is a partial JSON parser, which takes an incomplete string and returns the largest valid structure it can infer, closing open braces and dropping the trailing incomplete value. Libraries such as best-effort-json-parser do this. It works, and it's the right choice when the output is genuinely one large object. The cost is that intermediate states can be misleading, because a field can appear with a truncated value that looks complete.

The second approach, which I prefer when the output is a list, is to change the output format so that streaming is natural. Instead of asking for one array of objects, ask for one object per line. Each line is independently parseable, so you can validate and emit items the moment they complete:

const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  messages: [{ role: "user", content: prompt }],
});

let buffer = "";

for await (const event of stream) {
  if (event.type !== "content_block_delta") continue;
  buffer += event.delta.text ?? "";

  const lines = buffer.split("\n");
  buffer = lines.pop() ?? ""; // Keep the incomplete tail for the next chunk.

  for (const line of lines) {
    if (!line.trim()) continue;

    try {
      const parsed = Role.safeParse(JSON.parse(line));
      if (parsed.success) onRole(parsed.data);
    } catch {
      // A malformed line is dropped rather than failing the whole stream.
    }
  }
}

The buffer handling is the part that people get wrong. Network chunks don't align with line boundaries, so a chunk will frequently end mid-object. Popping the final element back into the buffer and carrying it forward is what makes the loop correct.

This pattern gives you per-item validation for free, which is a real advantage over parsing one large object. One bad item doesn't invalidate the rest of the extraction.

The Failures You Can't Retry Away

Everything so far assumes the model can produce the right answer if you ask correctly. Some failures don't work that way, and treating them as retry candidates wastes money while producing confidently wrong data.

The most important of these is extraction from something the source doesn't contain. If a résumé genuinely has no email address and your schema requires one, the model will produce something plausible.

Retrying produces a different plausible thing. This is the failure mode that constrained decoding makes worse rather than better, because the grammar guarantees a well-formed value in a slot that should've been empty. The fix is at the schema level, which is why nearly every field in my extraction schemas is nullable.

Ambiguity in the source is a similar case. When a document lists a date range next to two different job titles, there's no correct extraction, only a guess. Retrying gives you a different guess with the same confidence. These situations want a confidence signal in the schema and a review step in the interface, not another API call.

Then there's silent truncation. If the response hits the output token limit mid-object, you get syntactically broken JSON, and a naïve retry loop treats it as a transient parse failure and tries again with the same limit, failing identically each time. Check the stop reason on the response. If the model stopped because it ran out of tokens, retrying without raising the limit or splitting the input is guaranteed to fail again.

The general principle is that your retry policy should ask what kind of failure this is before deciding whether repeating the call could possibly help.

What This Actually Costs

Every layer above has a price, and it's worth measuring rather than assuming.

The main figure to track is attempts per successful extraction. Log it on every request and watch the p95 rather than the mean, because the mean hides the tail where the money goes. When a schema change causes a quality regression, this number moves before anything else does.

Prompt caching matters more here than in most workloads. Extraction prompts are unusually cache-friendly because the system prompt, the schema, and any few-shot examples are byte-identical on every request, and only the document changes.

On a pipeline where the schema and instructions ran to a couple of thousand tokens, moving that block into a cached prefix cut input cost substantially, and the saving compounds with every retry because repairs re-send the same prefix.

Repair requests are cheaper than fresh attempts for a reason worth understanding. The input grows, since you're now sending the original prompt plus the failed output plus the error list. But the output shrinks considerably, because the model is correcting a handful of fields rather than generating the full document again. Output tokens are the expensive direction on most providers, so the trade is usually favourable.

Two other things are worth instrumenting from the start: the distribution of validation error paths, which tells you exactly which schema fields are causing trouble and is far more actionable than an overall failure rate, and your local-repair hit rate, since if salvage() is fixing a large fraction of responses you have a prompt problem you can solve once rather than paying for repeatedly.

When You Don't Need Any of This

This machinery earns its place in a specific set of circumstances, and it's genuinely overkill outside them.

If the model's output goes straight to a human who will read it as prose, you don't need structured output at all. A chat interface, a summary, or a draft email all have a person as the validator, and adding a schema in front of that just constrains the model for no benefit.

If you're extracting one or two fields rather than a document's worth, a well-targeted prompt with a light safeParse and a single retry will serve you fine. The retry loop, semantic validation layer, and streaming parser are answers to problems that appear at scale and with schema complexity.

If your volume is low and a human reviews every result anyway, the validation layer is duplicating work someone is already doing. Surface the raw output, let the reviewer correct it, and spend the engineering time elsewhere.

And if you're still exploring what the feature should be, resist building this early. The schema is the most expensive thing to change once extraction code, validation rules, and stored data all depend on it. Prototype loosely, learn what fields you actually need, and tighten afterwards.

The safest rule is to start with a schema and safeParse, and add each subsequent layer only when a real failure justifies it. Every technique in this article came from a specific production incident rather than from a design document.

Wrapping Up

The gap between a working demo and a reliable feature is almost entirely in this layer. The model isn't the hard part any more, and the prompt isn't usually the hard part either. The hard part is deciding what you'll accept, detecting when you didn't get it, and responding sensibly when that happens.

Three ideas carry most of the weight:

1. The schema is the contract, and everything derives from it. One definition producing your type, your API schema, and your validator means those three can never drift apart.

2. Separate syntax failures, schema failures, and semantic failures. They have different causes and different fixes, and a retry loop that treats them identically will waste money on problems that repeating the call can't solve.

3. Make fields nullable rather than optional. Forcing the model to say "this was not present" rather than allowing it to quietly omit the field converts a whole class of silent hallucination into an explicit, checkable value.

Get those right and the rest is ordinary engineering. You're writing validation code and retry logic, which developers have been doing against unreliable inputs for decades. A language model is just a new kind of unreliable input, and it responds well to the same discipline.

References

• Zod: the schema library used throughout these examples.

• zod-to-json-schema: converts a Zod schema into the JSON Schema an API expects.

• Anthropic tool use documentation: forcing structured arguments through a tool definition.

• OpenAI structured outputs: strict schema conformance through constrained decoding.

• Outlines: grammar-constrained generation for locally hosted models.

• best-effort-json-parser: parsing incomplete JSON while a response is still streaming.

Try forcing too much through it, and either the lawn floods (your DOM) or the pipe bursts (your app).

There's a second observation that pairs with the first. Your laptop has 8 to 16 CPU cores. Your React app uses 1 of them, almost always. The main thread handles JavaScript, the DOM, layout, and paint setup. The other cores sit idle while the main thread struggles to keep a 60fps frame budget.

Both problems have the same shape: you need to keep React out of the hot path, and you need to use more than one thread. The patterns that get you there also happen to be the patterns behind Figma's canvas engine, Bloomberg's trading dashboards, and every biosignal viewer you've seen.

In one project, I had to visualise 19 EEG (brainwave) channels, each sending about 1,000 data points per second. That's almost 19,000 updates per second. If you feed all of that directly into React, the UI doesn't just slow down. It faints dramatically.

This article is the end-to-end architecture I landed on: the ring buffers, workers, shared memory, off-main rendering, and specific patterns that hold up under sustained multi-hour load.

Table of Contents

• Prerequisites

• Who's Already Doing This?

• The 1kHz Math

• Where it Usually Goes Wrong

• The Mental Model: Air Traffic Control Plus a Kitchen Brigade

• Step 1: Stop Putting Samples in React State

• Step 2: Separate Shape from Values

• Step 3: Move Heavy Work Off the Main Thread

• Step 4: Render Off Main with OffscreenCanvas

• Step 5: Decimate Before You Draw

• Step 6: Wrap an External Renderer

• Step 7: When Canvas isn't Enough, Reach for WebGL

• Step 8: Keep Memory Flat

• Step 9: Scheduling Strategies

• Step 10: Measure Sustained Performance

• Case Study: 19 EEG Channels

• Benchmarks: Single Thread vs Multi-Thread

• The COOP/COEP Catch

• Production Tradeoffs

• Should You Build Like This?

• Wrapping Up

• References

Prerequisites

To get the most out of this article, you'll want:

• Working knowledge of React 18 or 19. You should be comfortable with useState, useEffect, useRef, and the difference between mounting and re-rendering.

• TypeScript basics. Most examples are in TypeScript. You should be able to read type annotations without stopping.

• A rough sense of the browser main thread and event loop. You don't need to have written a Web Worker, but knowing what "blocking the main thread" means will make Step 3 easier.

• Familiarity with Canvas 2D or a chart library is a plus, not a requirement. If you've drawn anything on a canvas, you're ready.

• A laptop that can run modern Chrome or Edge. The examples rely on SharedArrayBuffer, OffscreenCanvas, and Atomics, which need a Chromium-based browser and cross-origin isolation (covered later in the article).

You don't need prior experience with Web Workers, ring buffers, or WebGL. This article introduces each in the context of a real problem.

Who's Already Doing This?

The patterns in this article aren't experimental. They're the architecture behind production apps that ingest and render high-frequency data:

• Trading and finance dashboards (Bloomberg, Hyperliquid, dYdX, every serious market viewer) push thousands of price ticks per second through canvas-rendered grids.

• Figma runs its entire canvas engine in WebAssembly inside a worker. The main thread renders React for the chrome only.

• Google Docs and Microsoft Loop run their document models in workers, with the DOM as the projection.

• Charting libraries like LightningChart, uPlot, Plotly, and ECharts draw on Canvas or WebGL and treat React as a wrapper.

• Biosignal, ECG, EEG, and motion-capture apps routinely process samples at 1kHz or higher and stream them to live plots.

• Observability and APM tools (Datadog live tail, Grafana real-time panels) decouple ingestion from render to keep tabs responsive.

• Audio editors and visualisers, plus anything using the Web Audio API with a waveform display.

• transformers.js and ONNX Runtime Web place ML inference in workers by default.

Different domains, same trick: React owns what changes rarely, something else owns what changes at refresh rate, and heavy work happens on threads that aren't the main one.

The 1kHz Math

Some numbers to make the problem concrete.

• A sample arrives every 1ms.

• A 60Hz display refreshes every 16.67ms.

• So in one frame, you'll receive roughly 16 to 17 samples per stream.

• With 19 active streams (the EEG case), that's 300 to 320 samples per frame.

If you setState on each sample, React tries to do around 19,000 renders per second. It can't, so it skips frames. The UI stutters and your laptop fans take off.

If you setState once per frame with the batch of ~320 samples, React does 60 renders per second, which is easy.

That single reframe is the entire trick, and it will echo through every step below.

Where it Usually Goes Wrong

Here's the version of the code I see in most real-time React apps the first time they try this. It looks reasonable. It's also the source of every bit of jank the team will spend the next two weeks tracking down.

import { useEffect, useState } from "react";

export default function NaiveChart({ socket }) {
  const [data, setData] = useState<number[]>([]);

  useEffect(() => {
    socket.on("newPoint", (point: number) => {
      setData((prev) => [...prev, point]); // re-renders every time
    });
  }, [socket]);

  return <div>{data.length} points</div>;
}

Three problems baked into seven lines:

1. Every incoming sample triggers a re-render: At 1kHz that's 1,000 renders per second. React was never going to be happy about that.

2. [...prev, point] allocates a new array on every push: At 1kHz that's a new array per millisecond, all of which the garbage collector has to clean up. The heap climbs, GC pauses lengthen, the fan kicks in.

3. There's no upper bound on the array: Run this for an hour and you have 3.6 million numbers in memory, all of which React has to consider on every render.

The fix isn't one trick. It's a stack of small ones, each addressing one of those failure modes and, eventually, the deeper problem of the main thread being the only thread.

The Mental Model: Air Traffic Control Plus a Kitchen Brigade

Before the code, two metaphors that will keep the pieces straight.

First, air traffic control: Three roles, one airport.

• The control tower (your store) sees every plane (every sample) and tracks where it is.

• The ground crew (React) sets up the runways and gates: the layout that planes use.

• The pilots (the draw loop) actually fly. They look at the tower for clearance and act every few seconds.

The control tower doesn't pull a gate from the ground crew every time a plane moves. It just holds the data. The ground crew rearranges gates when the schedule changes, which is rare. The pilots act constantly, at their own rate, off the tower's data.

Second, a kitchen brigade: A restaurant kitchen at peak hour. One head chef can't make every dish. The classical brigade has stations: sauce, fish, pastry, garde manger, plating, and service. Each station owns a slice of the meal. The expediter coordinates timing.

• The expediter is your main thread.

• The stations are your workers.

• The plating window is your shared memory.

• The dishes going to tables are your rendered frames.

A single chef trying to do everything serially is your main-thread-only frontend. A brigade is your worker-based one. The brigade is faster because cuts, sauces, and sears happen in parallel, not because any one cook is faster than the soloist. The expediter doesn't cook, they orchestrate.

Everything below is a specific application of these two ideas.

Step 1: Stop Putting Samples in React State

The single biggest mistake in real-time React apps is treating every sample as state, which it isn't. State is what determines which components exist and how they're arranged. A live plot is one component. The 60,000 samples scrolling across it aren't 60,000 pieces of state. They're one buffer.

You want a store that lives outside React. A ring buffer over a typed array gives you constant-time inserts and a bounded heap:

type Listener = () => void;

export function createSampleStore(capacity: number) {
  const buf = new Float32Array(capacity);
  let head = 0;
  let size = 0;
  const listeners = new Set<Listener>();

  return {
    push(sample: number) {
      buf[head] = sample;
      head = (head + 1) % capacity;
      if (size < capacity) size++;
    },
    pushBatch(samples: Float32Array) {
      for (let i = 0; i < samples.length; i++) {
        buf[head] = samples[i];
        head = (head + 1) % capacity;
        if (size < capacity) size++;
      }
    },
    read(): Float32Array {
      if (size < capacity) return buf.subarray(0, size);
      const out = new Float32Array(capacity);
      out.set(buf.subarray(head));
      out.set(buf.subarray(0, head), capacity - head);
      return out;
    },
    subscribe(l: Listener) {
      listeners.add(l);
      return () => listeners.delete(l);
    },
  };
}

Notice what's not here: no useState, no setter, no React anything. It's just plain JavaScript. The store can accept a million pushes per second and React won't care, because React isn't subscribed.

Here are the ring buffer mechanics, visualised:

We have head advances on every push and wraps at capacity. Reads pull a window of the last N samples in chronological order. The result is constant time and a bounded heap.

A simpler stop-gap, when you don't want a typed buffer yet, is to put the rolling window in a ref instead of state:

import { useEffect, useRef } from "react";

export default function RefChart({ socket }) {
  const bufferRef = useRef<number[]>([]);

  useEffect(() => {
    socket.on("newPoint", (point: number) => {
      bufferRef.current.push(point);
      if (bufferRef.current.length > 1000) {
        bufferRef.current.shift();
      }
    });
  }, [socket]);

  return <div>Streaming {bufferRef.current.length} points</div>;
}

This is the "10x faster than NaiveChart, still not great" version. The render doesn't trigger on every push, but you also won't see updates unless something else re-renders. For real plotting, pair the ref with a requestAnimationFrame draw loop (see Step 2).

Step 2: Separate Shape from Values

React renders when the shape of the UI changes. New plot? Re-render. Removed plot? Re-render. Switched from line to bar? Re-render. None of those happen at 1000Hz. They happen a few times a minute, when the user clicks something.

The values inside each plot change at the data rate. Those should never touch React.

Concretely:

function LivePlot({ store }: { store: SampleStore }) {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    const ctx = canvas.getContext("2d")!;

    let raf = 0;
    const draw = () => {
      const samples = store.read();
      drawSeries(ctx, samples);
      raf = requestAnimationFrame(draw);
    };
    raf = requestAnimationFrame(draw);
    return () => cancelAnimationFrame(raf);
  }, [store]);

  return <canvas ref={canvasRef} width={1200} height={300} />;
}

React renders this component once. The useEffect runs once. The requestAnimationFrame loop reads from the store on every frame.

The store can be pushed to at any rate the source can manage. The user sees a smooth 60fps line whether the source is sending 100 samples per second or 100,000. The instinct to wire samples into useState is wrong, so resist it.

Selective Subscriptions When You Do Need React in the Loop

Sometimes a component genuinely depends on the data (summary stats, axis labels, or a live value badge). For that, use a store with selective subscriptions so only the components that care re-render. Zustand makes this trivial:

import { create } from "zustand";

const useDataStore = create<{ latest: number | null; setLatest: (v: number) => void }>((set) => ({
  latest: null,
  setLatest: (v) => set({ latest: v }),
}));

function LatestBadge() {
  // Only re-renders when latest changes, not when other store fields do.
  const latest = useDataStore((state) => state.latest);
  return <div>Latest: {latest?.toFixed(2)}</div>;
}

Pair this with RAF coalescing on the writes (call setLatest once per frame, not once per sample) and you get a React component that updates smoothly at 60fps no matter what the data rate is.

useSyncExternalStore is the native equivalent and works against any pub-sub store, including the ring buffer above. Use whichever feels lighter for your team.

Step 3: Move Heavy Work Off the Main Thread

The store and imperative draw loop handle React's contribution to the bottleneck. The main thread itself is still doing all the ingest, parsing, and math. Everything past ~50,000 samples per second per stream needs more.

The browser gives you four escape hatches: Web Workers, transferable objects, SharedArrayBuffer + Atomics, and OffscreenCanvas. Each solves a specific problem.

The main thread runs JavaScript, the DOM, layout, and paint setup. Workers are isolated JavaScript contexts with their own event loops. They can't touch the DOM, they can't share memory by default, and every cross-thread message is async and copied unless you transfer it.

Three properties matter as you design against this model:

• Workers can't touch the DOM: That's the point. They run pure JavaScript. Perfect for data work, network parsing, math, codecs, ML inference.

• Communication is async: No shared variable to read in the middle of a function. Plan APIs around requests and events.

• Data copies, unless you transfer or share it: Structured clone is the default, transferable objects skip the copy, and SharedArrayBuffer skips it permanently.

Dedicated Workers in Practice

Here's a minimal worker for ingest:

// worker.ts
self.onmessage = (event) => {
  const { samples } = event.data;
  // Decode, filter, decimate. The main thread doesn't see any of this.
  const summary = computeStats(samples);
  postMessage(summary);
};

// main thread
import { useEffect, useRef } from "react";

export default function WorkerChart({ socket, store }) {
  const workerRef = useRef<Worker>();

  useEffect(() => {
    workerRef.current = new Worker(new URL("./worker.ts", import.meta.url), {
      type: "module",
    });

    workerRef.current.onmessage = (event) => {
      store.pushBatch(event.data); // pre-processed, cheap to ingest
    };

    socket.on("newPoint", (point: number) => {
      workerRef.current?.postMessage({ point });
    });

    return () => workerRef.current?.terminate();
  }, [socket, store]);

  return <LivePlot store={store} />;
}

Three things to internalise about workers.

First, workers are real processes from the runtime's perspective. Each has its own heap, event loop, and globalThis. Starting one costs about 1 to 5ms. Don't spin them up inside hot paths.

Second, module workers are the modern default. type: "module" enables ES modules inside the worker, including import. The legacy importScripts is for classic workers, so avoid it for new code.

Finally, bundlers know about workers. Vite, Webpack, esbuild, and Rspack all detect the new Worker(new URL("./x.ts", import.meta.url)) pattern and produce a separate chunk for the worker.

A Worker Pool That Scales with Cores

For CPU-bound work (parsing binary frames, decoding audio, computing FFTs), a pool spreads jobs across all available cores:

class WorkerPool {
  private workers: Worker[];
  private next = 0;
  private pending = new Map<string, (result: unknown) => void>();

  constructor(scriptUrl: URL, size = Math.max(1, navigator.hardwareConcurrency - 1)) {
    this.workers = Array.from({ length: size }, () => {
      const w = new Worker(scriptUrl, { type: "module" });
      w.onmessage = (event) => {
        const cb = this.pending.get(event.data.id);
        if (!cb) return;
        this.pending.delete(event.data.id);
        cb(event.data.result);
      };
      return w;
    });
  }

  async run<T>(kind: string, payload: unknown, transferables: Transferable[] = []): Promise<T> {
    const id = crypto.randomUUID();
    const result = new Promise<T>((resolve) => this.pending.set(id, resolve as (r: unknown) => void));
    const worker = this.workers[this.next];
    this.next = (this.next + 1) % this.workers.length;
    worker.postMessage({ id, kind, payload }, transferables);
    return result;
  }
}

export const pool = new WorkerPool(new URL("./decoder.worker.ts", import.meta.url));

Round-robin distribution with one worker per core minus one. Pending requests resolve when the matching response arrives. It's cheap, predictable, and scales linearly until you hit memory bandwidth limits.

Transferable Objects, the No-copy Path

postMessage clones the payload by default. Cloning a 10MB buffer takes milliseconds and doubles your memory use. The fix is to transfer the buffer instead.

The semantics: when you transfer a buffer, the sender loses access. The receiver gains it, with no copy and an O(1) handoff.

const buf = new ArrayBuffer(10 * 1024 * 1024); // 10 MB
new Uint8Array(buf).set(somePayload);

worker.postMessage({ buf }, [buf]); // second arg = list of transferables
// `buf` is now detached on this side. Accessing it throws.

The list of transferable types in 2026 includes ArrayBuffer (and any typed-array view backed by one), MessagePort, ImageBitmap, OffscreenCanvas, the stream types (ReadableStream, WritableStream, TransformStream), RTCDataChannel, VideoFrame, AudioData, and the WebTransport streams. The most useful for React plus real-time work are ArrayBuffer, OffscreenCanvas, and MessagePort.

A common pitfall is that forgetting to transfer creates silent slowness. The app works, but it copies every message. Profile worker postMessage calls. If they're showing milliseconds for "small" payloads, you're cloning when you should be transferring.

// Bad: copies every frame.
worker.postMessage({ samples: float32Array });

// Good: transfers the underlying buffer.
worker.postMessage({ samples: float32Array }, [float32Array.buffer]);

The buffer is detached after transfer, so the sender needs to re-allocate (or pull from a pool of pre-allocated buffers) if it wants to keep producing.

SharedArrayBuffer and Atomics

Transfer hands a buffer off. Sharing lets both threads see the same memory simultaneously.

const sab = new SharedArrayBuffer(1024 * 1024); // 1 MB shared
worker.postMessage({ sab });

// Both main and worker now hold references to the same memory.
const viewMain = new Int32Array(sab);
// Inside worker:
// const viewWorker = new Int32Array(event.data.sab);

Three properties matter.

SharedArrayBuffer needs cross-origin isolation. Your page must be served with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Without these headers, SharedArrayBuffer is undefined in the browser. Covered in more detail later in the article.

You also need Atomics for synchronisation. Multiple threads writing to the same memory without coordination produces undefined results. Atomics gives you compare-and-swap, load, store, add, sub, wait, and notify operations on typed array views.

const sab = new SharedArrayBuffer(8);
const view = new Int32Array(sab);

// Main thread: wake any worker that's waiting on slot 0.
Atomics.store(view, 0, 1);
Atomics.notify(view, 0, 1);

// Worker: block until slot 0 changes from 0.
const result = Atomics.wait(view, 0, 0); // "ok", "not-equal", or "timed-out"

And lock-free ring buffers are the killer app. A producer-consumer queue between two threads with no locking, no postMessage round-trip, and no GC pressure. The data sits in the shared buffer. Atomics coordinate read/write positions.

Here's a minimal SPSC (single-producer, single-consumer) ring buffer:

type SharedRing = {
  data: Float32Array;          // payload
  control: Int32Array;         // [head, tail]
};

function createSharedRing(capacity: number): SharedRing {
  const sab = new SharedArrayBuffer(capacity * 4 + 16);
  const control = new Int32Array(sab, 0, 4);   // [head, tail, ...]
  const data = new Float32Array(sab, 16, capacity);
  return { data, control };
}

function push(ring: SharedRing, value: number): boolean {
  const head = Atomics.load(ring.control, 0);
  const tail = Atomics.load(ring.control, 1);
  const next = (head + 1) % ring.data.length;
  if (next === tail) return false; // full
  ring.data[head] = value;
  Atomics.store(ring.control, 0, next);
  return true;
}

function pop(ring: SharedRing): number | null {
  const tail = Atomics.load(ring.control, 1);
  const head = Atomics.load(ring.control, 0);
  if (tail === head) return null; // empty
  const value = ring.data[tail];
  Atomics.store(ring.control, 1, (tail + 1) % ring.data.length);
  return value;
}

The producer writes from one thread. The consumer reads from another, neither blocks, and there's no postMessage between them. At signal rates, this is the only architecture that scales.

For multi-producer or multi-consumer queues, you need compare-and-swap loops (Atomics.compareExchange). They get fiddly fast. Most production setups use SPSC where they can and fall back to message-passing where they can't.

In Electron, Ingest in the Main Process

The same idea applies one level up. With Electron and a native SDK, you can ingest samples in the main process, buffer there, and forward batches across IPC at the renderer's refresh cadence. One IPC message per sample at 1kHz will saturate IPC. One IPC message per frame with a batch of 16 samples is trivial.

// electron main: buffer in Node, flush at 60Hz
let pending: number[] = [];

device.on("sample", (value) => pending.push(value));

setInterval(() => {
  if (pending.length === 0) return;
  const batch = new Float32Array(pending);
  pending = [];
  // Transferable to avoid the structured-clone copy.
  mainWindow.webContents.send("device:samples", batch.buffer, [batch.buffer]);
}, 1000 / 60);

// preload: expose a thin subscription API to the renderer
contextBridge.exposeInMainWorld("device", {
  onSamples: (cb: (samples: Float32Array) => void) => {
    const handler = (_: unknown, buf: ArrayBuffer) => cb(new Float32Array(buf));
    ipcRenderer.on("device:samples", handler);
    return () => ipcRenderer.removeListener("device:samples", handler);
  },
});

// renderer: feed the store from the bridge
useEffect(() => {
  return window.device.onSamples((batch) => store.pushBatch(batch));
}, []);

The renderer thread of the renderer touches only one batch per frame, no matter how fast the device is. The data work happens upstream.

Step 4: Render Off Main with OffscreenCanvas

The DOM is single-threaded. The Canvas API used to be too. OffscreenCanvas breaks that: a canvas you can transfer to a worker, where it draws independently of main.

// Main thread
const canvas = canvasRef.current!;
const offscreen = canvas.transferControlToOffscreen();
worker.postMessage({ canvas: offscreen }, [offscreen]);

// Worker
let ctx: OffscreenCanvasRenderingContext2D | null = null;

self.onmessage = (event) => {
  if (event.data.canvas) {
    ctx = event.data.canvas.getContext("2d");
    return;
  }
  if (event.data.samples && ctx) {
    drawSeries(ctx, event.data.samples);
  }
};

The main thread is now free to handle clicks, hover, and other interaction without competing with the draw loop. The worker draws at its own rate, against whatever data it has.

Combined with SharedArrayBuffer, you get the cleanest real-time rendering pipeline available in the browser:

The ingest worker writes samples into the shared buffer. The render worker reads them and draws. Main only reads summaries (FPS, latest value, channel labels) and renders chrome. No data ever crosses through main's event loop.

For 19-channel signal at 1kHz, this is the only architecture that keeps a guaranteed 60fps on a laptop, with headroom.

Step 5: Decimate Before You Draw

A 1200-pixel-wide canvas can show, at best, 1200 distinct X positions. If you have 60,000 samples in your window and you draw all of them, you do 50 times more work than the user can see.

Pick the right point per pixel column. The "min-max" pattern works well for signals: for each pixel column, find the minimum and maximum value in that range and draw a vertical line between them. This is visually identical to drawing every point, but it's much cheaper.

function drawDecimated(
  ctx: CanvasRenderingContext2D,
  samples: Float32Array,
  width: number,
) {
  const samplesPerPixel = samples.length / width;
  ctx.beginPath();
  for (let x = 0; x < width; x++) {
    const start = Math.floor(x * samplesPerPixel);
    const end = Math.floor((x + 1) * samplesPerPixel);
    let min = Infinity;
    let max = -Infinity;
    for (let i = start; i < end; i++) {
      const v = samples[i];
      if (v < min) min = v;
      if (v > max) max = v;
    }
    ctx.moveTo(x, scale(min));
    ctx.lineTo(x, scale(max));
  }
  ctx.stroke();
}

Decimation is the single biggest CPU win in real-time visualisation, and almost nobody does it.

A more visually faithful variant is LTTB (Largest Triangle Three Buckets), an algorithm that picks one representative sample per bucket while preserving the visual shape better than min-max. It's worth the read if you're plotting non-signal data like stock charts where peaks and dips matter individually. Most good chart libraries (uPlot, Plotly, ECharts) include decimation out of the box.

Step 6: Wrap an External Renderer

You don't always need to write the draw loop yourself. React is great at lifecycle management. Imperative chart libraries are great at raw performance. The right move is often to let React mount and unmount the chart while the library handles the fast inner loop.

import Uplot from "uplot";
import "uplot/dist/uPlot.min.css";
import { useEffect, useRef } from "react";

export default function UPlotChart({ data }: { data: AlignedData }) {
  const ref = useRef<HTMLDivElement>(null);
  const plotRef = useRef<Uplot | null>(null);

  useEffect(() => {
    const opts = {
      title: "Realtime Chart",
      width: 600,
      height: 300,
      series: [{}, { label: "Signal" }],
    };
    plotRef.current = new Uplot(opts, data, ref.current!);
    return () => plotRef.current?.destroy();
  }, []);

  useEffect(() => {
    plotRef.current?.setData(data); // imperative update, no React render
  }, [data]);

  return <div ref={ref} />;
}

uPlot, TimeChart, ECharts, Plotly, LightningChart, and the others all follow this shape: instantiate inside useEffect, call setData imperatively, and destroy on unmount. React orchestrates and the library renders.

The general pattern, for any imperative renderer, looks like this:

function ChartWrapper({ config, data }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const chart = new SomeFastChartLib(ref.current, config);
    chart.setData(data);
    return () => chart.destroy();
  }, [config, data]);

  return <div ref={ref} />;
}

This is the highest-ROI move if you're not in a domain where you need pixel-level control over the drawing. Reach for a library first, and only write your own draw loop when no library fits.

Step 7: When Canvas isn't Enough, Reach for WebGL

Canvas 2D handles a few thousand line segments per frame comfortably. Past that, you start spending milliseconds in stroke() itself.

WebGL (or its higher-level wrappers like regl, twgl, pixi.js, deck.gl) moves the rendering to the GPU. You pay an upfront cost (writing shaders and managing buffers) for the ability to draw millions of points without breaking a sweat.

Here's a minimal WebGL "line strip with a single vertex shader" sketch:

const gl = canvas.getContext("webgl2")!;

const program = gl.createProgram()!;
// ... compile vertex + fragment shaders, link, get attribute location ...

const samplesBuffer = gl.createBuffer();
function drawWebGL(samples: Float32Array) {
  gl.bindBuffer(gl.ARRAY_BUFFER, samplesBuffer);
  gl.bufferData(gl.ARRAY_BUFFER, samples, gl.STREAM_DRAW);
  gl.useProgram(program);
  gl.drawArrays(gl.LINE_STRIP, 0, samples.length);
}

The pattern is the same as Canvas 2D: an imperative draw call inside the RAF loop. The difference is the GPU does the actual rasterising. Most real-time charting libraries that claim "millions of points" are doing exactly this under the hood.

Default to Canvas 2D, and escalate to WebGL only when you can prove Canvas is the bottleneck on the Profiler.

Step 8: Keep Memory Flat

Real-time apps die slowly. They run smoothly for an hour and then the laptop fan kicks in. The cause is almost always memory.

There are three rules that keep the heap calm.

First, use typed arrays for numeric data. A Float32Array of 60,000 floats is 240KB. A plain JavaScript array of the same size is around 1.4MB and creates GC pressure on every push.

Second, bound everything. Use ring buffers, not growing arrays. Put caps on history, queues, and pending work. Anything that can grow unbounded eventually will.

Third, reuse buffers. Allocate once in setup, and reuse across frames. Allocating a fresh array per frame at 60fps is 60 allocations per second per plot. Multiply by plot count.

// Bad: fresh array every frame.
function drawFrame() {
  const snapshot = store.read(); // returns a new Float32Array
  drawDecimated(ctx, snapshot, width);
}

// Better: reuse a draw buffer.
const drawBuf = new Float32Array(WINDOW_SIZE);

function drawFrame() {
  store.readInto(drawBuf); // writes into the existing buffer
  drawDecimated(ctx, drawBuf, width);
}

These rules aren't React-specific. They're the rules any real-time system follows. The reason they need stating is that React-shaped thinking ("derive a new array each render") is the opposite of what real-time wants.

Step 9: Scheduling Strategies

A worker pool with no scheduling is just a queue. Sometimes you want priority: a user-driven action should jump ahead of a background sweep.

Priority Queues

A small priority scheduler:

type Priority = "high" | "normal" | "low";

class PriorityPool {
  private queues: Record<Priority, Job[]> = { high: [], normal: [], low: [] };
  private idle: Worker[];

  enqueue(job: Job, priority: Priority = "normal") {
    if (this.idle.length > 0) {
      const worker = this.idle.pop()!;
      this.dispatch(worker, job);
    } else {
      this.queues[priority].push(job);
    }
  }

  private next(): Job | null {
    for (const p of ["high", "normal", "low"] as const) {
      const j = this.queues[p].shift();
      if (j) return j;
    }
    return null;
  }

  private dispatch(worker: Worker, job: Job) {
    worker.postMessage(job.payload, job.transferables);
    worker.onmessage = (event) => {
      job.resolve(event.data);
      const next = this.next();
      if (next) this.dispatch(worker, next);
      else this.idle.push(worker);
    };
  }
}

Three buckets are usually enough: high (user-initiated), normal (steady-state work), low (background sweeps, prefetch, telemetry flushing).

Chunkable Work

A job that takes 2 seconds blocks a worker for 2 seconds. If you want to keep workers responsive to higher-priority jobs, the job has to be chunkable.

// In the worker:
self.onmessage = async (event) => {
  const { id, kind, payload } = event.data;
  if (kind === "decode_large") {
    const total = payload.byteLength;
    for (let i = 0; i < total; i += CHUNK) {
      const chunk = decodeChunk(payload, i, Math.min(i + CHUNK, total));
      self.postMessage({ id, kind: "progress", chunk, offset: i });
      // Yield so the worker can check its message queue.
      await new Promise((r) => setTimeout(r, 0));
    }
    self.postMessage({ id, kind: "done" });
  }
  if (kind === "cancel") {
    // ... abort the current job
  }
};

Yielding inside a worker isn't free, but it lets the worker process cancellation messages or higher-priority jobs interleaved with the big task. For long jobs (like a firmware flash, large file decode, or big render), this is essential.

Fan-out and Fan-in

Split a big job into N pieces, dispatch each to a different worker, and gather the results.

async function decodeFile(buffer: ArrayBuffer): Promise<DecodedFrame[]> {
  const chunks = splitBuffer(buffer, 8);
  const results = await Promise.all(
    chunks.map((chunk) => pool.run<DecodedFrame[]>("decode", chunk, [chunk])),
  );
  return results.flat();
}

This gives you linear speedup on parallelisable workloads, up to the worker count. It's critical for batch operations like decoding a recording, summarising a long document, or computing embeddings for a folder.

Step 10: Measure Sustained Performance

A spike on the Profiler is one thing. A slow heap creep over an hour is another. For real-time apps, you measure two things.

First, frame consistency. Are you holding 60fps consistently, or dropping occasional frames? A simple FPS meter:

let lastTime = performance.now();
let frames = 0;

function rafLoop(now: number) {
  frames++;
  if (now - lastTime >= 1000) {
    const fps = (frames * 1000) / (now - lastTime);
    frames = 0;
    lastTime = now;
    console.log(`fps: ${fps.toFixed(1)}`);
  }
  requestAnimationFrame(rafLoop);
}
requestAnimationFrame(rafLoop);

A more honest measure is the worst frame in a window. Average frame time hides the jank.

Second, heap stability. Open DevTools Memory tab, take a heap snapshot, run the app for ten minutes, take another snapshot, and then compare. The diff should be flat. If it's growing, you have a leak: retained listeners, growing arrays, or closures holding onto large objects.

For real apps, wire heap usage and FPS into your analytics so you spot regressions before users complain.

Case Study: 19 EEG Channels

Back to the project that started this article: we have nineteen channels, each at 1kHz, all rendered simultaneously, and all needing to stay smooth across multi-hour recording sessions.

The first build used LightningChart. It's powerful, capable, and beautiful. But it's also heavy. Memory usage climbed noticeably, the chart's own internals were doing a lot of work for our use case (which was 19 simple line plots, not full multi-axis financial charts), and the licensing was a friction point.

We switched to uPlot. It's tiny, fast, and written specifically for time-series. Memory usage dropped, render time per frame went from "occasionally over budget" to "always under," and my machine stopped sounding like it was about to take off. The chart library change alone bought us most of the headroom we needed.

The architecture around the chart did the rest. The pipeline runs on four threads:

• One ingest worker reads from the device SDK over IPC (Electron main process to renderer).

• One SharedArrayBuffer holds the rolling window for all 19 channels.

• One render worker reads the SAB and draws to an OffscreenCanvas.

• Main thread renders chrome: channel labels, controls, and the FPS meter.

The shared buffer layout is one big Float32Array indexed as [channel * samplesPerChannel + sampleIndex]. The ingest worker writes new samples and advances per-channel head pointers (stored in an Int32Array slice of the SAB). The render worker reads the latest window each frame.

const CHANNELS = 19;
const WINDOW_SAMPLES = 60_000;

const sab = new SharedArrayBuffer(CHANNELS * WINDOW_SAMPLES * 4 + CHANNELS * 4);
const heads = new Int32Array(sab, 0, CHANNELS);
const samples = new Float32Array(sab, CHANNELS * 4, CHANNELS * WINDOW_SAMPLES);

function writeSample(channel: number, value: number) {
  const head = Atomics.load(heads, channel);
  samples[channel * WINDOW_SAMPLES + head] = value;
  Atomics.store(heads, channel, (head + 1) % WINDOW_SAMPLES);
}

The renderer reads the channel buffers, decimates per pixel column, and draws:

// render.worker.ts
function drawFrame() {
  const ctx = offscreenCtx;
  ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
  for (let ch = 0; ch < CHANNELS; ch++) {
    const start = ch * WINDOW_SAMPLES;
    drawDecimatedRow(ctx, samples.subarray(start, start + WINDOW_SAMPLES), ch);
  }
  requestAnimationFrame(drawFrame);
}

On a 2024 M3 MacBook Pro, this holds 60fps with 19 channels at 1kHz, and 144fps if the display supports it. The main thread stays under 1% utilisation. Workers consume the spare cores. The user feels something that used to require a native app.

The lesson, in short: most of the work is choosing the right tool for the inner loop, and getting out of its way.

Benchmarks: Single Thread vs Multi-Thread

Here are numbers from running comparable workloads on a 2024 M3 MacBook Pro. They're indicative, not promissory.

The pattern: workers alone help, and workers plus shared memory help more. Workers plus shared memory plus OffscreenCanvas is what gets you to "the main thread is doing nothing and the chart is still smooth."

For chart-heavy apps, the leap from "workers" to "workers plus OffscreenCanvas" is the biggest single architectural improvement available without leaving the browser.

The COOP/COEP Catch

SharedArrayBuffer and high-resolution timers were tightened in 2020 after Spectre/Meltdown. To use them, your page must be served with two HTTP headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

This opts your page into "cross-origin isolation." Within an isolated context, SharedArrayBuffer exists, performance.now() is high-resolution, and various other restricted APIs work.

Outside an isolated context, SharedArrayBuffer is undefined, performance.now() is throttled to about 1ms precision, and Atomics throw.

The cost is significant. require-corp means every cross-origin resource (images from a CDN, embedded YouTube videos, third-party fonts, analytics scripts) must explicitly opt in by setting Cross-Origin-Resource-Policy: cross-origin or Cross-Origin-Embedder-Policy: credentialless. Many third-party services don't, which breaks their embedding.

There are two practical options:

• For an Electron app: the renderer process can be configured to use these headers easily. Most production Electron apps that want real-time visualisation enable them by default.

• For a browser app: weigh the embeds you'd lose against the performance you'd gain. If your app is the main attraction (Figma, Google Docs), opt in. If you depend on third-party widgets, the cost is real.

For chart-heavy or signal-heavy apps that need SAB, the Electron path is usually cleaner.

Production Tradeoffs

Here are the five real costs of everything above.

• Code complexity: A worker-driven app has 2 to 4 times the source files of a single-threaded one (main + workers + shared types). It's worth it for the right scale, but painful for a trivial app.

• Debugging: Stack traces split across threads. Chrome DevTools handles this well in 2026 (each worker has its own debugger panel), but it's still more work than a single-thread bug.

• Bundle size: Each worker is a separate chunk. Tree-shaking inside workers is sometimes worse than in main (less mature). Audit worker bundles separately.

• Startup latency: Spinning up workers at app start adds 50 to 200ms. Pre-warm them during the splash screen, or accept the first-frame delay.

• Browser API gaps: localStorage, document, and most DOM APIs aren't available in workers. Some libraries silently rely on them and break. Test in a worker context before bundling a library you haven't tried there.

There are three trade-offs specific to the imperative rendering pattern:

• Declarative animation of the data: The chart frame, labels, and controls all stay declarative. The data inside the chart becomes imperative.

• Easy snapshot testing of the rendered output: A canvas has no DOM you can query. Test the data path separately from the draw path. Snapshot the store output, not the pixels.

• React's component story for the inner loop: The draw loop is a closure. Composing draw loops is harder than composing components. Pick your component boundary carefully so each canvas does one thing.

For most apps these costs aren't worth paying. For an app that has to render 1kHz data smoothly, they're the price of admission.

Should You Build Like This?

If your data rate is below 30 updates per second per stream, none of this is needed. Naïve setState per batch will work. Profile first, optimise second.

This architecture earns its keep when:

• You have many streams or sensors

• Ingestion is sustained, not bursty

• The UX promise is smooth motion for hours, not seconds

• You'd rather not rewrite the UI in a native language to get there

The boring rule: start with requestAnimationFrame coalescing and external stores. Promote to workers when those aren't enough. Promote to shared memory when worker postMessage is the bottleneck. Promote to OffscreenCanvas when the render loop itself becomes the bottleneck. Each step is a real architectural investment. Take them in order.

Wrapping Up

React can handle real-time visualisation if you use it the right way. Instead of pushing React to do everything, use it as the conductor. Let specialised libraries and workers handle the heavy lifting.

These are the three rules that hold up across every high-frequency React app I've built:

1. Workers do the work, while main does the UI. If main is doing math, you've put the math in the wrong place.

2. Transfer if you can, share if you must. Both beat cloning. Sharing is more complex than transferring.

3. Let React orchestrate. Let specialised tools render. The store owns the data, the draw loop owns the values, and React owns the shape.

Get those right and your React app stops being a one-core system that flinches at high-frequency data. It becomes a real multi-core system that scales with the hardware, ingests without dropping, and renders without stuttering.

The cores are right there. Use them.

References

• uPlot: tiny, fast, focused on time-series.

• TimeChart: high-performance real-time chart on WebGL.

• Using Web Workers in React: MDN reference.

• SharedArrayBuffer on MDN: the shared-memory primitive.

• OffscreenCanvas on MDN: rendering off the main thread.

• COOP and COEP explainer: what cross-origin isolation buys you.

• Design system: the building blocks of your product (buttons, inputs, styles, tokens, patterns).

• Monorepo: one big repo with multiple packages living together, sharing tooling and workflows.

Now here's the magic: when you combine them, you get modularity, consistency, and a faster development cycle. Basically the dream setup for teams working across web, mobile, and beyond.

In this article, you'll learn how to build a modular, scalable design system using React and Turborepo – the same approach used by Microsoft, IBM, and Shopify.

Table of Contents

• Prerequisites

• Who's Already Doing This?

• Why it Works

• Think of it Like a Ladder

• The Same Design System, Everywhere

• Should You Go Monorepo?

• When a Monorepo Is Not the Right Fit

• Let's Build Our Design System

  • Create Your Turborepo Project

  • Design Your Package Structure

  • Build Your Design Tokens Package

  • Create Primitive Components

  • Configure the Turborepo Pipeline

  • Build the @yourds Packages

  • Use Your Design System in an App

• Wrapping Up

Prerequisites

Before you follow along, you'll want to have a few things in place:

• Working knowledge of React and TypeScript: You should be comfortable creating components and reading basic type annotations.

• Familiarity with the command line: You'll run npx, npm, and similar commands throughout.

• Node.js installed (v18 or later): Verify with node -v. If you don't have it, install it from nodejs.org.

• A package manager: This guide uses npm, but pnpm or yarn will work with minor command tweaks.

• A code editor of your choice (VS Code is a popular fit for TypeScript work).

You don't need any prior experience with monorepos or Turborepo. We'll set everything up from scratch.

Who's Already Doing This?

Turns out, some of the biggest design systems you've heard of run inside monorepos:

1. Microsoft Fluent UI: lives in a multi-package monorepo that ships React components, Web Components, and even design tokens.

2. IBM Carbon: multiple packages like @carbon/ibm-products come straight out of their Carbon monorepo.

3. Shopify Polaris: openly describes itself as a monorepo, packaging React components, docs, and even a VS Code extension.

4. Atlassian Atlaskit: their public @atlaskit/* packages are published from a large internal monorepo.

5. MUI (Material UI): maintained as a mono-repository to coordinate React components, tooling, and docs.

6. Elastic EUI: developed and released from a single repo, with discussions about monorepo publishing flows.

Why it Works

When you put all the pieces of your design system in one repository, you get a few specific advantages that are hard to replicate in a split-repo setup. Each of these reinforces the others, which is why teams that adopt this pattern rarely go back.

Here's what makes it work:

• Consistency: tokens, styles, and primitives are defined once and flow everywhere.

• Faster iteration: fix a bug in Button and the updates cascade to mobile, desktop, and docs instantly.

• Shared tooling: linting, tests, CI pipelines, and release workflows are configured once, and then applied to all packages.

• Versioning control: with tools like Changesets or Lerna, you can release packages independently but keep them aligned.

• Cross-platform flexibility: the same building blocks can power React web apps, React Native, Electron apps, SDKs, and documentation sites.

Think of it Like a Ladder 🪜

The cleanest way to picture a monorepo design system is as a series of stacked layers. Each layer builds on the one beneath it, and each layer has a clear job.

New contributors find their way around faster because the relationships between packages are predictable: tokens flow up into primitives, primitives compose into layouts, and layouts assemble into screens.

The diagram below shows this stack visually:

At the base, you've got primitives (tokens, styles).

Above that: plugins (utility helpers).

Then come layouts, built from plugins + primitives.

Then screens, built from layouts.

Finally, navigators tie screens together.

At the very top: your app imports just one package, and boom! The UI is environment-agnostic.

The Same Design System, Everywhere

The real payoff of this ladder is that you climb it once, then reuse the whole thing across every platform you ship to.

A button defined in your primitives package can render in a web app, a React Native mobile app, an Electron desktop app, or a documentation site without you rewriting it for each environment.

The diagram below shows the same design system flowing into three different app types, with each environment importing the same package and getting consistent styling, behaviour, and accessibility out of the box:

Whether it's web, desktop, or mobile, the design system climbs that same ladder.

Should You Go Monorepo?

Not every team needs one. But if you're building a design system that's meant to serve multiple apps, stay consistent across platforms, and support lots of contributors, then a monorepo becomes less of a buzzword and more of a sanity-saver.

When a Monorepo Is Not the Right Fit

A quick clarification first, because monorepos sometimes get tangled up with another debate. The "monorepo vs polyrepo" question is not the same as the "monolith vs microservices" question. You can absolutely run microservices out of a monorepo (Google and Facebook do this at massive scale).

The two choices live on different axes: monorepo vs polyrepo is about where the code lives, while monolith vs microservices is about how the runtime is shaped.

With that out of the way, here are a few signs a monorepo may not be the best fit for your situation:

• You're a small team shipping a single product. The tooling overhead of a monorepo (workspace config, build pipelines, package boundaries) may slow you down more than it helps. A single React app with no shared libraries probably doesn't need this layer.

• Your packages have wildly different release cadences and stakeholders. If two parts of your codebase are owned by teams that need very different deploy pipelines, governance, or security postures, separate repos can reduce friction.

• You can't invest in monorepo tooling. Tools like Turborepo, Nx, and Changesets do a lot of heavy lifting, but they have a learning curve. If your team can't dedicate time to set them up and maintain them, you may struggle.

• You're using languages or runtimes that don't share well. Monorepos shine when most packages live in the same toolchain. Mixing Node, Go, Rust, and Python in one repo is possible, but the build-tool story gets harder.

For most teams building a serious design system, none of these are dealbreakers. But it's worth checking your situation before committing.

Let's Build Our Design System

Create Your Turborepo Project

Start by creating a new Turborepo project. This gives you the perfect foundation for a scalable monorepo.

# Create a new Turborepo project
npx create-turbo@latest my-design-system

# Navigate to the project
cd my-design-system

# Install dependencies
npm install

Turborepo creates a workspace with apps/ and packages/ folders, shared tooling configuration, and optimized build pipelines.

Design Your Package Structure

Next, create a logical hierarchy for your design system packages. Think of it like a ladder, as I mentioned above: each level builds on the one below.

my-design-system/
├── packages/
│   ├── tokens/          # Design tokens (colors, spacing, typography)
│   ├── primitives/      # Base components (Button, Input, Card)
│   ├── layouts/         # Layout components (Grid, Stack, Container)
├── apps/
│   ├── web/            # Example web app
│   └── docs/           # Documentation site
└── turbo.json          # Turborepo configuration

Detailed file structure

my-design-system/
├── packages/
│   ├── tokens/
│   │   ├── src/
│   │   │   ├── colors.ts
│   │   │   ├── spacing.ts
│   │   │   ├── typography.ts
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── primitives/
│   │   ├── src/
│   │   │   ├── Button/
│   │   │   │   └── Button.tsx
│   │   │   ├── Input/
│   │   │   │   └── Input.tsx
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── layouts/
│   │   ├── src/
│   │   │   ├── Grid/
│   │   │   ├── Stack/
│   │   │   └── index.ts
│   │   └── package.json
├── apps/
│   ├── web/
│   │   ├── src/
│   │   │   ├── App.tsx
│   │   │   └── main.tsx
│   │   ├── index.html
│   │   └── package.json
│   └── docs/
│       ├── src/
│       └── package.json
├── turbo.json
├── package.json
└── README.md

Build Your Design Tokens Package

Start with the foundation: design tokens. Tokens are the smallest, most reusable units of a design system: a color value, a spacing step, a font size, a border radius. Instead of hard-coding padding: 16px or color: #3b82f6 everywhere, you reference a token like spacing.md or colors.primary[500].

The benefits are huge:

• One place to change a value: update a token once and every component that uses it updates automatically.

• Theming becomes trivial: want a dark mode? Just swap which tokens resolve to which values.

• Cross-platform consistency: the same token names work in web CSS, native styles, even Figma.

Tokens are the DNA of your design system. Let's build them.

# Create the tokens package
mkdir -p packages/tokens/src
cd packages/tokens

Update these in your packages/tokens/package.json. This file declares the package name, version, build scripts, and dev dependencies needed to compile the token source files into a publishable package:

{
  "name": "@yourds/tokens",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}

Update these in your packages/tokens/src/colors.ts. This file defines the color tokens: a named palette of color values organised by intent (primary, gray) and shade (50 is lightest, 900 is darkest). Components reference these by name rather than hardcoding hex codes:

export const colors = {
  primary: {
    50: '#f0f9ff',
    100: '#e0f2fe',
    500: '#3b82f6',
    600: '#2563eb',
    900: '#1e3a8a'
  },
  gray: {
    50: '#f9fafb',
    100: '#f3f4f6',
    500: '#6b7280',
    900: '#111827'
  }
} as const;

Update these in your packages/tokens/src/spacing.ts. This file defines the spacing scale: a set of standard size steps that components use for padding, margin, and gap values. Using a fixed scale (xs, sm, md, lg, and so on) keeps spacing consistent across the UI:

export const spacing = {
  xs: '0.25rem',    // 4px
  sm: '0.5rem',     // 8px
  md: '1rem',       // 16px
  lg: '1.5rem',     // 24px
  xl: '2rem',       // 32px
  '2xl': '3rem'     // 48px
} as const;

Update these in your packages/tokens/src/typography.ts. This file defines the typography tokens: font sizes and font weights that components use for text. Like spacing, these are named steps rather than arbitrary pixel values:

export const typography = {
  fontSizes: {
    xs: '0.75rem',
    sm: '0.875rem',
    base: '1rem',
    lg: '1.125rem',
    xl: '1.25rem',
    '2xl': '1.5rem'
  },
  fontWeights: {
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700
  }
} as const;

Update these in your packages/tokens/src/index.ts. This file is the public entry point of the package: it re-exports everything from the three token files so consumers can do import { colors, spacing, typography } from "@yourds/tokens" in a single line:

export * from './colors';
export * from './spacing';
export * from './typography';

Create Primitive Components

Build your base components that consume the design tokens:

# Create the primitives package
mkdir -p packages/primitives/src
cd packages/primitives

# Install dependencies
npm install react react-dom

Update these in your packages/primitives/package.json:

{
  "name": "@yourds/primitives",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts --external react",
    "dev": "tsup src/index.ts --format cjs,esm --dts --external react --watch"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}

Update these in your packages/primitives/src/Button/Button.tsx:

import React from 'react';
import { colors, spacing } from '@yourds/tokens';

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
  disabled?: boolean;
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children,
  disabled = false,
  ...props
}) => {
  const baseStyles = {
    border: 'none',
    borderRadius: '0.5rem',
    cursor: disabled ? 'not-allowed' : 'pointer',
    fontWeight: 500,
    transition: 'all 0.2s ease',
    opacity: disabled ? 0.6 : 1
  };

  const variants = {
    primary: {
      backgroundColor: colors.primary[500],
      color: 'white',
      ':hover': { backgroundColor: colors.primary[600] }
    },
    secondary: {
      backgroundColor: colors.gray[100],
      color: colors.gray[900],
      ':hover': { backgroundColor: colors.gray[200] }
    },
    outline: {
      backgroundColor: 'transparent',
      color: colors.primary[500],
      border: `1px solid ${colors.primary[500]}`,
      ':hover': { backgroundColor: colors.primary[50] }
    }
  };

  const sizes = {
    sm: { padding: `\({spacing.xs} \){spacing.sm}`, fontSize: '0.875rem' },
    md: { padding: `\({spacing.sm} \){spacing.md}`, fontSize: '1rem' },
    lg: { padding: `\({spacing.md} \){spacing.lg}`, fontSize: '1.125rem' }
  };

  const buttonStyle = {
    ...baseStyles,
    ...variants[variant],
    ...sizes[size]
  };

  return (
    <button style={buttonStyle} disabled={disabled} {...props}>
      {children}
    </button>
  );
};

Update these in your packages/primitives/src/index.ts:

export { Button } from './Button/Button';
export type { ButtonProps } from './Button/Button';

Configure the Turborepo Pipeline

Now, set up the build pipeline in turbo.json to ensure packages build in the correct order.

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}

Build the @yourds Packages

With the tokens and primitives packages defined, the next step is to compile them so they can be consumed by your apps.

Running npm install at the root resolves all workspace dependencies, including the internal links between @yourds/tokens and @yourds/primitives. Then npm run build walks through every package and runs each one's build script, which Turborepo orders correctly so tokens compiles before primitives (since primitives depend on tokens). The final npm install step then registers the built packages so your apps/web app can import them by name:

# Go to the root of the monorepo
npm install

# Compile every package in the right order
npm run build

# Register the built packages for the apps to use
npm install @yourds/tokens @yourds/primitives

If everything ran successfully, you should see a dist/ folder inside both packages/tokens and packages/primitives, containing compiled JavaScript and TypeScript declaration files.

Use Your Design System in an App

Now you can consume your design system in any React application.

The example below replaces the default content in your apps/web/src/App.tsx file with a small home page that demonstrates two things at once: importing primitives (the Button component) from @yourds/primitives, and importing tokens (colors, spacing) directly from @yourds/tokens to style standard HTML elements like the wrapper <div> and the <h1>.

The result is a fully working page that uses your design system end-to-end, with zero hardcoded colors or spacing values:

import { Button } from "@yourds/primitives";
import { colors, spacing } from "@yourds/tokens";

export default function Home() {
  return (
    <div style={{ padding: spacing.lg }}>
      <h1 style={{ color: colors.primary[500] }}>My App with Design System</h1>
      <Button variant="primary" size="lg">
        Get Started
      </Button>
      <Button variant="outline" size="md">
        Learn More
      </Button>
    </div>
  );
}

Once you save the file, run the app in development mode:

npx turbo dev --filter=web

You should see your home page render with the primary[500] blue heading, padded by spacing.lg, and two buttons styled by your shared design system. Any change you make to a token (say, swapping the primary color) will flow into this page automatically the next time you rebuild.

Wrapping up

A monorepo won't magically make your design system perfect. But it does give you:

• A shared space where everything connects

• The agility to publish parts independently

• The clarity to scale design across teams and platforms

No wonder the biggest design systems in the world are already doing it.