DEV Community: Grzegorz Otto

The Turborepo + Bun + Biome stack behind a 40-package monorepo

Grzegorz Otto — Wed, 08 Jul 2026 03:21:44 +0000

Forty packages, one maintainer, and no ESLint config anywhere in the repo. That is not a boast - it is the direct result of a decision made early: every tool in the toolchain has to earn its place by governing all forty packages from one config file, not forty.

The repo is flare-engine, a modular 2D engine for React Native + Web (animation, gamification, interactive UI, with games as showcases - not a game engine, not a Unity or Godot competitor). The stack behind it is Turborepo Bun Biome, and this post is the actual setup: the real turbo.json, the real biome.json, the real CI guardrail, straight from the repo (trimmed only where a config is long, and I say so where I trim), not a starter template's idealized version.

Four binaries, four root configs - turbo.json, biome.json, tsconfig.base.json, and the Changesets config - each governing all forty packages at once (Bun's own "config" is just the workspaces array in the root package.json). Plus a CI step that fails the build the moment a package imports something it shouldn't. That is the whole story, and I want to show you the files, not describe them.

Four binaries, not twelve config files

The thesis is narrow: a solo maintainer can keep forty packages honest only if there is exactly one config of each kind, and every package extends it rather than declaring its own variant. Twelve packages each with a slightly different ESLint config is not a monorepo, it is twelve monorepos wearing a workspace file as a costume.

Here is the root package.json that runs all of it - Bun workspaces (not pnpm; that distinction matters and I will say it again below), the script table every package leans on, and the pinned package manager:

// C:\_PROG\flare-engine-workspace\flare-engine\package.json
{
  "name": "flare-engine",
  "version": "0.0.0",
  "private": true,
  "workspaces": ["packages/*", "benchmarks", "apps/*"],
  "scripts": {
    "build": "turbo build",
    "test": "turbo test",
    "lint": "turbo lint",
    "typecheck": "turbo typecheck",
    "check:deps": "bun scripts/check-deps-tiers.mjs",
    "check:changeset": "bun scripts/check-changeset.mjs",
    "lint:fix": "biome check --write .",
    "format": "biome format --write .",
    "release": "bun run propagate-license && turbo build --filter='./packages/*' && changeset publish"
  },
  "packageManager": "bun@1.2.0"
}

workspaces is a plain array of globs - packages/*, the private benchmarks package, and apps/*. No pnpm-workspace.yaml, because there is no pnpm here. scripts.build/test/lint/typecheck are one-liners that hand off to turbo <task> - the root package.json doesn't know how to build anything itself, it just fans the call out. check:deps and check:changeset are the two custom guardrails covered later. lint:fix is biome check --write . over the entire repo - one binary, every package, one pass.

Bun as the whole toolbelt

Bun is the second of the three legs of Turborepo Bun Biome, and it's doing more work than "package manager" implies - it is the runtime, the test runner, and the workspace mechanism in one binary. bun install resolves the workspace graph and writes a text lockfile. bun test runs every package's unit tests without a separate Jest or Vitest config. bun scripts/check-deps-tiers.mjs runs a plain ESM script with zero build step.

I want to be explicit about something, because it is easy to get wrong reading about this stack in 2026: this is Bun workspaces, not pnpm. pnpm 10 is what runs this portfolio's own repo - a completely different project. Mixing the two up is a category error, and if you're evaluating "Bun workspaces vs pnpm" for your own monorepo, the honest answer is that flare-engine picked Bun specifically because collapsing the runtime, the package manager, and the test runner into one binary was worth more than pnpm's more mature workspace tooling.

The versions in this post are a snapshot, resolved from bun.lock on 2026-07-04: Bun 1.2.0, Turborepo 2.9.6, Biome 1.9.4, TypeScript 5.9.3. Bun 1.3, Turborepo 3.0, and Biome 2.2 already exist upstream as of this writing - if you're reading this later, check your own lockfile before copying a version number out of a blog post.

One turbo.json for 40 packages

Turborepo Bun Biome is the whole toolchain, and turbo.json is the file that makes the "one config governs forty packages" claim literal. Here it is in full - four tasks and a cache-key line:

// C:\_PROG\flare-engine-workspace\flare-engine\turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["tsconfig.base.json", "tsconfig.json", "biome.json", "bunfig.toml"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "out/**"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {},
    "typecheck": {
      "dependsOn": ["^build"]
    }
  }
}

build.dependsOn: ["^build"] is the caret-prefixed dependency graph: before a package builds, every package it depends on has to build first (the ^ means "this task in my dependencies," not "this task in me"). outputs tells Turborepo which directories to hash and cache - dist/** for the tsup output, out/** for the one Next.js app in apps/*. globalDependencies does the inverse: it puts the root configs (biome.json, tsconfig.base.json, bunfig.toml) into every task's cache key, so editing any one of them busts the cache for all forty packages at once, not just the package you touched. test.dependsOn: ["build"] means tests only run against built output, never against stale dist. typecheck.dependsOn: ["^build"] needs its dependencies' type declarations to exist first, but not its own build (typecheck doesn't need itself pre-built - tsc --noEmit reads .ts source directly). lint: {} has no dependency at all - it is fully parallel, because Biome only ever looks at one package's own src/ directory.

dependencies' build (^build)
        │
        ├──▶ build ──▶ test
        │
        └──▶ typecheck

lint  (no deps, fully parallel)

That outputs array is also the entire cache contract. When Turborepo sees a task whose inputs (source files + lockfile + this turbo.json) hash to something it has seen before, it replays the recorded outputs instead of re-running the task - the "FULL TURBO" line in the terminal. I am not going to hand you a cache-hit percentage here; a third-party 2026 monorepo guide claims a specific number for Bun over pnpm, and that number is theirs, measured on their repo, not mine. The honest visual for this post is a real terminal capture of a cold turbo run build followed by a warm one hitting the cache - no invented statistic attached.

Biome: lint and format in one config

Biome replaces ESLint and Prettier with one Rust binary and one config file. biome.json, trimmed to the linter and formatter blocks:

// C:\_PROG\flare-engine-workspace\flare-engine\biome.json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always"
    }
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "correctness": {
        "noUnusedImports": "error",
        "noUnusedVariables": "error"
      },
      "style": {
        "noNonNullAssertion": "off",
        "useConsistentArrayType": {
          "level": "error",
          "options": { "syntax": "shorthand" }
        },
        "useImportType": "error",
        "useSingleVarDeclarator": "off",
        "noDefaultExport": "error"
      }
    }
  }
}

noUnusedImports and noUnusedVariables are set to error, not warn - a dead import fails CI, it doesn't just clutter a report. useImportType is also error: every type-only import must say import type, which matters a great deal in a monorepo where verbatimModuleSyntax (next section) is on - a plain import of a type-only binding is a build error, not a lint nit. noNonNullAssertion is explicitly turned off - the codebase uses ! deliberately in places where the type system can't see an invariant the engine guarantees at runtime. noDefaultExport is set to error as well, so the whole codebase is named-exports-only, with a small overrides block that flips the rule back off for the handful of files that genuinely need a default export (config files like *.config.ts and the Next.js app pages). One file. Lint and format both live here; there is no separate .eslintrc and .prettierrc to keep in sync, because there's nothing to keep in sync.

One tsconfig base, 40 extends

tsconfig.base.json is the config every package's TypeScript extends - the same one-config-governs-all rule, applied to type-checking:

// C:\_PROG\flare-engine-workspace\flare-engine\tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true,
    "types": ["bun-types"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "noUncheckedIndexedAccess": true
  },
  "exclude": ["node_modules", "dist"]
}

strict and noUncheckedIndexedAccess are the two settings that catch the most real bugs in practice - the second means array[i] is typed T | undefined, not T, so every index access has to prove it checked bounds. verbatimModuleSyntax is what makes Biome's useImportType rule load-bearing rather than cosmetic: without it, a type-only import that isn't marked import type can survive erasure incorrectly at the module boundary. Forty packages extend this one file and layer on their own include paths - none of them re-declares strict or re-decides whether indexed access is checked.

Releasing in lockstep

Changesets manages versioning, and the .changeset/config.json makes a deliberate, debatable choice - lockstep, not independent SemVer:

// C:\_PROG\flare-engine-workspace\flare-engine\.changeset\config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": ["@changesets/changelog-github", { "repo": "grzott/flare-engine" }],
  "commit": false,
  "fixed": [["@flare-engine/*"]],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@flare-engine/benchmarks"]
}

fixed: [["@flare-engine/*"]] means every scoped package bumps together - all forty move from 0.2.0 to 0.2.1 in the same release, even if only math changed. That is lazy by the independent-SemVer argument, and I'll name the tradeoff honestly: for a single-maintainer engine where consumers (Pan Tvardowski, the internal second game) always want the whole set moving in step, lockstep removes an entire class of "which version of render works with which version of ecs" support questions. If this were a multi-team OSS project with independent release cadences per package, I'd pick linked groups or full independence instead.

access: "restricted" is the other load-bearing field. @flare-engine/* publishes to the private npm registry at version 0.2.1 today - restricted until the October 2026 Apache-2.0 launch. Any example below that says bun add @flare-engine/math needs that fine print attached, every time:

# Restricted until the Oct-2026 Apache-2.0 launch - not yet public npm
bun add @flare-engine/math

ignore: ["@flare-engine/benchmarks"] excludes the private benchmarking package from versioning entirely - it lives outside packages/ and never ships.

A per-package example, packages/math/package.json, shows the four scripts every one of the forty packages carries:

// C:\_PROG\flare-engine-workspace\flare-engine\packages\math\package.json
{
  "name": "@flare-engine/math",
  "version": "0.2.1",
  "scripts": {
    "build": "tsup",
    "test": "bun test",
    "lint": "biome check src/",
    "typecheck": "tsc --noEmit"
  },
  "publishConfig": {
    "access": "restricted",
    "registry": "https://registry.npmjs.org/"
  },
  "sideEffects": false
}

Same four scripts, every package, every time - tsup for the build, bun test for the tests, biome check src/ for lint, tsc --noEmit for typecheck. Turborepo's whole job is fanning these four identical scripts out across forty package.json files in dependency order.

The guardrail that ties it together

None of the above prevents a package from importing something one tier above it in the dependency graph - config alone doesn't enforce architecture. That enforcement is a custom script, scripts/check-deps-tiers.mjs, wired into CI:

// C:\_PROG\flare-engine-workspace\flare-engine\scripts\check-deps-tiers.mjs
/**
 * check-deps-tiers - CI guardrail for the @flare-engine/* dependency graph.
 *
 * Three checks over every packages/*:
 *   1. PHANTOM deps - declared in package.json (deps + peerDeps) but never
 *      imported from src (.ts/.tsx/.mts/.cts).
 *   2. MISSING deps - imported from src but not declared.
 *   3. UPWARD tier violations - a package depending on a strictly-higher tier,
 *      breaking the downward-only rule. `@flare-engine/engine` is the sanctioned
 *      umbrella barrel: it may depend on anything, but its own deps are still
 *      required to point downward from every OTHER package's perspective.
 *
 * Phantom and missing are both errors. Exit 1 on any violation, 0 when clean.
 * Bun-runnable plain ESM.
 */

Three checks, one script, exit 1 on any violation: phantom dependencies (declared but never imported - dead weight), missing dependencies (imported but never declared - the thing that silently works today and breaks the moment hoisting changes), and upward-tier violations (a lower-tier package reaching into a higher-tier one, breaking the downward-only dependency rule that keeps the whole graph acyclic). This is the mechanical enforcement of the same strict-layer discipline covered in Architecture before the AI build - that post argued for the rule; this script is what makes the rule impossible to violate by accident. The result, measured 2026-07-04: 0 dependency cycles across the full acyclic DAG.

CI wires all of this into one ordered chain, .github/workflows/ci.yml:

# C:\_PROG\flare-engine-workspace\flare-engine\.github\workflows\ci.yml
name: CI

on:
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile

      - run: bun run lint
      - run: bun run check:deps
      - run: bun run check:changeset
      - run: bun run typecheck
      - run: bun run build
      - run: bun run test

bun install --frozen-lockfile first - no silent lockfile drift on a PR build. Then six steps in a fixed order: lint (fast, fully parallel, fails first if it's going to fail), check:deps (the tier guardrail above), check:changeset (did this PR remember to add a changeset), typecheck, build, test - the slowest and most expensive check runs last, after everything cheaper has already had a chance to fail fast. This is engine-only CI: it exercises lint/typecheck/build/test on Ubuntu with setup-bun, not on-device React Native builds, which run through a separate EAS pipeline outside this post's scope.

Limits

Bun, not pnpm. Said once above, said again here because it's the easiest thing to get backwards reading about this stack out of context: flare-engine runs on Bun workspaces. pnpm 10 is a different repo (this portfolio). If you're deciding between the two for your own monorepo, don't let this post stand in for a real Bun-vs-pnpm benchmark - it isn't one.

Versions drift fast. Bun 1.2.0, Turborepo 2.9.6, Biome 1.9.4, TypeScript 5.9.3 are the resolved versions from bun.lock on 2026-07-04. Bun 1.3, Turborepo 3.0, and Biome 2.2 are already out in the wild as this publishes. Treat every version number here as a dated snapshot, not a recommendation to pin.

No cache-hit percentage of my own. I did not measure a cache-hit rate on this repo, and I'm not going to borrow the "~40% fewer cache misses vs pnpm" number from someone else's 2026 guide and present it as mine. The gallery above shows a real, unedited turbo run build replay hitting FULL TURBO - that's the honest visual, with no percentage attached to it.

Restricted npm. @flare-engine/* publishes access: restricted at version 0.2.1 - private registry, not installable by the public - until the October 2026 Apache-2.0 launch. The repo's LICENSE file says MIT today; Apache-2.0 is the plan for the pre-launch relicense, not the current state.

This is a tooling post, not an engine-internals post. The framing here is a monorepo running a modular 2D engine for React Native + Web animation, gamification, and interactive UI - games are showcases built on it, not the product itself, and this isn't a game-engine-vs-Unity-or-Godot comparison. If you want the engine's internals, that's a different post.

Close

If you're setting up or cleaning up a TypeScript monorepo in 2026, the shape here scales down further than forty packages suggests. Two packages need almost none of this - you can skip the tier guardrail and the lockstep Changesets config until you actually have a dependency graph worth protecting. What doesn't scale down is the discipline of one config per tool: the moment you let a second package declare its own ESLint rules or its own tsconfig strictness, you've started the sprawl this whole stack exists to prevent.

This toolchain is also the reason a new prototype package - a second consumer app, an experiment that might not ship - takes minutes to wire up instead of days: bun add, extend the base tsconfig, and Turborepo already knows how to build, test, lint, and typecheck it in the right order. Clone the shape, not the exact numbers; your forty will look different from mine.

If you want the layering rule this repo's CI mechanically enforces, Architecture before the AI build is the post that argues for it. If you want to see where this repo started - 36 packages, three weeks, the same strict-layer discipline before the guardrail script existed - that's 36 packages, 1 dev: a React Native game engine in 3 weeks.

I built generator coroutines for my game engine, then didn't use them

Grzegorz Otto — Tue, 23 Jun 2026 15:29:39 +0000

Generator coroutines are the textbook fix for callback hell in game sequencing. Write a boss script or a cutscene as a straight-line function* that yields to wait, instead of a pyramid of timers and callbacks. I built exactly that for my engine - CoroutineManager, 122 lines, 12 tests, three yield kinds. Then, when it came time to actually script the bosses in the shipped game, I used a finite state machine instead and left the coroutine system unused on purpose.

This post is about why. Two reasons that most TypeScript game coroutines tutorials never mention, because they don't matter until you ship a real-time, save-capable game.

The elegant case for TypeScript game coroutines

The pitch for coroutines is real and fair. Consider scripting a boss that pauses, fires, waits two seconds, then fires again. With timers and callbacks you get something like this:

// pseudocode
startPhase(() => {
  fire();
  setTimeout(() => {
    fire();
    setTimeout(() => {
      startNextPhase();
    }, 1000);
  }, 2000);
});

With a generator coroutine, the same logic reads as a straight sequence:

// pseudocode
function* bossScript() {
  fire();
  yield 2.0;   // wait 2 seconds
  fire();
  yield 1.0;   // wait 1 second
  startNextPhase();
}

The generator version is obviously better to read and modify. The sequencing matches the mental model of "first this, then that." It's the same pattern Unity uses - Unity coroutines are C# iterator methods (IEnumerator + yield return) started via StartCoroutine and stopped via StopCoroutine, with built-in yield instructions such as WaitForSeconds, WaitForEndOfFrame, WaitUntil, and WaitWhile. It's also why redux-saga, a widely-used Redux middleware, models side-effect orchestration with generator functions: a saga is a generator that yields plain JavaScript objects ("effects") describing what should happen, and the middleware interprets each effect and resumes the generator - a real-world precedent for generators as a sequencing model outside of games.

The readability argument won me over. So I built the scheduler.

What I actually built

The CoroutineManager lives in packages/core/src/coroutine.ts and clocks in at 122 lines. It tracks active coroutines in a list, ticks them on every update(dt) call, and handles three yield kinds: number (wait N seconds), undefined (wait one frame), and Promise (wait for async resolution).

The heart of the scheduler is the advance method. Here it is verbatim:

// packages/core/src/coroutine.ts
private advance(state: CoroutineState): void {
  const result = state.gen.next();
  if (result.done) {
    state.done = true;
    return;
  }

  const value = result.value;
  if (typeof value === 'number') {
    state.waitTime = value;
  } else if (value instanceof Promise) {
    state.waitingForPromise = true;
    value.then(
      () => {
        state.waitingForPromise = false;
      },
      () => {
        // On rejection, stop the coroutine
        state.done = true;
      },
    );
  }
  // undefined → wait 1 frame (will advance next update)
}

The system has 12 tests. The only callers are those tests - nothing in the game or the engine's other packages uses CoroutineManager. Here is one of those test callsites, verbatim:

// packages/core/tests/coroutine.test.ts
mgr.start(
  (function* () {
    yield 0.5;
    reached = true;
  })(),
);

The ergonomics are clean. The tests pass. And then I chose not to wire it into the game.

Reason 1: allocation on the hot path

Look at advance again. The first line is const result = state.gen.next().

By the ECMAScript specification, every generator .next() returns a freshly created {value, done} object. ECMA-262 §7.4.12 (CreateIterResultObject) does OrdinaryObjectCreate(%Object.prototype%) then sets the value and done properties and returns that new object. On top of that, invoking the generator function in the first place allocates the generator object itself.

On Hermes - the JavaScript engine React Native uses - this result object is allocated on every .next() with no JIT to elide it, so a manually-driven generator loop produces steady per-step GC pressure. On V8, TurboFan's escape analysis can sometimes eliminate the iterResult allocation for plain for-of loops, but not for hand-driven .next() coroutine loops like this one. So on both engines you get a stream of small, short-lived objects accumulating across every frame.

This is not a hard per-frame performance cliff. Minor GC of young objects is cheap. The point is that it is non-zero allocation on a path engineered for zero allocation. The engine's frame loop is designed around zero per-frame heap allocation - typed arrays for component data, pooled event objects, pre-allocated collision structures. Running a coroutine scheduler in that loop introduces steady GC pressure from a source that compounds with every additional concurrent sequence.

No measured profiling number exists for this path, because I never wired the coroutines into the loop. The allocation argument is a design reason grounded in how generators work - not a benchmark.

Reason 2: you can't serialize a paused generator

The harder dealbreaker is serialization.

A paused JavaScript generator cannot be serialized. Its resume state lives in spec-internal slots - [[GeneratorState]] and [[GeneratorContext]], the latter holding the execution context with the suspended instruction position and live scope. These are not exposed to user code and have no defined serialization form. Call structuredClone on a generator and you get a DataCloneError on the closure. Call JSON.stringify and you get {}.

For a game engine that needs to support save states, replays, or deterministic tests, this matters. The sequence's progress must be plain, restorable data - something you can write to disk and reload. A generator's "where am I" is a black box.

The FSM solves this directly. The boss's state is a string field on the Boss component - b.phase. On every update, the system reads that string and drives behavior from it. Here is the serialization tell, verbatim from the real boss FSM:

// Pan-Tvardowski/src/systems/boss/fsm.ts
runtime.context.deps = deps;
const currentName = runtime.fsm.current?.name;
if (currentName !== b.phase) runtime.fsm.start(b.phase);

b.phase is the entire state. To save the game, serialize b.phase. To load, set b.phase and call fsm.start(b.phase) - the FSM reconstructs from that string. A paused generator has no equivalent. You would have to re-implement explicit progress tracking anyway, at which point you have reinvented the FSM.

What won and why

The finite state machine won on the two axes that matter for a real-time, save-capable game.

Its authoritative state is a string on a component - zero per-frame allocation, trivially serializable. The FSM primitive itself is 76 lines in packages/ecs/src/fsm.ts. The PT boss system uses it today: phase edges drive transitions, cooldown-driven fire callbacks handle the in-phase cadence. There is no function* anywhere in the boss code.

A zero-allocation data-driven timeline stepper - a planned next refinement - would let me express a phase's beat sequence as an array of pattern steps rather than procedural callbacks. That is planned, not shipped. Today the pattern is FSM + fire callbacks.

Here is the comparison at a glance:

Property	Generator coroutine	Finite state machine
Readability of a sequence	Excellent - straight-line `function*`	Moderate - phase edges + callbacks
Per-frame allocation	One generator object + one `{value,done}` per step	Zero
Serializable state	No - internal slots only	Yes - a string on a component
Cancellation semantics	`return()` on the generator	State transition to an end state
Best fit	Non-hot-path async, once-through flows	Real-time game logic with save requirements

As a decision tree:

Game sequencing need
│
└─ In the frame loop?
   ├─ No  → Generator coroutine
   └─ Yes → Must survive a save?
            ├─ Yes → Finite state machine
            └─ No  → Many concurrent sequences?
                     ├─ Yes → Finite state machine
                     └─ No  → Generator coroutine

Limits

No benchmark exists for the coroutine path. The allocation argument is qualitative, grounded in spec behavior and the engine's zero-alloc discipline - not a measured fps delta. On V8, escape analysis may partially elide the iterResult allocation in some loops; on Hermes, it does not. Either way, the serialization reason stands independently.

The FSM is not a readability win over coroutines. Boss scripts expressed as phase edges and fire callbacks are less obviously sequential than a function*. That trade-off is real. If readability were the only axis, coroutines would have won.

The engine is published to npm as @flare-engine/* version 0.1.0 with restricted access - it is not open source at this stage. The CoroutineManager ships in @flare-engine/core; it is simply unused by the game.

Where coroutines do belong

The coroutine system is not a mistake. It is the right tool on a different layer.

For non-hot-path async - scripting an onboarding flow in a React Native app, sequencing an asset or boot pipeline, running any once-through async glue that is not in the frame loop and does not need to survive a save - a generator coroutine is excellent. The readability benefit is real. The allocation and serialization costs do not apply to a flow that runs once, on startup, outside the 60 fps tick.

This is the exact example for the React Native prototyping angle: generators are how you script onboarding flows without callback hell in React Native. The mistake is not reaching for generators; the mistake is wiring them into the frame loop of a save-capable game and pretending the trade-offs aren't there.

Right tool, wrong layer.

Originally posted on grzegorzotto.dev

Archetype ECS in TypeScript: why I didn't use bitECS or miniplex

Grzegorz Otto — Wed, 10 Jun 2026 04:42:55 +0000

Everyone says "use an ECS." Nobody tells you the real decision is how it stores components. That choice shapes the API, the performance envelope, and the limits you'll hit two years later.

The TypeScript ecosystem has two well-built options. bitECS goes struct-of-arrays: each component field is a TypedArray indexed by entity id. It's the throughput pick - designed for high entity counts (tens of thousands and up), and it serializes efficiently because the bytes are contiguous typed arrays. miniplex goes object-based: entities are plain objects, queries are archetype buckets that re-index on add/remove, and the TypeScript integration is the friendliest I've seen. If you want React bindings out of the box, miniplex 2.x is the one.

I used neither for @flare-engine/ecs. I wrote a third approach - bitmask archetypes plus per-component Maps - and accepted one hard limit to get there. This post is about that trade-off.

What an archetype ECS TypeScript implementation actually decides

An ECS is three things: entities (integer IDs), components (plain data attached to entities), and systems (functions that run over "every entity with components X and Y").

The part libraries differ on is the last word: how do you find all entities with components X and Y?

The naive answer is to scan every entity and check. That is O(n) in entity count and dies at scale. The productive answer is to maintain an index so "give me all entities with Position and Velocity" is nearly free. How you build that index is the design decision.

There are three ways to build that index:

Model	Data layout	Wins	Costs
bitECS - struct-of-arrays	`Position.x: Float32Array`, `Position.y: Float32Array`, indexed by entityId	cache-local, scales to 100k	data = parallel arrays
miniplex - object buckets	archetype bucket: `[{pos, vel}, ...]`	great DX + React	object-heap iteration, GC pressure at scale
flare-engine - bitmask + Maps	entity 3 → archetype `0b011`; per-component stores `Map{3 → {x,y}}`	readable in debugger, one bitmask-AND match	32-component ceiling

Struct-of-arrays (bitECS). Every field of every component is a typed array indexed by entity ID. Position.x[3] and Position.y[3] are the position of entity 3. CPU cache loves this - you iterate a contiguous block of floats. The cost: your data is parallel arrays, not objects. You can't console.log an entity and see its components. Serialization is a typed-array snapshot. This is the right shape when you're at 10k+ entities and throughput is the primary constraint.

Object archetype buckets (miniplex). Entities are plain objects. miniplex uses an archetype model - archetypes in 1.x, reworked into the .with() / .without() query API in 2.x: entities with the same component set land in the same bucket, so a query iterates one array of objects rather than all entities. Great DX, strong TypeScript narrowing, first-class React integration. The cost: you're iterating object heap references, which is harder for the CPU to prefetch, and GC pressure increases with churn. At hundreds of entities this is invisible. At 50k with frequent add/remove it starts to matter.

Bitmask archetypes plus per-component Maps (flare-engine). Each component type gets a unique integer ID and a bit (1 << id). An entity's current component set is stored as a single number - its archetype bitmask. Component data lives in Map<entityId, data> per component type. "Does entity 3 have Position and Velocity?" is (archetype3 & mask) === mask - one bitwise AND. The cost: Map indirection is not cache-local, and the 32-bit JavaScript number limits you to 32 component types.

The flare-engine code

The whole ECS is eight files. Here are the three that carry the bulk of the design.

Component definition

// packages/ecs/src/component.ts
let nextComponentId = 0;

export function defineComponent<T = undefined>(name: string, defaults?: () => T): ComponentDef<T> {
  const id = nextComponentId++;
  if (id >= 32) {
    throw new Error(`Maximum 32 component types exceeded (defining "${name}")`);
  }
  return {
    id,
    bit: 1 << id,
    name,
    create: defaults ?? (() => undefined as T),
  };
}

defineComponent hands out sequential IDs and computes a bit. When id hits 32, 1 << 32 wraps to 1 in JavaScript - a silent collision - so the throw is load-bearing, not defensive. Tag components (no data, just presence) pass no defaults; the returned create() returns undefined.

World - storage and mutation

// packages/ecs/src/world.ts
export class World {
  private archetypes = new Map<number, number>();       // entityId → bitmask
  private componentStores = new Map<number, Map<number, unknown>>(); // componentId → (entityId → data)

  add<T>(entityId: number, def: ComponentDef<T>, data?: T): void {
    const arch = this.archetypes.get(entityId);
    if (arch === undefined) return;

    let store = this.componentStores.get(def.id);
    if (!store) {
      store = new Map();
      this.componentStores.set(def.id, store);
    }
    store.set(entityId, data !== undefined ? data : def.create());

    const newArch = arch | def.bit;          // OR in the bit
    this.archetypes.set(entityId, newArch);

    for (const query of this.queries) {      // notify live queries
      query._check(entityId, newArch);
    }
  }
}

The JSDoc on World says explicitly: "Archetype bitmasks enable fast query matching." add ORs the component's bit into the entity's archetype, then calls _check on every registered query. remove ANDs the inverted bit out: arch & ~def.bit. has is (arch & def.bit) !== 0 - a single expression.

Query - the bitmask match

// packages/ecs/src/query.ts
export class Query {
  readonly requiredMask: number;
  readonly excludedMask: number;

  private entities: number[] = [];
  private entitySet = new Set<number>();  // O(1) membership

  readonly onEntityAdded = new Signal<number>();
  readonly onEntityRemoved = new Signal<number>();

  matches(archetype: number): boolean {
    return (
      (archetype & this.requiredMask) === this.requiredMask &&
      (archetype & this.excludedMask) === 0
    );
  }

  _check(entityId: number, archetype: number): void {
    const isMatch = this.matches(archetype);
    const wasMatch = this.entitySet.has(entityId);

    if (isMatch && !wasMatch) {
      this.entitySet.add(entityId);
      this.entities.push(entityId);
      this.onEntityAdded.emit(entityId);
    } else if (!isMatch && wasMatch) {
      this.entitySet.delete(entityId);
      this.entities.splice(this.entities.indexOf(entityId), 1);
      this.onEntityRemoved.emit(entityId);
    }
  }
}

matches is the whole archetype-query engine. Everything else is bookkeeping.

_check keeps entities[] and entitySet in sync and fires onEntityAdded / onEntityRemoved Signals. Those signals are what let @flare-engine/react subscribe to query membership changes without polling - the React side calls useEffect on the signal and gets notified when enemies spawn or despawn, no manual diffing.

world.query(Position, Velocity) builds a requiredMask by ORing the bits of the passed components and constructs a Query(mask, 0). The .queryBuilder().with(A).without(B).build() path composes requiredMask and excludedMask separately.

Why this shape for this engine

Three reasons.

Readability. world.query(Position, Velocity) reads like English. The underlying data - Map<number, {x: number, y: number}> - prints as a plain object in any debugger or console.log. I spent a significant portion of the engine's early development reading entity state in the Bun REPL. Parallel typed arrays are opaque there.

Reactive queries. The Signal-based onEntityAdded / onEntityRemoved pair means the React layer and the ECS layer share membership information without a polling bridge. When Pan Tvardowski's bullet-spawner adds a Bullet component, every query that requires Bullet reacts immediately - the lifetime/cleanup sweep, the bullet alpha-pulse pass, the devtools snapshot counter. No per-frame scan.

Simplicity of the match. A single AND covers "has all required components and none of the excluded ones." Every query - no matter how many with/without clauses - reduces to the same fixed two-operation test.

The numbers - measured, off-device

The ecs.step microbench runs world.step(dt) with a single move system (read Position + Velocity, write Position) on Bun, off-device. These numbers measure the ECS step in isolation - not on-device frame time, not the full game loop.

Entities	Step cost	Throughput
500	11.51 µs	86.9K ops/sec
1,000	23.7 µs	42.2K ops/sec
2,000	46.70 µs	21.4K ops/sec
5,000	119.68 µs	8.4K ops/sec

The curve is linear - roughly 24 ns per entity, no cliff. Pan Tvardowski runs on the order of hundreds of live entities at peak. At that scale the ECS step is well under a millisecond.

The more honest benchmark is the full integration frame: 1,000 entities plus 300 particles, measured off-device on Bun, costs 9.01 ms - and the ECS step is a small slice of that. On a Samsung Galaxy A54 5G under heavy load (50 enemies, 300 bullets), the game drops to around 48 fps. That cliff is not the ECS. The engine's own analysis points to CollisionWorld.step - physics broadphase, not entity queries - as the bottleneck at that load (~350 bodies: 50 enemies + 300 bullets), where the off-device physics microbench crosses its 500-AABB threshold and the per-step cost extrapolates to most of the frame budget. The ECS was never my bottleneck, so I optimized it for readability rather than for a throughput crown I didn't need.

Caveat on the external numbers. The noctjs/ecs-benchmark suite reports bitECS at ~335K ops/sec (packed_5 scenario) and miniplex at ~109K ops/sec. Those numbers come from a different harness measuring a different operation - I cannot put "23.7 µs" and "335K ops/sec" in the same sentence as if they're comparable. What they do tell you: struct-of-arrays is built for throughput at scale. I wasn't at scale.

Limits - where this choice is wrong

The 32-component ceiling is real and hard. 1 << id on a JavaScript number is 32-bit. Past 32 component types you get a silent bit collision - the throw in defineComponent is the only guard. If your game or simulation has 40+ component types, this architecture forces you to either pack flags into a single component, move to a BigInt multi-word mask, or switch to bitECS. For Pan Tvardowski, the current count is well under 32; I've never approached the wall. But I know where it is.

No cache locality. Map<entityId, data> indirection is the opposite of bitECS's whole point. Each world.get(entityId, Position) is a Map lookup - a hash, a pointer follow, a heap read. At 10k+ entities with a tight system loop this compounds into measurable latency. The envelope for this architecture is hundreds-to-low-thousands of entities. The engine's design notes float a struct-of-arrays path as a possible next step if I outgrow Maps - but it doesn't ship yet. Per-component Maps are the only storage path today. SoA is what I'd reach for if the benchmarks started showing a cliff.

No serialization story. bitECS can snapshot a game state by cloning typed arrays - the bytes are contiguous and typed. Maps of plain objects require a custom serializer. Pan Tvardowski sidesteps this differently: it uses a seeded deterministic RNG for reproducible benchmark runs rather than serializing live state. If you need save-state or netcode out of the box, that's a point for bitECS.

No multi-threading. becsy is the ECS being built around multi-threading - though as of 0.15.x that multi-threaded execution is still on its roadmap, not yet shipped. This one is single-threaded, and makes no attempt otherwise.

The pattern beyond games

Archetype queries are not game-specific. They are indexed sets of things matching a shape. If you have a kanban board with thousands of cards that can be "blocked", "overdue", "assigned", "flagged" - a bitmask-per-card plus a query for "overdue AND assigned AND NOT blocked" is an O(1) per-card match plus a push-based reactive update. The same pattern applies to chat messages with read/pinned/flagged states, to map markers with type/visible/selected/clustered states, to live feeds where items enter and leave "above-the-fold" visibility.

The ECS framing is the cue: when you're managing thousands of homogeneous items and the interesting logic is "do something to all items matching these conditions," archetype queries are a legitimate state model regardless of whether you're rendering sprites or rendering a React list.

The allocation discipline that makes this safe in a hot loop is a separate piece - the zero-alloc game loops post covers why object storage stays harmless in a hot loop only when the move system pools and mutates in place, never allocating inside step. And the Skia Atlas post shows the other end of the frame: the ECS query for renderable entities feeds the SpriteBatch that draws them in a single draw call.

Originally posted on grzegorzotto.dev

Zero-allocation TypeScript game loops: 60 fps on a mid-range Android phone

Grzegorz Otto — Tue, 26 May 2026 14:30:56 +0000

16.67 ms sounds generous until a garbage collector decides to think.

Across three Android devices (a year-old mid-tier, an older flagship, and a current flagship), release builds, Hermes runtime, a 2D TypeScript game loop has roughly that long to advance every entity, run every system, and flush every draw command to Skia before the display catches up. The zero-allocation TypeScript discipline keeps that budget intact across a 36-package engine and a shipped showcase game. Five rules carry the load: plain {x, y} objects instead of Vec2 classes, an out parameter made mandatory on every hot-path operation, one generic Pool<T> reused everywhere transient objects appear, module-level scratch state for random-number generation, and an atlas render pipeline that groups draw commands by texture so the GPU sees one draw call per batch instead of one per sprite.

Measured outcome (three Android devices, release build, Hermes, TestingBot Maestro sweep 2026-05-26): worst cell across five gameplay scenarios landed at 9.52 ms p95 frame-time (Pixel 10, particle-storm) - 7.15 ms of headroom against the 16.67 ms / 60 fps budget. The four real-gameplay flows stayed between 0.93 ms and 4.18 ms. The frame budget is decided at module load - not at the closure-allocating callsite an autocomplete suggested.

The frame budget on a mid-range Android

16.67 ms is the 60-fps wall. Hermes ships the Hades concurrent garbage collector (GC) by default - Hades keeps pause times short, roughly 70%+ shorter than the older JavaScriptCore (JSC) engine, but "short" is not zero, and the pauses scale with allocation rate. A single allocation inside a for loop over 300 particles is not one allocation: it is 300 allocations per frame, which is 18,000 allocations per second at 60 fps. Each one is a fresh object the GC has to trace and collect.

The game loop itself - onFixedUpdate / onUpdate / onLateUpdate / onPreRender / onPostRender signals, a fixed 16.67 ms step accumulator, a maxDt cap to prevent the spiral of death - is defined in packages/core/src/game-loop.ts and packages/core/src/clock.ts. That structure is not the subject here. What the loop runs inside every signal is the subject.

Five gameplay scenarios captured 2026-05-26 via TestingBot Maestro on three real Android devices, release build, Hermes runtime. Each cell is the p95 frame-time across a 30-second steady-state window, measured by a recorder that brackets the live game loop (postfx + ECS + Skia render), not a synthetic micro-bench. The 16.67 ms / 60 fps budget is the reference:

Scenario	Galaxy A55	Pixel 6	Pixel 10
boot (ambient Zone 1)	0.93 ms	1.51 ms	1.76 ms
boss-smok (mid-FSM + bullets)	1.00 ms	1.58 ms	3.40 ms
boss-lucyper (3-phase postfx)	1.11 ms	1.61 ms	2.03 ms
zone-transitions (despawn + respawn every 5s)	2.25 ms	4.18 ms	3.73 ms
particle-storm (synthetic worst-case)	3.67 ms	6.69 ms	9.52 ms

Worst observed cell across the sweep: 9.52 ms (Pixel 10, particle-storm). That leaves 7.15 ms of headroom against the 16.67 ms 60-fps budget - roughly 43% of the frame unused at p95 even under the synthetic worst-case load. The four real-gameplay flows (boot, boss fights, zone transitions) sat between 0.93 ms and 4.18 ms - 75-95% of the budget unspent.

Postfx-stage p95 stayed under 0.030 ms in every cell across the sweep. The screen-effect pipeline is not the bottleneck.

Methodology and caveats. Each cell is a single TestingBot capture (n=1) from a cloud device farm, 2026-05-26. The 30-second window starts after stable steady state. "p95 frame-time" is the 95th-percentile of per-frame durations - one frame in twenty exceeded the listed value during the window. With n=1 per cell, this is a preliminary baseline, not a device-vs-device ranking; the noise floor between cloud-farm sessions is wider than several of the inter-device gaps in the table. A nightly cron is now accumulating samples; a future post will share rolling medians once the dataset is meaningful.

This sweep also replaces a different measurement methodology from April 2026. The earlier numbers (Samsung Galaxy A54 5G, entity-count stress with 10/30/50 enemies and 50/150/300 bullets, average fps) covered a narrower scenario set on one device. The current sweep traded that for p95 frame-time across in-game gameplay flows on three devices, which is closer to how the shipped game actually runs.

Plain objects beat classes - zero-allocation TypeScript by construction

The cheapest object is the one that already exists.

A Vec2 class allocates on every construction. A plain { x, y } object allocated once and mutated in place does not. The engine uses a plain-object type plus a static namespace for all math operations - no prototype chain, no GC pressure from construction:

// packages/math/src/vec2.ts
/** Vec2 plain object type - no class, no GC pressure. */
export type Vec2 = { x: number; y: number };

/** Creates a Vec2 plain object. */
export function vec2(x = 0, y = 0): Vec2 {
  return { x, y };
}

The static namespace includes an optional out parameter on every operation. Optional means callers who do not care about allocations can ignore it. The mandatory-out variant removes the option entirely:

// packages/math/src/vec2.ts
  /** Component-wise addition. Writes into out if provided. */
  add(a: Vec2, b: Vec2, out?: Vec2): Vec2 {
    if (out) {
      out.x = a.x + b.x;
      out.y = a.y + b.y;
      return out;
    }
    return { x: a.x + b.x, y: a.y + b.y };
  },

Vec2.add(a, b) returns a fresh object. That is the natural autocomplete completion - it is what a senior dev would reach for on first pass, and it is wrong in any loop over hundreds of entities. The discipline is to supply the out buffer and never let that form ship in a hot path. The lint catches some obvious cases; code review catches the rest.

For the genuinely hot path - computing a normalised velocity vector inside an enemy update loop - the engine drops the optional form entirely:

// packages/math/src/vec2.ts
  /** Zero-alloc; writes into `out`. Mandatory `out` so callers avoid temporaries in hot paths. */
  normalizeOut(dx: number, dy: number, speed: number, out: Vec2): Vec2 {
    const len = Math.sqrt(dx * dx + dy * dy);
    if (len <= 1e-6) {
      out.x = 0;
      out.y = 0;
      return out;
    }
    const inv = speed / len;
    out.x = dx * inv;
    out.y = dy * inv;
    return out;
  },

normalizeOut has no return-a-fresh-object path. The caller owns the buffer. In a 300-bullet update loop, that is 300 existing Vec2 structs written into - not 300 new ones allocated. Autocomplete will not write this form for you; the signature forces the discipline on the caller.

One Pool to rule them - twelve lines, three patterns

The pool pattern is not new. Robert Nystrom's Game Programming Patterns documented it in 2014. What is new here is that one twelve-line generic primitive runs the entire 36-package engine plus every transient in Pan Tvardowski - particles, sprite-batch commands, audio sources, explosion FX slots. One shape, applied uniformly:

// packages/core/src/pool.ts
/**
 * Generic object pool for zero-alloc gameplay.
 *
 * - acquire() returns a recycled or newly created object
 * - release(obj) returns it to the pool
 * - prewarm(count) pre-allocates objects
 */
export class Pool<T> {
  private items: T[] = [];
  private factory: () => T;
  private resetFn: ((item: T) => void) | undefined;

  /**
   * @param factory Function to create a new instance.
   * @param reset Optional function to reset an object before reuse.
   */
  constructor(factory: () => T, reset?: (item: T) => void) {
    this.factory = factory;
    this.resetFn = reset;
  }

  /** Get an object from the pool (or create a new one). */
  acquire(): T {
    if (this.items.length > 0) {
      return this.items.pop()!;
    }
    return this.factory();
  }

  /** Return an object to the pool. Calls reset if configured. */
  release(item: T): void {
    if (this.resetFn) this.resetFn(item);
    this.items.push(item);
  }

  /** Pre-allocate objects into the pool. */
  prewarm(count: number): void {
    for (let i = 0; i < count; i++) {
      this.items.push(this.factory());
    }
  }

  /** Number of available objects in the pool. */
  get available(): number {
    return this.items.length;
  }

  /** Clear all pooled objects. */
  clear(): void {
    this.items.length = 0;
  }
}

Three real consumers, three patterns, one primitive:

ParticlePool (packages/particles/src/particle-pool.ts) wraps Pool<Particle> and calls prewarm(256) at construction - 256 particle slots ready before the first frame. The update() method uses a swap-and-pop release so the active list never shifts: when a particle's lifetime hits zero, it swaps with the last element and pops, returning the dead particle to the pool in O(1).

SpriteBatch (packages/render/src/sprite-batch.ts) keeps an internal _pool: SpriteDrawCommand[] and an _acquire() method that pops from the pool or calls the factory. Every draw() call writes into a recycled command object. At flush(), every command returns to the pool and _commands.length = 0 resets the list in place - no splice, no filter, no GC.

Pan Tvardowski explosion FX slots - the third pattern is module-level rather than class-level: a fixed-size array prewarmed at module load, not inside a constructor:

Lifecycle of one slot through that pool:

At module load, _spiralPool is prewarmed with 8 slots, each set to { entityId: -1, active: false }.
triggerSpiralCollapse(entityId) walks the pool, finds the first slot where !active, sets slot.active = true and slot.entityId = entityId.
The play-scene tick advances the SpiralCollapse component until elapsed >= duration.
When the duration expires, world.destroy(entityId) fires and the slot resets to slot.active = false, slot.entityId = -1 - ready for the next collapse.

The slots themselves, prewarmed at module load in Pan Tvardowski:

// apps/pan-tvardowski/src/fx/explosions.ts
const SPIRAL_POOL_SIZE = 8;

interface SpiralSlot {
  entityId: number;
  active: boolean;
}

const _spiralPool: SpiralSlot[] = [];
for (let _i = 0; _i < SPIRAL_POOL_SIZE; _i++) {
  _spiralPool.push({ entityId: -1, active: false });
}

The key point: prewarm sizing is a scene-load decision, not a per-frame one. The worst time to grow a pool is during gameplay. All three patterns - class-level with constructor prewarm, class-level with internal pop/factory, and module-level with literal array init - move that cost to module or scene load. Once the game loop is running, no pool grows.

Scratch state and the module-level linear congruential generator

Random numbers should not allocate either.

Math.random() is a closure call. A per-call array of candidate values is worse. The engine uses a module-level scalar _lcgS with a linear congruential generator (LCG) function _lcgNext() - re-seeded per call from the spawn position so identical spawns produce identical particle sequences:

// apps/pan-tvardowski/src/fx/explosions.ts
// Scratch LCG state - zero-alloc; re-seeded per call.
let _lcgS = 1;

function _lcgNext(): number {
  _lcgS = (_lcgS * 16807) % 2147483647;
  return (_lcgS - 1) / 2147483646;
}

// [inside _spawnParticles:]
// Seed the LCG reproducibly from position so identical spawns are consistent.
_lcgS = (x * 31 + y * 17) | 0 || 1;

No new, no array, no closure capture per call. One number on the module scope, rewritten in place. The deterministic seeding from spawn position is load-bearing for replay testing - a future post will cover deterministic game testing in depth.

The render side - atlas batching is part of the allocation story

A draw call is the heaviest object in the system. Allocating fewer is as important as pooling particles.

SpriteBatch.flush() (packages/render/src/sprite-batch.ts) groups all queued draw commands by the triple (image, effect, alpha) - the atlas key. Every command that shares the same key goes into one batch. The render call fires once per batch - one draw call per atlas texture batch (per-texture, not per-sprite). A change in effect or alpha breaks a batch by design; that is a structural property, not a bug.

At the end of flush(), every SpriteDrawCommand returns to the internal pool, _commands.length = 0 resets the list, and the batch records are cleared in place. The command objects survive across frames - the frame boundary is a reset, not a reconstruction.

Microbench figures from the Bun harness (harness, not device - see Limits):

Benchmark	Config	Result	Throughput
Entity-Component-System (ECS) step	1,000 entities (Pos+Vel)	23.7 µs/frame	42.2K ops/sec
Render flush	1,000 sprites in 1 atlas	26.6 µs/frame	37.6K ops/sec
Integration frame	1,000 entities + 300 particles	9.01 ms/frame	111 ops/sec

The integration frame - Entity-Component-System step plus render flush plus particle update, 1,000 entities and 300 particles - completes in 9.01 ms on the desktop harness. That is inside the 16.67 ms / 60-fps budget by roughly 40%. The device p95 numbers (the scenario table earlier in this post) are what matter for shipped behaviour; the harness figures show the math fits on a desktop CPU.

What the measurements say - and do not

The three devices in this sweep span roughly two years of Android hardware: a Galaxy A55 (Exynos 1480, Android 14) as a mid-tier reference, a Pixel 6 (Tensor G1, Android 13) as an older flagship, and a Pixel 10 (Tensor G5, Android 16, 120 Hz) as a current flagship. All ran release builds on Hermes. iOS measurements are pending; no JavaScriptCore comparison exists yet.

Every cell in the sweep cleared the 16.67 ms / 60 fps budget at p95. The worst cell (Pixel 10, particle-storm, 9.52 ms) is the floor of the headroom claim - everything else sat further inside the frame. With n=1 per cell, do not read inter-device differences as device rankings; read them as a baseline distribution.

The harness microbenches (23.7 µs Entity-Component-System step, 26.6 µs render flush, 9.01 ms integration frame) are from bun bench on a desktop CPU, not a phone CPU. They validate that the math fits the budget in isolation. The device p95 numbers above are what happened on actual hardware. Both matter; they are not the same measurement.

As of 2026-05-20, the engine carried approximately 2,481 tests green and Pan Tvardowski carried 1,168 - the p95 numbers above came from that same engine running the shipped game's gameplay code paths, not from a synthetic stress harness.

Limits

Three Android devices, single OS family. Every measurement in this post is Android, release build, Hermes runtime. No iOS, no JavaScriptCore (JSC) comparison. The sweep names three devices spanning a year-old mid-tier to a current flagship; with n=1 per cell this is a baseline, not a fleet model.

p95 is one metric. The long tail (p99, p99.9, frame spikes) is not in this snapshot. A frame that exceeds the 16.67 ms budget but stays inside p95 is hidden by definition. A nightly cron is now accumulating samples so a future post can publish rolling medians plus the long tail.

The April A54 stress test is retired. That run used entity-count synthetic loads (10/30/50 enemies, 50/150/300 bullets) and reported average fps - including a heavy-mode dip to 48 fps. The new sweep traded that for p95 frame-time across in-game scenarios on three devices. The two datasets are not directly comparable; the May sweep is closer to shipped gameplay, the April sweep pushed harder on raw entity counts.

Harness microbenches are not device measurements. 23.7 µs Entity-Component-System (ECS) step and 26.6 µs render flush are from bun bench on a desktop dev machine. They show the algorithm fits the frame budget; the device p95 numbers in the scenario table are what actually happens on a phone.

Discipline, not a tool. No lint rule catches "you closed over a fresh { x, y } inside a worklet." Code review catches it; tests do not. The normalizeOut signature communicates intent but cannot enforce that every caller supplies a pre-existing buffer. The senior dev's job is to recognise the pattern and reject the natural autocomplete completion - which returns a fresh object - in any hot path.

Hermes regime, 2026. Hades concurrent GC keeps pauses short but not zero. A closure-allocating callsite inside a 300-iteration update loop still moves the needle. The claim is that the discipline is robust under Hermes' GC model - not that Hermes removes the problem.

The engine is not open-source software (OSS) yet. The October 2026 Release Candidate (RC) target is when the engine publishes to npm. The code blocks and provenance paths in this post are the current public record; readers cannot inspect the repository today.

Not the orchestration sequel. The patterns in this post predate any AI-directed session - they are discipline, not orchestration.

Close

The rule a reader can apply this week: in any hot loop, name the buffer you write into. If the call signature does not accept an out, fix the signature first.

The same discipline applies outside games. A React Native app running a Reanimated worklet, a Skia canvas, or a gesture handler doing per-frame coordinate math wants the same shape: pre-allocate the state object, mutate it in place on update, never close over a fresh { x, y } inside the worklet. An animated dashboard rendering 200 cards at 60 fps has the same problem as a game rendering 200 bullets - the frame budget is the frame budget.

If you want the context this post grew from: the 3-week build story for the origin, the engine-gap post for the why, and the architecture deep-dive for the structural layer the discipline runs inside. The next deep-dive covers the Skia Atlas pipeline in detail - how useRSXformBuffer drives the per-texture batching at higher sprite counts.

Originally posted on grzegorzotto.dev.

The React Native game engine gap in 2026 - RNGE, Skia, Phaser-in-WebView, expo-gl

Grzegorz Otto — Tue, 12 May 2026 15:31:30 +0000

I needed a 2D game engine for an action game I'm building in React Native. I went looking for one. There is no React Native game engine in 2026.

There are four partial options - each serious in its own domain, each missing something fundamental for the others. I spent two weeks mapping exactly where each one breaks. By the end of the second week, I'd started writing the missing layer myself. This post is the map I built before that decision.

The four options I evaluated: react-native-game-engine (RNGE), Phaser 4 inside a WebView, the graphics primitives expo-gl and react-native-wgpu, and @shopify/react-native-skia paired with Reanimated 4. None of these is a React Native game engine in the sense of "install it, add a game loop, render sprites, play audio, manage scenes." Each one is something else - a renderer, a context, a web engine in a sandbox, a dormant project - and each one fails at a specific cliff. Here is where each cliff sits and what it means.

Option 1 - `react-native-game-engine` (dormant, JS-only)

RNGE was where I started. It is the only library that has ever called itself a React Native game engine, and the API is real - an entity-component update + render loop, the pattern any 2D engine starts from. I cloned it, ran the examples, and the architecture sketch convinced me for about an hour.

Then I read the publish history. The last version is 1.2.0, published in June 2020 - nearly six years ago. Around 2,235 downloads per week, sustained by projects that cannot migrate, not by anyone actively choosing it. The issue tracker has been silent for years.

The deeper problem was architectural, not bibliographic. RNGE renders each game entity by mounting a React Native View. There is no GPU path, no sprite atlas, no draw-call batching. On a mid-range Android, roughly 50 active entities is where frames start to drop. For a turn-based puzzle game with a handful of pieces, RNGE still works - that regime is real and the library still serves it. For anything action-shaped - bullets, particles, animated enemies - the ceiling appears before the game is interesting to play.

This is a reference implementation with a community, not a maintained engine. I closed the tab.

Option 2 - Phaser 4 in a WebView

Phaser is one of the great open-source projects of the decade. Phaser 4 shipped GA in April 2026 with around 40,000 GitHub stars and roughly 166,000 npm downloads per week - those are real numbers from a real engine, on the web. If you are building a 2D game for browsers, this is what you reach for.

Inside a React Native app, the integration is exactly one shape: you mount Phaser inside a <WebView>. That is the entire bridge. There is no shared state with your RN navigation, no shared Reanimated layer, no direct access to native APIs. You are running two runtimes - the host RN app and an embedded Chromium-class browser - and they do not share anything that matters at the engine level. The WebView pays its own startup cost, fights the host app's GC, and sits behind a JS-to-JS bridge for any cross-boundary state.

The performance reality on Android is hard. Phaser 4 itself is fast - the April "Caladan" release describes it as a "completely rewritten WebGL based renderer." But Phaser 4 running inside an Android WebView runs roughly 5-10× slower than the same Phaser scene running in a desktop browser, because the WebView's GPU driver paths and GC behavior are not Chrome's. iOS Safari's JIT narrows the gap. The architectural reality does not change: this is the web's engine running in a sandbox inside your app.

If you already have a Phaser game and want to embed it inside an RN shell as a playable surface, the WebView route works and ships today. Several games on the App Store and Play Store do exactly this. But the project I was running was "render 2D game content using React Native's own rendering pipeline so it shares state with the rest of my app." Phaser-in-WebView is not that project. It is RN-as-a-launcher.

Option 3 - `expo-gl` and `react-native-wgpu` (primitives, not engines)

By the third checkpoint I had a hypothesis: maybe the answer is to build straight on the GPU primitives. There are two healthy primitive-layer libraries in the RN ecosystem in 2026. expo-gl exposes a WebGL 2.0 context; its latest version, 55.0.13, was published in May 2026 - actively maintained, broad device support, in Expo Go. react-native-wgpu exposes WebGPU on RN 0.81+ with the New Architecture, backed by Google's Dawn runtime. WebGPU on mobile React Native is real and shipping.

Neither of these is an engine. They are graphics contexts.

What they do not ship: a sprite batcher, a scene system, an asset pipeline, audio sync, an input abstraction, an ECS. Every one of those layers is on you. Building a 2D game on top of expo-gl or react-native-wgpu is the same as building a 2D game on top of WebGL or WebGPU in any other host - perfectly legitimate, but the engine work is the project, not a starting point.

TypeGPU and react-three-fiber's React Native template demonstrate the ecosystem is alive. They also confirm the engine layer above the primitives is empty. The infrastructure is there. Nobody has assembled it. That is not a criticism of the primitive libraries - they are doing exactly what they should - it is a statement about where the gap sits in the stack.

Option 4 - Skia + Reanimated

@shopify/react-native-skia is where the evaluation actually changes shape. It is the only credible native GPU path inside React Native today, downloaded around 750,000 times per week. Paired with Reanimated 4 - the worklet layer that makes per-frame UI-thread computation viable - Skia is the closest thing the RN ecosystem has to an engine-grade renderer.

A regime caveat first, because it is load-bearing. Reanimated 4 is New Architecture only (Fabric, no Paper). The 4.0/4.1 line requires RN 0.78+; the current 4.3.x line (4.3.1 published 2026-05-07) requires RN 0.81+. Apps still on the legacy Paper renderer must stay on Reanimated 3.x, and Reanimated 3's worklet model is not the same animal as 4's. The Skia + Reanimated 4 architecture described here only exists if your app is on the New Architecture.

The primitive that makes this viable is Skia's <Atlas> API combined with Reanimated's useRSXformBuffer. You define a sprite atlas, write a worklet that fills a typed buffer of RSX transforms - one per sprite - and Skia issues a single GPU draw call regardless of sprite count. The transforms are computed on the UI thread, not the JS thread. That is the architecture that makes fast 2D viable on React Native, full stop.

// @shopify/react-native-skia - Atlas + useRSXformBuffer
// docs: https://shopify.github.io/react-native-skia/docs/shapes/atlas/
import { Atlas, useRSXformBuffer } from '@shopify/react-native-skia';

// One RSXform per sprite: [scos, ssin, tx, ty]
// Computed on the UI thread inside a worklet - no JS bridge per frame.
const transforms = useRSXformBuffer(spriteCount, (val, i) => {
  'worklet';
  const entity = entities[i];
  val.set(
    entity.cos * entity.scale,
    entity.sin * entity.scale,
    entity.x,
    entity.y,
  );
});

// Single GPU draw call regardless of spriteCount.
return <Atlas image={atlas} sprites={rects} transforms={transforms} />;

I ran the architecture across realistic game loads on my benchmark device - a Samsung Galaxy A54 5G, release build, Android. Light load (10 enemies + 50 bullets) held at 120 fps. Medium (30 enemies + 150 bullets) held at 117 fps. Heavy (50 enemies + 300 bullets) dropped to 48 fps. The cliff is real, but it sits where I'd want it to sit: at the edge of action-game intensity, not in the middle.

Then I checked the cheap-Android floor and the entire calculus changed. On an OPPO A16 - the kind of budget device that represents a meaningful slice of the Indian and Eastern European markets I want this game to reach - the <Atlas> API tops out at roughly 300 sprites before frames drop. That number comes from Skia GitHub issue #2521 - community-reported, not a controlled benchmark on my desk. The same issue reports an iPhone 12 mini holds up to around 15,000 sprites before slight drops appear. The spread is roughly 50×. If your game or animated UI needs 400 simultaneous sprites and your floor device is budget Android, the headline number is not the design number. The cheap-Android number is.

That insight applies far beyond games. The Atlas + worklet path is exactly what powers animated dashboards, gesture-rich onboarding flows, and custom-rendered card UIs in non-game RN apps. The device floor applies there too. If you are shipping a high-touch animated UI to global Android, the Skia + Reanimated path is real and it is constrained by the same math.

But - and this is where the journey ended for me - Skia is only the renderer. It does not ship sprite sheets, tilemaps, a scene stack, game-shaped audio, input gesture layers, or an ECS. You get a high-performance 2D canvas with good batching semantics on the New Architecture, and everything above that layer - the game engine - is yours to build. That is exactly what I started doing two weeks into this evaluation.

What this means if you want a React Native game engine today

After four checkpoints the map writes itself. The four options sit on a two-by-two grid, on two axes: whether they give you native GPU access (rows) and whether they ship a full engine layer - game loop, scenes, assets, audio, input - above the renderer (columns).

	No engine layer (renderer/context only)	Full engine layer (loop, scenes, assets, audio, input)
Native GPU	Skia + Reanimated 4 (renderer only); `expo-gl` / `react-native-wgpu` (context only)	empty: the gap, does not exist in RN
No native GPU	`react-native-game-engine` (RN Views, dormant)	Phaser 4 in WebView (full engine, separate runtime)

The top-right cell - native GPU rendering plus a full engine layer - is empty. That thing does not exist in React Native. That is the gap. That is what I started building.

If you are mapping your own project against the grid, here is how I would pick from where I sit today:

RNGE if you have a handful-of-entities puzzle game, a prototype, or a project that needs to ship today and cannot take on a renderer migration. Accept the ceiling; it is real and it will not move.

Phaser-in-WebView if you already have a finished Phaser game and need to embed it in an RN shell. This is a launcher, not an integration. The experience is bounded by WebView performance on your floor device.

expo-gl / react-native-wgpu if you are building the engine on purpose. You want full control of the GPU stack, you understand the scope, and you have time. The primitives are excellent; the work above them is yours.

Skia + Reanimated if your device floor sits above the OPPO A16 class, you accept building scenes, audio, input, and ECS yourself, and you want native GPU batching without leaving React Native. Do the device-floor math against your target market before you commit.

None of these is "React Native game engine" off the shelf. That thing does not exist yet. I am now writing the layer that would close that quadrant. Whether anyone else needs it is the question I am answering by building it.

Limits

Four limits apply to everything above.

Single benchmark device. Every frame number in this post - 120 fps, 117 fps, 48 fps - comes from a Samsung Galaxy A54 5G running a release build, Android only. iOS is not tested in this post's benchmarks. An iPad Pro M-series will laugh at every cliff named here. A 2020 budget Android will fall below the OPPO A16 floor before the numbers even apply.

Crowdsourced device-floor numbers. The ~300 sprites on OPPO A16 and ~15,000 on iPhone 12 mini come from Skia GitHub issue #2521 - community reports, not a controlled benchmark I ran. Treat them as the device-floor lesson, not the device-floor table. I link the issue rather than presenting the numbers as measured data.

This is a comparison, not a recommendation. I do not say "use Skia + Reanimated" here. I say: if your device floor, sprite budget, and willingness to build the engine layer above the renderer all align, that is the only credible native GPU path in RN today. The fit analysis is yours to do.

Phaser-in-WebView is a real path for some games. Content-heavy web ports with a finished Phaser game upstream and minimal RN integration ship today and work. The post's argument is about integration shape - "RN as a launcher" - not about whether the path is wrong. Do not confuse the framing with a dismissal.

No comparison against Unity or Godot is attempted here. Native-first engines deploy via a separate runtime and a different store binary. They are outside the scope of "React Native rendering options."

Close

The gap is real and it is shaped. Zero React Native game engines exist off the shelf in 2026. Four partial options exist, each viable inside its own regime, none viable across all of them. I confirmed that, then started writing the layer that would close the gap.

Next Monday's post is the first chapter of the engine I started writing: the architecture decisions I made before any code, why a strict layering with downward-only dependencies is the load-bearing piece, and how it survives an AI-directed build at all.

Originally published at grzegorzotto.dev/blog.

DEV Community: Grzegorz Otto

The Turborepo + Bun + Biome stack behind a 40-package monorepo

Four binaries, not twelve config files

Bun as the whole toolbelt

One turbo.json for 40 packages

Biome: lint and format in one config

One tsconfig base, 40 extends

Releasing in lockstep

The guardrail that ties it together

Limits

Close

Related

I built generator coroutines for my game engine, then didn't use them

The elegant case for TypeScript game coroutines

What I actually built

Reason 1: allocation on the hot path

Reason 2: you can't serialize a paused generator

What won and why

Limits

Where coroutines do belong

Related

Archetype ECS in TypeScript: why I didn't use bitECS or miniplex

What an archetype ECS TypeScript implementation actually decides

The flare-engine code

Component definition

World - storage and mutation

Query - the bitmask match

Why this shape for this engine

The numbers - measured, off-device

Limits - where this choice is wrong

The pattern beyond games

Related

Zero-allocation TypeScript game loops: 60 fps on a mid-range Android phone

The frame budget on a mid-range Android

Plain objects beat classes - zero-allocation TypeScript by construction

One Pool to rule them - twelve lines, three patterns

Scratch state and the module-level linear congruential generator

The render side - atlas batching is part of the allocation story

What the measurements say - and do not

Limits

Close

The React Native game engine gap in 2026 - RNGE, Skia, Phaser-in-WebView, expo-gl

Option 1 - react-native-game-engine (dormant, JS-only)

Option 2 - Phaser 4 in a WebView

Option 3 - expo-gl and react-native-wgpu (primitives, not engines)

Option 4 - Skia + Reanimated

What this means if you want a React Native game engine today

Limits

Close

Option 1 - `react-native-game-engine` (dormant, JS-only)

Option 3 - `expo-gl` and `react-native-wgpu` (primitives, not engines)