DEV Community: Maryan Mats

Why I Stopped Using Enums in TypeScript (I Use `as const` Instead)

Maryan Mats — Mon, 06 Apr 2026 16:39:28 +0000

I used to put enums everywhere.

New project? First thing I'd write — before components, before API types, before anything — was a file called enums.ts. Status codes, user roles, theme variants, HTTP methods, toast types. If it had more than two possible values, it was an enum.

It felt right. Coming from languages where enums are first-class citizens (Rust, C#, Java), TypeScript enums seemed like the obvious tool. Clean syntax. Named constants. Auto-complete in VS Code. What's not to love?

Then one afternoon I opened the compiled JavaScript output of a project I was shipping to production. And I stared at it for a while.

What TypeScript enums compile to (and why it matters)

Here's an innocent enum:

enum Status {
  Idle,
  Loading,
  Success,
  Error,
}

Four values. Clean. Readable. Now here's what TypeScript emits:

var Status;
(function (Status) {
  Status[Status["Idle"] = 0] = "Idle";
  Status[Status["Loading"] = 1] = "Loading";
  Status[Status["Success"] = 2] = "Success";
  Status[Status["Error"] = 3] = "Error";
})(Status || (Status = {}));

An IIFE. A self-invoking function that mutates an object with double assignments. For four strings.

If you've never seen this pattern before, let me unpack what Status[Status["Idle"] = 0] = "Idle" actually does. The inner assignment Status["Idle"] = 0 sets Status.Idle to 0 and returns 0. Then the outer assignment uses that 0 as a key: Status[0] = "Idle". So now Status.Idle === 0 and Status[0] === "Idle".

This is called reverse mapping. TypeScript generates it by default for numeric enums. It means your compiled object is twice the size you'd expect, and it contains entries you almost certainly never asked for.

console.log(Status.Idle);    // 0
console.log(Status[0]);      // "Idle"
console.log(Status["Idle"]); // 0

I've been writing TypeScript for years and I had never once needed Status[0]. Not once. But every numeric enum I ever shipped included reverse mappings, silently doubling the runtime footprint.

The numeric enum footgun

Reverse mapping isn't just a size issue. It's a type safety issue.

Numeric enums are more permissive than most developers expect. In practice, plain numbers can flow into enum-typed parameters more easily than you'd want — especially at runtime boundaries where data comes from outside your type system.

enum Direction {
  Up,    // 0
  Down,  // 1
  Left,  // 2
  Right, // 3
}

function move(dir: Direction) {
  // ...
}

// This is where it gets dangerous — data from outside your app
const dirFromApi = Number(data.direction);
move(dirFromApi as Direction); // looks safe, isn't

The as Direction cast feels reasonable — you're telling TypeScript "I know this is a Direction." But the compiler can't verify that at runtime. If the API returns 5 (a new direction the backend team added that your frontend doesn't know about yet), the cast succeeds silently and your switch statement falls through.

I discovered this the hard way. A colleague passed a raw API response number into a function expecting a Direction. It worked in every test because the API happened to return 0, 1, 2, or 3. Then one day it returned 5, and the switch had no matching case.

No runtime error. No type error. Just wrong behavior in production. The type system gave us a false sense of completeness.

To be fair, this isn't unique to enums — any unchecked as cast can lie to the compiler. The problem is that enums encourage this pattern at boundaries, because raw strings and numbers from APIs don't naturally flow into enum types without a cast. With a union type like "up" | "down" | "left" | "right", the API string either matches or it doesn't — no cast required, no false confidence.

String enums are better — but still weird

Okay, so numeric enums have problems. What about string enums?

enum Theme {
  Light = "light",
  Dark = "dark",
  System = "system",
}

The compiled output is cleaner — no reverse mapping:

var Theme;
(function (Theme) {
  Theme["Light"] = "light";
  Theme["Dark"] = "dark";
  Theme["System"] = "system";
})(Theme || (Theme = {}));

Better. Still an IIFE, but at least the object isn't doubled. And TypeScript correctly rejects Theme.Light === "light" in strict mode — wait, no it doesn't. It actually works. But it gets inconsistent:

const theme: Theme = "light"; // Error: Type '"light"' is not assignable to type 'Theme'

A string enum value is the string "light" at runtime, but TypeScript treats them as distinct types. String enums create a nominal-ish value space — they're not just string literal unions, they're their own branded type. So you can't assign a plain string to a string enum, even when the value is identical. This creates friction at every boundary — API responses, URL params, localStorage, JSON parsing. You end up writing value as Theme casts everywhere, which defeats the purpose of type safety.

// From an API response
const data = await response.json();
const theme = data.theme as Theme; // Trust me bro

// From localStorage
const saved = localStorage.getItem("theme") as Theme; // fingers crossed

Every as Theme is a lie you're telling the compiler. It might be true. It might not. You've just disabled the one thing that was supposed to protect you.

TypeScript enums and tree-shaking

Here's one that really bothered me once I noticed it.

Modern bundlers (Rollup, esbuild, Vite) eliminate unused code through tree-shaking. They analyze your imports and strip anything that isn't referenced. This works best with static structures — plain objects, constants, pure expressions that the bundler can reason about statically.

Enums are generally less optimization-friendly than plain literals or as const objects, because they compile to runtime code (that IIFE) rather than disappearing into the type system. The IIFE mutates a variable, and while some bundlers and minifiers have gotten smarter about recognizing enum patterns in recent years, the optimization is never as clean or reliable as a plain const declaration that a bundler can trivially inline or eliminate.

import { Status } from './enums';

// Only using Status.Error for a single comparison
if (response.status === Status.Error) {
  showToast();
}

With a plain as const object, a bundler can see that Status.Error is the string "error" — it's a static property access on a frozen object. With an enum, the bundler has to trace through the IIFE to reach the same conclusion. Some will. Many won't bother, especially across module boundaries.

With small enums this is trivial. But I've seen codebases with 50+ enums in a shared types package, imported across dozens of components. The cumulative effect — all those runtime objects, all that indirection — adds up in ways that plain objects and literal types simply don't.

const enum — the escape hatch that isn't

TypeScript offers const enum as a solution to the compilation problem:

const enum Status {
  Idle = "idle",
  Loading = "loading",
  Success = "success",
  Error = "error",
}

const current = Status.Loading;
// Compiles to:
const current = "loading"; // inlined!

No IIFE. No runtime object. The values are inlined at compile time. Sounds perfect.

Except:

1. It gets fragile in modern toolchains. If your project uses single-file transpilation — Babel, SWC, esbuild, or any Vite-based pipeline — each file is compiled independently without knowledge of other modules. const enum needs cross-file resolution to inline values, which makes it fragile once your code crosses module or package boundaries. It works fine within a single file, but that's rarely where enums live in real projects.

2. It breaks declaration files. If you're publishing a library, const enum values need to be inlined into the consumer's code. This means the consumer must use the same TypeScript version and configuration. The TypeScript team themselves recommend against const enum in libraries.

3. You can't iterate over it. Since there's no runtime object, Object.values(Status) doesn't work. Need a dropdown of all options? You're maintaining a separate array. That array will drift from the enum eventually. I've seen it happen more times than I can count.

The TypeScript documentation literally has a section called "Const enum pitfalls." When the official docs dedicate a section to pitfalls, that's a signal.

TypeScript enum alternatives: what I use instead

Two patterns. Both native TypeScript. Both compile to exactly what you'd expect.

Pattern 1: `as const` objects (enum replacement)

const Status = {
  Idle: "idle",
  Loading: "loading",
  Success: "success",
  Error: "error",
} as const;

type Status = (typeof Status)[keyof typeof Status];
// type Status = "idle" | "loading" | "success" | "error"

The compiled output:

const Status = {
  Idle: "idle",
  Loading: "loading",
  Success: "success",
  Error: "error",
};

That's it. A plain object. No IIFE. No reverse mapping. Fully tree-shakeable. The type Status is a union of the literal values — which is what you actually wanted from the enum in the first place.

You get everything enums promise and nothing they smuggle in:

function setStatus(status: Status) { /* ... */ }

setStatus("idle");            // works
setStatus("loading");         // works
setStatus("not-a-status");    // Error: Argument of type '"not-a-status"' is not assignable
setStatus(Status.Idle);       // also works

// Iteration works
const allStatuses = Object.values(Status); // ["idle", "loading", "success", "error"]

// Type guard works
function isStatus(value: string): value is Status {
  return Object.values(Status).includes(value as Status);
}

Notice that you can pass either the literal string "idle" or Status.Idle. Both are valid. No as casts needed at boundaries. When your API returns "idle", it's already the correct type. When you read from localStorage, you can validate it with a simple includes check.

Pattern 2: Plain union types

For cases where you don't need a runtime object at all — just type checking:

type Theme = "light" | "dark" | "system";

Compiles to: nothing. Zero bytes. The type is erased completely. If all you need is to constrain a function parameter or a prop, this is the lightest possible solution.

interface Props {
  theme: Theme;
  onThemeChange: (theme: Theme) => void;
}

I use union types when the set of values is small (2-4 options) and I don't need to iterate over them at runtime. For anything larger, or when I need Object.values() / Object.keys(), I use the as const pattern.

Migrating from enum to as const: before and after

Here's a pattern I've refactored out of three different codebases now. API response handling with enums:

Before:

enum ApiStatus {
  Pending = "pending",
  Fulfilled = "fulfilled",
  Rejected = "rejected",
}

interface ApiState<T> {
  status: ApiStatus;
  data: T | null;
  error: string | null;
}

function handleResponse<T>(state: ApiState<T>): string {
  switch (state.status) {
    case ApiStatus.Pending:
      return "Loading...";
    case ApiStatus.Fulfilled:
      return `Got ${state.data}`;
    case ApiStatus.Rejected:
      return `Error: ${state.error}`;
  }
}

After:

const ApiStatus = {
  Pending: "pending",
  Fulfilled: "fulfilled",
  Rejected: "rejected",
} as const;

type ApiStatus = (typeof ApiStatus)[keyof typeof ApiStatus];

interface ApiState<T> {
  status: ApiStatus;
  data: T | null;
  error: string | null;
}

function handleResponse<T>(state: ApiState<T>): string {
  switch (state.status) {
    case ApiStatus.Pending:
      return "Loading...";
    case ApiStatus.Fulfilled:
      return `Got ${state.data}`;
    case ApiStatus.Rejected:
      return `Error: ${state.error}`;
  }
}

The usage code barely changes. The switch statement is identical. The interface is identical. The only difference is the definition — and the compiled output.

But now state.status === "pending" works without a cast. JSON from the API is directly assignable. And your bundler can prove that ApiStatus.Pending is just the string "pending" — no IIFE indirection, no runtime overhead.

The type helper I keep in every project

The (typeof X)[keyof typeof X] line is ugly. I'll admit that. So I use a helper:

type ValueOf<T> = T[keyof T];

Then:

const Status = { Idle: "idle", Loading: "loading" } as const;
type Status = ValueOf<typeof Status>;
// "idle" | "loading"

One line in a types.ts file. Used everywhere. If your team has a shared utility types package, it probably already exists.

When TypeScript enums are still the right choice

I'd be dishonest if I pretended enums are never the right choice. Here's when I still reach for them:

Bit flags. If you genuinely need bitwise operations — file permissions, feature flags with combinations — numeric enums with explicit powers of two are the clearest way to express that:

enum Permission {
  Read = 1 << 0,    // 1
  Write = 1 << 1,   // 2
  Execute = 1 << 2, // 4
}

const userPerms = Permission.Read | Permission.Write; // 3

You can do this with as const objects, but the intent is less clear and you lose the visual pattern of the bitshift syntax.

Codebases that already use them consistently. If your team has 200 enums and everyone understands the conventions, migrating to as const for consistency is a refactor, not an improvement. Don't refactor for ideology. Refactor when it solves a problem.

Quick prototypes. Sometimes I'm sketching an idea at midnight and I just want auto-incrementing numbers for a state machine. enum State { A, B, C, D } is fine. I'll clean it up if it survives till morning.

Quick comparison: enum vs `as const` vs union type

Use case	Best choice	Why
Type safety only, no runtime values needed	Union type	Zero bytes — erased at compile time
Runtime values + iteration (`Object.values`)	`as const` object	Plain JS object, fully tree-shakeable
Bit flags / bitwise operations	`enum`	Clearest intent with `1 << n` syntax
Data from API / localStorage / URL params	`as const` or union type	No cast needed — strings match directly
Publishing a library	Avoid `const enum`	Fragile across package boundaries
Existing codebase with 200 enums	Keep `enum`	Consistency beats ideology

The deeper lesson

This is a pattern I keep running into with TypeScript: the features that feel most like "real programming language features" — enums, namespaces, decorators (the old experimental ones) — are often the ones that age worst. They were designed before the ecosystem settled on ESModules, before bundlers got smart about tree-shaking, before isolatedModules became the default.

The features that age best are the ones that erase completely at compile time: types, interfaces, union types, as const, generics, utility types. They add zero bytes to your bundle because they don't exist at runtime. They're pure type-level constructs that guide the compiler and then disappear.

TypeScript is at its best when it's a layer on top of JavaScript, not a language next to it. Enums blur that line. They introduce runtime behavior that doesn't exist in JavaScript, with semantics that don't quite match any other language. Every other TypeScript feature I've mentioned — as const, union types, keyof typeof — desugars to plain JavaScript you could have written yourself.

That's the property I optimize for now. Not cleverness. Not syntax sugar. Predictable compilation.

I still have enums.ts in an old project. I open it sometimes when I'm feeling nostalgic. Forty-seven enums. Some of them have reverse mappings I'm sure nobody has ever called. They compile to about 3 KB of IIFEs that do absolutely nothing useful. I think of it as a monument to good intentions.

If you're interested in more TypeScript war stories, check out my deep dive into why you probably don't need Zustand — another case of looking under the hood and finding something simpler.

Update: I packaged the as const + union type pattern into ts-safe-enum — a 536-byte defineEnum() function with full type inference, type guards, validation, and reverse lookup. No as const needed, no runtime surprises.

Stop Writing try/catch — Your TypeScript Errors Deserve Types

Maryan Mats — Mon, 06 Apr 2026 16:32:21 +0000

Look at this function signature.

function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

It says: "Give me a string, I'll give you a User." Clean. Typed. Beautiful.

It's also a lie.

That function can throw a TypeError if the network is down. A SyntaxError if the response isn't JSON. A DOMException if the request is aborted. A random string if some dependency deep in the call stack decides to throw "oops". Yes — JavaScript lets you throw literally anything. A string. A number. null. A Promise. undefined.

Your type system sees none of this.

Promise<User> is the happy path. It's the fairy tale version of your function. The real signature — if TypeScript could express it — would be something like Promise<User | throws TypeError | SyntaxError | DOMException | string | unknown>. But TypeScript has no syntax for that. No throws clause. No checked exceptions. No way to encode in the type system what a function does when things go wrong.

And this isn't a bug. It's a deliberate design decision by the same person who made the same decision for the same reasons twenty years earlier.

The man who decided this — twice

Anders Hejlsberg designed C#. Then he designed TypeScript. Neither language has typed exceptions. He explained why in a 2003 Artima interview, and the reasoning applies to both languages word for word.

The versioning problem. If fetchUser declares it throws NetworkError and ParseError, and next month you add retry logic that can throw TimeoutError, every caller breaks. Adding an exception type to a function is a breaking change. In a language like TypeScript, where you import from dozens of npm packages that update independently, this is catastrophic.

The scalability problem. "When you start building big systems where you're talking to four or five different subsystems, you end up having to declare 40 exceptions that you might throw. And once you aggregate that with another subsystem you've got 80 exceptions."

The human problem. Java tried this. Checked exceptions. Every language that runs on the JVM after Java — Scala, Kotlin, Groovy, Clojure — looked at checked exceptions and said no. In practice, Java developers write throws Exception (catching everything) or empty catch {} blocks. The feature designed to force correct error handling instead encouraged ignoring errors.

The TypeScript team closed the throws clause proposal (GitHub issue #13219, 279 comments) as "Not Planned." Not because they didn't think about it. Because they did think about it and decided it was worse than the problem it solves.

So here we are. TypeScript types your data beautifully and is completely blind to your errors. And if you're only using try/catch, you're coding without a safety net in the one place where safety matters most.

`catch (e: unknown)` — the narrowing nightmare

Before TypeScript 4.4, catch (e) gave you e: any. You could write e.message without checking anything. If someone threw a number instead of an Error, your catch block threw another error. Brilliant.

TypeScript 4.4 fixed this with useUnknownInCatchVariables (enabled by default under strict). Now catch (e) gives you e: unknown. Better — but look what you have to do:

try {
  const user = await fetchUser(id);
  await saveToDatabase(user);
} catch (e: unknown) {
  if (e instanceof Error) {
    console.error(e.message);
  } else {
    console.error(String(e));
  }
}

You're narrowing at runtime because the type system has no idea what you caught. And it gets worse.

instanceof Error isn't reliable. In JavaScript, each realm (window, iframe, web worker, Node.js vm module) has its own global objects. An Error created in an iframe fails instanceof Error in the parent window — different Error constructors, different prototype chains. This is so common that TC39 shipped Error.isError() (Stage 4, ES2026) specifically to fix it.

And when you subclass Error in TypeScript targeting ES5, instanceof breaks silently. class HttpError extends Error doesn't set the prototype correctly — you need a manual Object.setPrototypeOf(this, HttpError.prototype) or your catch blocks will miss your custom errors entirely. TypeScript issue #13965 documents this. It's been open since 2017.

So the pattern is: you throw typed errors, you catch unknown, you narrow with instanceof which doesn't work across realms, which doesn't work with subclasses unless you add a workaround, and the whole time the compiler offers zero help. This is the state of the art.

The `async/await` tax

try/catch was designed for synchronous code. One operation, one potential failure. But async/await turned every function into a chain, and now you're wrapping entire blocks:

try {
  const response = await fetch('/api/users');
  const data = await response.json();
  const validated = validateUser(data);
  await saveToDatabase(validated);
} catch (e: unknown) {
  // Which line failed?
  // Was it the network? The JSON parse? The validation? The database?
  // We don't know. One catch block for four completely different failure modes.
  handleError(e);
}

You can nest try/catch blocks inside each other to catch each operation separately. Nobody does this because it looks horrible. Or you can split every await into its own try/catch. Nobody does this either because you end up with 30 lines of error handling for 4 lines of logic.

The result? Most developers write a single catch block that handles everything the same way. "Something went wrong. Please try again." The user sees a generic error. The developer has no idea what actually failed. The type system shrugs.

Every modern language figured this out

Here's what convinced me this isn't just a functional programming trend. The convergence is real.

Rust has no exceptions. Every function that can fail returns Result<T, E>:

fn read_config(path: &str) -> Result<Config, ConfigError> {
    let content = fs::read_to_string(path)?;  // ? returns early on error
    let config = toml::from_str(&content)?;    // same here
    Ok(config)
}

The compiler refuses to compile if you don't handle the Result. The ? operator propagates errors visually — you can see at a glance which lines can fail. The error type is in the signature. Done.

Go returns errors as ordinary values:

user, err := fetchUser(id)
if err != nil {
    return fmt.Errorf("fetching user %s: %w", id, err)
}

Verbose? Yes. But every failure point is visible. No invisible jumps up the call stack. No "which line threw?" mystery.

Swift 6 added typed throws — func load() throws(FileError) — so catch blocks know exactly which errors they're handling.

Zig built error unions into the language syntax — !T means "a value of type T or an error" — with compile-time-known error sets.

Every language designed in the last fifteen years has moved toward errors as values in the type system. Java's checked exceptions are universally considered a failed experiment. The only question left is ergonomics — how do you make error-as-values feel as natural as try/catch?

The fix: return your errors

Here's the simplest version. No libraries. Pure TypeScript. A discriminated union:

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

That's it. Two lines. Now use it:

type FetchError =
  | { type: "NETWORK"; message: string }
  | { type: "PARSE"; raw: string }
  | { type: "NOT_FOUND"; id: string };

async function fetchUser(id: string): Promise<Result<User, FetchError>> {
  let res: Response;
  try {
    res = await fetch(`/api/users/${id}`);
  } catch (e) {
    return { ok: false, error: { type: "NETWORK", message: String(e) } };
  }

  if (res.status === 404) {
    return { ok: false, error: { type: "NOT_FOUND", id } };
  }

  try {
    return { ok: true, value: await res.json() };
  } catch {
    return { ok: false, error: { type: "PARSE", raw: await res.text() } };
  }
}

Now the caller:

const result = await fetchUser("123");

if (!result.ok) {
  switch (result.error.type) {
    case "NETWORK":
      showRetryDialog();
      break;
    case "NOT_FOUND":
      redirect("/404");
      break;
    case "PARSE":
      reportBug(result.error.raw);
      break;
  }
  return;
}

// TypeScript knows result.value is User here
console.log(result.value.name);

Look at what changed. The function signature says Promise<Result<User, FetchError>>. The error types are right there. The caller handles each error type individually — network errors get a retry dialog, 404s get a redirect, parse errors get a bug report. The type system enforces exhaustive handling. If you add a new error type to FetchError, every switch that doesn't handle it gets a compile error.

No instanceof. No unknown. No guessing. The types do the work.

Want better ergonomics? Meet `neverthrow`

The DIY approach works. But chaining operations gets verbose. neverthrow adds map, andThen, and match — the same composition tools that make Rust's Result feel natural:

import { ok, err, Result, ResultAsync, fromThrowable } from 'neverthrow';

const safeJsonParse = fromThrowable(
  JSON.parse,
  (e) => ({ type: "PARSE" as const, message: String(e) })
);

const fetchUser = (id: string): ResultAsync<User, AppError> =>
  ResultAsync.fromPromise(
    fetch(`/api/users/${id}`).then(r => {
      if (!r.ok) throw new Error(`HTTP ${r.status}`);
      return r.json();
    }),
    (e) => ({ type: "NETWORK" as const, message: String(e) })
  );

// Chain operations — errors short-circuit automatically
fetchUser("123")
  .andThen(user => validateAge(user))  // ResultAsync<User, AppError | ValidationError>
  .map(user => user.name)
  .match(
    name => showGreeting(name),
    error => handleError(error)  // called with the FIRST error that occurred
  );

The andThen chain works like a pipeline. If fetchUser fails, validateAge never runs — the error flows straight to match. This is Scott Wlaschin's Railway Oriented Programming: two parallel tracks (success and failure), and the moment something fails, everything switches to the failure track.

And neverthrow's safeTry gives you something close to Rust's ? operator:

import { safeTry } from 'neverthrow';

const program = safeTry(async function* () {
  const user = yield* fetchUser("123").safeUnwrap();
  const orders = yield* fetchOrders(user.id).safeUnwrap();
  const total = orders.reduce((sum, o) => sum + o.amount, 0);
  return ok(total);
});
// ResultAsync<number, FetchError | OrderError>

Each yield* either unwraps the value or returns the error early. The error types accumulate in the union automatically. It reads almost like normal async/await — but every error is typed.

You're already using this pattern (you just don't know it)

This isn't some functional programming experiment. The libraries you use every day already moved to errors-as-values.

Zod has safeParse:

const result = UserSchema.safeParse(data);
if (!result.success) {
  console.log(result.error.issues);  // typed validation errors
} else {
  console.log(result.data);  // typed, validated data
}

That return type is a discriminated union. Success or failure, with typed data in both branches. Zod offers parse (throws) and safeParse (returns) — and the community recommendation is clear: use safeParse.

TanStack Query returns a discriminated union from every useQuery:

const { status, data, error } = useQuery({ queryKey: ['user'], queryFn: fetchUser });

if (status === 'success') {
  // data is User — not User | undefined
}
if (status === 'error') {
  // error is Error — guaranteed
}

The status field narrows the entire result type. This is the same pattern as Result<T, E> — just shaped as a React hook.

React Router / Remix uses thrown responses for route-level errors, then catches them in ErrorBoundary components — separating the happy path (component) from the error path (boundary) structurally.

The ecosystem is converging. The only thing left is connecting the dots in your own code.

Eric Lippert's razor: most of your catch blocks shouldn't exist

Eric Lippert, former C# compiler team member, classified exceptions into four categories. This framework changed how I think about every catch block I write:

Fatal — OutOfMemoryError, stack overflow. You can't recover. Don't catch these.
Boneheaded — TypeError, ReferenceError. These are bugs in your code. Fix the bug, don't catch the symptom.
Vexing — JSON.parse throwing on invalid input. A non-exceptional condition forced through an exception API. Use safeParse instead.
Exogenous — Network failures, file not found. External conditions you can't prevent. This is the only category where catch is appropriate.

Most catch blocks in production code handle vexing or boneheaded exceptions. The vexing ones should be replaced with Result-returning alternatives. The boneheaded ones should be fixed, not caught. Only exogenous exceptions — things genuinely outside your control — deserve a catch block.

When I applied this framework to a codebase I was working on, about 70% of the try/catch blocks either (a) caught a validation error that should have been a return value, or (b) caught a bug that should have been fixed upstream. The remaining 30% were legitimate — network calls, file I/O, third-party APIs with undocumented failure modes.

When `try/catch` is still the right tool

I'm not saying delete every catch in your codebase. There are places where try/catch is genuinely the best option:

At the boundary with libraries that throw. You don't control how fetch, JSON.parse, or your ORM surfaces errors. Wrap them at the boundary, convert to Result, and use typed errors from that point inward:

const safeFetch = (url: string): ResultAsync<Response, NetworkError> =>
  ResultAsync.fromPromise(
    fetch(url),
    (e) => new NetworkError(String(e))
  );

One try/catch at the edge. Typed errors everywhere else.

In top-level error boundaries. React's ErrorBoundary, Express's error middleware, a global process.on('unhandledRejection') — these are safety nets. They should exist. They catch the things you didn't anticipate.

For truly exceptional conditions. If your database connection drops mid-transaction, the appropriate response might be to throw, let the framework catch it, and return a 500. Not everything needs to be a typed Result.

The rule of thumb: use try/catch at the edges, use Result in the core. External world talks to your code through boundaries where exceptions get converted into typed errors. Your domain logic — validation, business rules, data transformation — returns errors as values. The type system covers the part that matters most.

The pattern across everything I've written

I keep finding the same blind spot in different shapes.

In my enums article, it was TypeScript generating runtime code (IIFEs, reverse mappings) that doesn't match what developers expect. In my booleans article, it was the type system allowing impossible states because booleans destroy information. Here, it's function signatures hiding half the truth because TypeScript can't express what a function does when it fails.

The common thread: TypeScript is at its best when it makes the wrong thing impossible. But with try/catch, it can't even see the wrong thing. The function signature says "returns User." Reality says "returns User or explodes in 15 different ways, and you'll find out which one at 3 AM."

Returning errors as values doesn't add complexity. It moves complexity from runtime to compile time — from "we'll find out in production" to "the compiler told me at 2 PM on a Tuesday." That's a trade I'll take every time.

Anders Hejlsberg was right to reject checked exceptions. Java proved they don't work as a language feature. But the problem they tried to solve — making error paths visible and type-safe — is real. The answer isn't forcing developers to declare exceptions. It's giving them types expressive enough to return errors as values. TypeScript already has those types. We just need to use them.

If you liked this, check out why I stopped using booleans — same idea, different blind spot. And if you want to see what happens when you push TypeScript's type system to its absolute limits, my framework design series goes there.

Update: I packaged these patterns into ts-safe-result — a tiny (< 1KB), zero-dependency Result<Value, Error> type for TypeScript with ok, err, map, flatMap, match, tryCatch, tryAsync, and more. If you want to start using typed errors in your codebase today, it's ready to go.

Stop Using Booleans Everywhere — Use Union Types Instead

Maryan Mats — Mon, 06 Apr 2026 16:31:28 +0000

I spent four hours debugging a loading spinner.

The UI showed a spinner and an error message at the same time. A red banner saying "Something went wrong" floating right next to an animated circle telling the user to wait. The state that caused it:

{ isLoading: true, isError: true, data: null }

Three booleans. Eight possible combinations. And somehow, the app landed on the one combination that should never exist. Loading and errored — simultaneously. The fix was a one-liner. But the real fix — the one that would have prevented this bug from ever being possible — was not using booleans in the first place.

This isn't a TypeScript thing. This isn't a React thing. This is a programming thing. And it has a name.

The call that broke my brain: `createUser("John", true, false, true)`

Before we talk types, let's talk about the moment booleans become unreadable.

createUser("John", true, false, true);

What does this do? Is it (name, isAdmin, isActive, sendEmail)? Or (name, sendEmail, isAdmin, verified)? You have no idea. I have no idea. The person who wrote this had the docs open. You don't.

This anti-pattern has a name: the Boolean Trap. Ariya Hidayat coined it in 2011 after years of API design at Trolltech (the Qt team), and it shows up everywhere:

widget.repaint(false);        // "don't repaint"? No — repaint without erasing
menu.stop(true, false);       // jQuery: clearQueue=true, jumpToEnd=false
slider = new Slider(true);    // true = horizontal. Obviously.

Martin Fowler called these flag arguments and wrote an entire refactoring catalog entry to eliminate them. Robert C. Martin put it bluntly in Clean Code: "Boolean arguments loudly declare that the function does more than one thing."

The Qt team went further. When they redesigned the API from Qt 3 to Qt 4, they replaced boolean parameters with enums across the board:

// Qt 3 — what does false mean?
str.replace("%USER%", user, false);

// Qt 4 — self-documenting
str.replace("%USER%", user, Qt::CaseInsensitive);

That wasn't a cosmetic change. That was an engineering team saying "we shipped an API that caused too many bugs, and the root cause was booleans."

This bug has a name: Boolean Blindness

In 2011, Robert Harper — professor at Carnegie Mellon — published a blog post that gave this entire class of bugs a name: Boolean Blindness. The term was coined by his PhD student Dan Licata during a functional programming course.

The core insight came from Conor McBride (University of Strathclyde), and it's deceptively simple:

A boolean is a single bit. true or false. When you evaluate x === 0 and get true, the result carries zero information about what was tested. You have to remember where that true came from and what it meant. The moment you pass it to another function, you've separated the answer from the question.

Pattern matching preserves the information. Booleans destroy it.

// Boolean blindness: the "true" means nothing on its own
const isEmpty = items.length === 0;
if (isEmpty) {
  // you "know" items is empty — but the type system doesn't
  // nothing stops you from accessing items[0] here
}

// Pattern matching: information is preserved structurally
type ItemsState =
  | { status: "empty" }
  | { status: "loaded"; items: Item[] };

if (state.status === "empty") {
  // items doesn't even exist here — impossible to misuse
}

Harper's argument wasn't aesthetic. It was type-theoretic. A boolean is a computation result that happens to correlate with a proposition, but it is not the proposition itself. When you branch on a boolean, the type system learns nothing. When you branch on a discriminated union, the type system narrows.

That narrowing is the difference between hoping your code is correct and proving it.

The math that should scare you: 2^n impossible states

Here's the arithmetic that convinced me to stop.

Every boolean you add to a state object doubles the number of possible states. One boolean: 2 states. Two booleans: 4. Three: 8. Five: 32.

Now count how many of those states are valid.

// Three booleans
type State = {
  isLoading: boolean;
  isError: boolean;
  data?: User;
}

Eight possible combinations. Let's list them:

`isLoading`	`isError`	`data`	Valid?
`false`	`false`	`undefined`	Yes — idle
`true`	`false`	`undefined`	Yes — loading
`false`	`false`	`User`	Yes — success
`false`	`true`	`undefined`	Yes — error
`true`	`true`	`undefined`	No — loading AND error?
`true`	`false`	`User`	No — loading but has data?
`false`	`true`	`User`	No — error but has data?
`true`	`true`	`User`	No — everything at once?

Four valid states. Four impossible states. That's a 50% defect rate in your type definition. And nothing in the type system prevents you from creating the impossible ones.

Now here's the same thing with a union type:

type State =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: Error };

Four states. All valid. You physically cannot construct { status: "loading", error: new Error() } — the type system rejects it. The impossible states don't just "not happen" — they don't exist.

Kyle Shevlin calls this principle "Enumerate, Don't Booleanate." Richard Feldman demonstrated it at Elm Conf with his talk "Making Impossible States Impossible." Yaron Minsky at Jane Street made it a mantra: "Make illegal states unrepresentable."

They all arrived at the same conclusion from different starting points. That should tell you something.

This isn't a TypeScript thing — every language figured it out

What convinced me this isn't just a frontend trend is that every typed language has arrived at the same solution independently.

Rust: enums are the default

Rust doesn't have a separate "union type" concept. Its enum is the union type — and it's the idiomatic way to model state:

// The Rust community would reject this in code review
fn rotate_block(&self, block: &mut Block, timed_out: bool)
self.rotate_block(&mut block, true)?;  // what does true mean?

// Idiomatic Rust
enum RotateReason { Full, Timeout }
fn rotate_block(&self, block: &mut Block, reason: RotateReason)
self.rotate_block(&mut block, RotateReason::Timeout)?;

Rust's linter, Clippy, has a dedicated rule — fn_params_excessive_bools — that flags functions with too many boolean parameters. It's not a style preference. It's in the official pedantic lint group.

Python: keyword-only arguments and linting rules

Python can't enforce union types the same way, but it has a different escape hatch — forcing callers to name their booleans:

# Bad — what does True mean?
round_number(3.5, True)

# Python's fix: keyword-only arguments (the * separator)
def round_number(value: float, *, up: bool) -> float: ...
round_number(3.5, up=True)  # now it's readable

The Ruff linter (Python's fastest linter, replacing flake8) ships three dedicated rules for boolean traps: FBT001, FBT002, FBT003 — flagging boolean type hints, default values, and positional boolean arguments respectively.

Swift and Kotlin: the language enforces readability

Swift builds argument labels into the language syntax. You can't write createUser("John", true, false) in Swift — every parameter gets a label at the call site by default:

createUser(name: "John", isAdmin: true, sendEmail: false)

Kotlin took the same approach with named parameters and official guidance that says: "Do not use boolean types as arguments. Create a separate function with a descriptive name."

Even .NET has official guidelines

Microsoft's .NET Framework Design Guidelines state it explicitly:

And they note that an enum is the same memory size as a boolean in .NET (both backed by Int32). There's no performance argument. Only a readability and correctness argument — and booleans lose both.

The libraries already know this

This isn't theoretical. The most respected libraries in the ecosystem already moved away from booleans.

TanStack Query returns a discriminated union. The status field ("pending", "error", "success") narrows the entire result type — when you check status === "success", TypeScript knows data is TData, not TData | undefined. The boolean helpers (isPending, isError, isSuccess) exist for convenience, but the architecture is union-first.

XState is built entirely on the principle that state is a discriminated union. Not just valid states — valid transitions. You can't go from idle to success without passing through loading. The state machine is the type.

React component libraries universally migrated from boolean props to variant props:

// 2018 — boolean prop soup
<Button primary danger warning disabled loading>Click</Button>
// What color is this button? Red? Green? Yellow? All three?

// 2026 — every serious library
<Button variant="danger" state="loading">Click</Button>
// Exactly one variant. Exactly one state. No ambiguity.

Chakra UI, Radix, shadcn/ui, Headless UI — they all made the same migration. Not because unions are trendy. Because boolean props created impossible combinations that their users kept hitting.

The gotcha nobody warns you about

If you're sold on discriminated unions in TypeScript, here's the trap that will bite you on day one. Kyle Shevlin wrote about this, and it's subtle.

Do not destructure a discriminated union at the top level. It breaks narrowing.

// BAD — TypeScript loses the connection between status and data
const { status, data, error } = fetchResult;
if (status === "success") {
  console.log(data.name);  // Error! data might be undefined
}

// GOOD — narrow first, then access
const result = fetchResult;
if (result.status === "success") {
  console.log(result.data.name);  // Works — TypeScript narrowed the type
}

The moment you destructure, status, data, and error become independent variables. TypeScript can no longer reason about their relationship. You need to keep the object intact so that checking status narrows the entire type.

This is the single most common mistake I see when people adopt discriminated unions. Once you know it, you never hit it again. But the first time? It's confusing.

When booleans are still fine

I'm not saying booleans are evil. I'm saying they're overused. Here's when they're the right tool:

Truly binary, independent state. A checkbox is checked or unchecked. A modal is open or closed. A feature flag is on or off. If the concept is genuinely binary and doesn't combine with other booleans, a single boolean is perfectly clear.

const [isOpen, setIsOpen] = useState(false);

I'm not going to write type DialogState = "open" | "closed" for this. That's over-engineering. The name isOpen already communicates the meaning. There's no second boolean to combine with. No impossible state to prevent.

Fowler's rule of thumb. Martin Fowler notes that a boolean parameter is acceptable when its value is derived from context — not specified by the caller:

// Fine — the boolean comes from existing state
const canEdit = user.role === "admin" && !document.locked;

// Not fine — the boolean is a mystery at the call site
processDocument(doc, true, false);

The signal is this: if you have two or more booleans that interact, or if a boolean appears as a function parameter, or if you're writing if (isA && !isB && isC) — stop. You're modeling a state machine with bits. Use a union type. Let the type system do the work.

The deeper pattern

I keep coming back to the same principle across every article I write. It showed up when I looked inside Zustand and found useSyncExternalStore. It showed up when I dropped TypeScript enums for as const. It showed up when I realized render props aren't dead.

The principle is this: the best tools are the ones that make the wrong thing impossible, not just the right thing possible.

Booleans make the right thing possible. Union types make the wrong thing impossible. That's not a subtle difference. That's the difference between hoping your code works and knowing it does.

Three booleans: 8 states, 4 impossible. A union with 4 variants: 4 states, 0 impossible. The math is that simple. The bugs you'll never write — those are the ones that matter most.

Robert Harper wrote about Boolean Blindness in 2011. The Qt team redesigned their entire API to eliminate boolean parameters in 2005. Martin Fowler, Robert C. Martin, and the Rust, Python, Swift, and Kotlin communities all independently arrived at the same conclusion. At some point, when every language and every respected engineer tells you the same thing, maybe it's worth listening.

If this resonated, check out why I stopped using TypeScript enums — same energy, different target. And if you want to see what happens when you push type safety even further, my three-part series on building a web framework goes deep into compilers, signals, and the limits of static analysis.

Render Props Are Not Dead — React Hooks Didn't Replace What Actually Matters

Maryan Mats — Mon, 06 Apr 2026 16:27:09 +0000

I'm going to say something that gets me looks in code reviews.

I still use render props. Regularly. In new code. In 2026. Not because I'm nostalgic, and not because I missed the hooks migration. I use them because they solve problems that hooks genuinely cannot solve — and because the React community threw away a powerful architectural pattern based on a misunderstanding of what hooks actually replaced.

Here's what hooks replaced: the use of render props for sharing stateful logic between components. That's it. That's the thing hooks made obsolete. The <MouseTracker> example from the old React docs, where you wrapped a component in a render prop just to get access to x and y coordinates — yes, useMousePosition() is obviously better for that.

But render props were never just about sharing logic. They were about giving the consumer control over rendering while the provider controls behavior. That's a fundamentally different concern. And hooks don't touch it.

The thing nobody talks about: Container/Presentational separation

Remember the Container/Presentational pattern? Dan Abramov wrote about it in 2015, then half-retracted it in 2019 saying hooks made it unnecessary. And technically, hooks did eliminate the need for class-based container components that existed solely to hold state.

But the principle behind Container/Presentational — separating what happens from what it looks like — didn't go away. It's one of the most useful architectural boundaries you can draw in a React application. And render props are still the cleanest way to express it.

// The container: manages behavior, knows nothing about UI
function Combobox<T>({ items, onSelect, children }: {
  items: T[];
  onSelect: (item: T) => void;
  children: (props: {
    inputProps: React.InputHTMLAttributes<HTMLInputElement>;
    listProps: React.HTMLAttributes<HTMLUListElement>;
    items: T[];
    highlightedIndex: number;
    isOpen: boolean;
  }) => React.ReactNode;
}) {
  const [query, setQuery] = useState('');
  const [isOpen, setIsOpen] = useState(false);
  const [highlightedIndex, setHighlightedIndex] = useState(-1);

  const filtered = items.filter(/* ... */);

  const inputProps = {
    value: query,
    onChange: (e: React.ChangeEvent<HTMLInputElement>) => setQuery(e.target.value),
    onFocus: () => setIsOpen(true),
    onKeyDown: handleKeyDown,
    role: 'combobox' as const,
    'aria-expanded': isOpen,
  };

  return <>{children({ inputProps, listProps, items: filtered, highlightedIndex, isOpen })}</>;
}

The Combobox manages keyboard navigation, filtering, ARIA attributes, open/close state. It has zero opinions about markup. Now the consumer:

<Combobox items={users} onSelect={handleSelect}>
  {({ inputProps, items, highlightedIndex, isOpen }) => (
    <div className="relative">
      <input {...inputProps} className="border rounded px-3 py-2" />
      {isOpen && (
        <ul className="absolute mt-1 shadow-lg rounded">
          {items.map((user, i) => (
            <li
              key={user.id}
              className={i === highlightedIndex ? 'bg-blue-100' : ''}
            >
              <img src={user.avatar} className="w-6 h-6 rounded-full" />
              <span>{user.name}</span>
              <Badge role={user.role} />
            </li>
          ))}
        </ul>
      )}
    </div>
  )}
</Combobox>

Try doing this with a hook. You'd get useCombobox() that returns state and handlers — fine. But the consumer still needs to wire everything together manually: the input, the list, the items, the highlight styles, the conditional rendering. The hook gives you data. The render prop gives you data and a rendering boundary — a clear place where the container ends and the presentation begins.

This is why Downshift, the library that basically invented this pattern for accessible comboboxes, still ships both the hook API (useCombobox, useSelect) and the render prop API. Kent C. Dodds didn't keep the render prop version out of nostalgia. He kept it because for complex rendering delegation, it's the better abstraction.

The real reason render props survive: inversion of control

There's a design principle that explains why render props refuse to die. It's called inversion of control, and it's the difference between a library that does things for you and a library that does things through you.

Without inversion of control, components accumulate config props:

<Autocomplete
  items={items}
  renderItem={renderItem}
  renderEmpty={renderEmpty}
  renderLoading={renderLoading}
  maxVisible={10}
  filterFn={customFilter}
  sortFn={customSort}
  groupBy={groupByCategory}
  showAvatar={true}
  avatarSize="sm"
  highlightMatch={true}
  // ... it never ends
/>

Every new use case demands a new prop. The component becomes a configuration object with JSX syntax. I've seen components with 40+ props. They're untestable, they're rigid, and every new feature request means modifying the component internals.

Render props invert this. Instead of configuring what the component does, you tell it what to render:

<Autocomplete items={items}>
  {({ inputProps, results, isOpen, highlightedIndex }) => (
    <div>
      <SearchInput {...inputProps} />
      {isOpen && (
        <ResultsList>
          {results.length === 0 ? (
            <EmptyState query={inputProps.value} />
          ) : (
            results.map((item, i) => (
              <ResultCard
                key={item.id}
                item={item}
                highlighted={i === highlightedIndex}
              />
            ))
          )}
        </ResultsList>
      )}
    </div>
  )}
</Autocomplete>

The Autocomplete component didn't need to know about EmptyState, ResultCard, SearchInput, avatars, grouping, or highlight matching. The consumer brought all of that. The component stayed simple — it manages filtering, keyboard navigation, and ARIA. Nothing else.

This is the pattern that Headless UI, Base UI, Ark UI, and TanStack Table all use today. It's not legacy. It's the architecture of the most respected component libraries in the React ecosystem right now.

What hooks literally cannot do

I'm not being provocative here. There are concrete technical limitations.

You can't call hooks conditionally

This is the rules of hooks. You can't put a useEffect inside an if statement. You can't call useState after an early return. The React documentation is explicit about this — hooks must be called in the same order on every render.

But you can conditionally render a component. And if that component uses hooks internally, the hooks only run when the component mounts.

// This violates rules of hooks:
function Page({ showAnalytics }) {
  if (showAnalytics) {
    usePageView('/dashboard'); // ILLEGAL — conditional hook call
  }
  return <Dashboard />;
}

// This is perfectly fine:
function PageView({ path }) {
  usePageView(path); // Always runs when mounted — no violation
  return null;
}

function Page({ showAnalytics }) {
  return (
    <>
      {showAnalytics && <PageView path="/dashboard" />}
      <Dashboard />
    </>
  );
}

The PageView component is essentially a render prop that returns nothing — a renderless component. When showAnalytics is false, it doesn't mount, so usePageView never runs. No wasted event listeners. No wasted network requests.

This pattern is everywhere in real codebases. You need a scroll listener only when a certain panel is open? Wrap the hook in a component, render it conditionally. You need an intersection observer only for items that are close to the viewport? Same pattern.

You can't use hooks inside `.map()`

// This is illegal:
function List({ items }) {
  return items.map(item => {
    const [expanded, setExpanded] = useState(false); // VIOLATION
    return <div key={item.id}>...</div>;
  });
}

// This is fine — each component instance has its own hook state:
function ListItem({ item }) {
  const [expanded, setExpanded] = useState(false);
  return <div>...</div>;
}

function List({ items }) {
  return items.map(item => <ListItem key={item.id} item={item} />);
}

You might say "just extract a component" — and yes, that's the solution. But notice: the moment you extract a component to hold per-item state, you've created a container/presentational boundary. The render prop pattern just makes that boundary explicit and reusable.

A hook returns data. It doesn't control when you render.

This is the subtle one. A hook like useTransition from React Spring returns interpolated values. But the library needs to control the rendering lifecycle — it needs to call your render function for entering items, leaving items, and updating items at specific moments during the animation.

const transitions = useTransition(items, {
  from: { opacity: 0, y: -10 },
  enter: { opacity: 1, y: 0 },
  leave: { opacity: 0, y: 10 },
});

return transitions((style, item) => (
  <animated.div style={style}>
    {item.text}
  </animated.div>
));

That transitions() call is a render prop in disguise. React Spring calls your function once for each item in each animation phase — enter, leave, update. You can't replicate this with a pure hook because the hook can't control when your render function executes for each individual item.

The same applies to react-virtualized, TanStack Table's flexRender(), and any library where the rendering order is determined by the library, not by you.

The libraries that chose render props in 2025-2026

This isn't history. These are active decisions by major libraries.

Headless UI v2 (Tailwind Labs) uses children-as-a-function as its primary API. Every component — Listbox, Combobox, Menu, Dialog — exposes state through render props:

<Listbox value={selected} onChange={setSelected}>
  {({ open }) => (
    <>
      <ListboxButton>{selected.name}</ListboxButton>
      {open && (
        <ListboxOptions>
          {people.map(person => (
            <ListboxOption key={person.id} value={person}>
              {({ focus, selected }) => (
                <div className={focus ? 'bg-blue-100' : ''}>
                  {selected && <CheckIcon />}
                  {person.name}
                </div>
              )}
            </ListboxOption>
          ))}
        </ListboxOptions>
      )}
    </>
  )}
</Listbox>

The { open }, { focus, selected } — that's state that lives inside the component. You can't access it from outside with a hook because it's scoped to the component instance. The render prop is the only API that exposes it cleanly.

Base UI v1.0 (MUI, released December 2025) explicitly chose a render prop over Radix's asChild pattern. Their reasoning: better TypeScript inference, more explicit prop merging, easier debugging. They built an entire useRender hook to power this system. This is a brand-new architectural decision, not a legacy holdover.

TanStack Table uses flexRender() — a function that takes a column definition (which can be a function) and calls it with cell data. Every cell in every row is rendered through what is essentially a render prop.

Downshift still ships both hooks and render props. The hooks are recommended for new code, but the render prop API isn't deprecated — because for some use cases, it's genuinely better.

Children as a function — the underrated variant

There are two ways to pass a render prop: as a named prop (render, renderItem) or as children. The children-as-a-function pattern gets less love, partly because of an old American Express blog post calling it an antipattern. Their argument: children doesn't communicate intent like a named prop does.

That's fair for complex cases. But for simple state exposure, children-as-a-function is cleaner than anything else:

<Toggle initial={false}>
  {({ on, toggle }) => (
    <button onClick={toggle}>
      {on ? 'Enabled' : 'Disabled'}
    </button>
  )}
</Toggle>

Compare with the hook version:

function ToggleButton() {
  const { on, toggle } = useToggle(false);
  return (
    <button onClick={toggle}>
      {on ? 'Enabled' : 'Disabled'}
    </button>
  );
}

For this case, the hook is better — simpler, no nesting, direct. I'm not arguing otherwise.

But here's where children-as-a-function wins: when you need the same behavior with different UIs in the same tree.

<AuthGate>
  {({ user, isAuthenticated, login, logout }) => (
    <>
      <Header>
        {isAuthenticated
          ? <UserMenu user={user} onLogout={logout} />
          : <LoginButton onClick={login} />
        }
      </Header>
      <Sidebar>
        {isAuthenticated
          ? <UserProfile user={user} />
          : <GuestPrompt onLogin={login} />
        }
      </Sidebar>
    </>
  )}
</AuthGate>

With a hook, you'd call useAuth() in the parent, then pass everything down as props. Which works — but now Header and Sidebar both receive auth props they only need for rendering decisions. The render prop version scopes the auth state to exactly where it's used.

And here's the bridge that most people miss — you can create a render prop component from any hook in one line:

const AuthGate = ({ children }) => children(useAuth());

That's it. Hook inside, render prop outside. Best of both worlds.

The container pattern, revisited

Let me come back to the container/presentational split, because I think this is where the real architectural value lives.

When hooks arrived, the narrative was: "You don't need container components anymore. Just call useData() in your component and you're done." And for small components, that's true. A useUser() hook in a ProfileCard component is clean and simple.

But as applications grow, this "just use hooks" approach creates a specific problem: your components become tangled mixtures of behavior and presentation.

function UserDashboard() {
  const { user } = useAuth();
  const { data: projects } = useQuery('projects', fetchProjects);
  const { data: notifications } = useQuery('notifications', fetchNotifications);
  const [activeTab, setActiveTab] = useState('projects');
  const [sidebarOpen, setSidebarOpen] = useState(true);
  const isMobile = useMediaQuery('(max-width: 768px)');

  useEffect(() => {
    if (isMobile) setSidebarOpen(false);
  }, [isMobile]);

  // 200 lines of JSX mixing layout, data, and interaction logic
}

Seven hooks. Multiple data sources. UI state mixed with server state mixed with responsive behavior. This component is doing everything. Testing it means mocking auth, mocking two API endpoints, mocking window resize, and rendering the full UI to check any single behavior.

Now with a render prop container:

function DashboardContainer({ children }: {
  children: (props: {
    user: User;
    projects: Project[];
    notifications: Notification[];
    activeTab: string;
    setActiveTab: (tab: string) => void;
    sidebarOpen: boolean;
    toggleSidebar: () => void;
  }) => React.ReactNode;
}) {
  const { user } = useAuth();
  const { data: projects = [] } = useQuery('projects', fetchProjects);
  const { data: notifications = [] } = useQuery('notifications', fetchNotifications);
  const [activeTab, setActiveTab] = useState('projects');
  const [sidebarOpen, setSidebarOpen] = useState(true);
  const isMobile = useMediaQuery('(max-width: 768px)');

  useEffect(() => {
    if (isMobile) setSidebarOpen(false);
  }, [isMobile]);

  return (
    <>
      {children({
        user,
        projects,
        notifications,
        activeTab,
        setActiveTab,
        sidebarOpen,
        toggleSidebar: () => setSidebarOpen(prev => !prev),
      })}
    </>
  );
}

The same hooks live in the container. But now the presentation is a pure function of props — no hooks, no effects, no state management. Just JSX:

<DashboardContainer>
  {({ user, projects, notifications, activeTab, setActiveTab, sidebarOpen, toggleSidebar }) => (
    <div className="flex h-screen">
      {sidebarOpen && <Sidebar user={user} notifications={notifications} />}
      <main className="flex-1">
        <TopBar onToggleSidebar={toggleSidebar} user={user} />
        <TabBar active={activeTab} onChange={setActiveTab} />
        {activeTab === 'projects' && <ProjectGrid projects={projects} />}
        {activeTab === 'notifications' && <NotificationList items={notifications} />}
      </main>
    </div>
  )}
</DashboardContainer>

The presentation function is trivially testable — pass in mock data, check the output. The container is testable independently — does it fetch the right data, does it respond to mobile breakpoints. The boundary between them is explicit, enforced by the render prop signature.

You can achieve this separation with a custom hook. But the hook doesn't enforce the boundary — nothing stops the next developer from adding useState to the "presentational" component. The render prop makes the architecture visible in the code structure itself.

Real downsides — the honest ones

I promised honest downsides, and "it looks weird" doesn't count. Here are the real ones.

The nesting problem is real

If you compose multiple render props, you get this:

<AuthProvider>
  {(auth) => (
    <ThemeProvider>
      {(theme) => (
        <FeatureFlags>
          {(flags) => (
            <LocaleProvider>
              {(locale) => (
                <App auth={auth} theme={theme} flags={flags} locale={locale} />
              )}
            </LocaleProvider>
          )}
        </FeatureFlags>
      )}
    </ThemeProvider>
  )}
</AuthProvider>

Four levels of nesting for four providers. With hooks, this is just:

function App() {
  const auth = useAuth();
  const theme = useTheme();
  const flags = useFeatureFlags();
  const locale = useLocale();
  // ...
}

There's no arguing that the hook version is more readable here. If you need to compose more than two render props, hooks win on ergonomics. For providers and context, hooks are simply the better tool.

DevTools get noisy

Every render prop component adds a layer to the React DevTools component tree. If you have deeply nested render props, the tree becomes harder to navigate. Anonymous functions show as <Unknown> unless you name them.

// Shows as <Unknown> in DevTools
<Toggle>{({ on }) => <span>{on}</span>}</Toggle>

// Shows as <ToggleView> in DevTools
<Toggle>{function ToggleView({ on }) { return <span>{on}</span>; }}</Toggle>

It's solvable, but it's friction that hooks don't have.

TypeScript generics get awkward

Typing a generic render prop requires the <T extends unknown> workaround because the TSX parser confuses <T> with a JSX tag:

// Syntax error — looks like a JSX tag
const List = <T>(props: ListProps<T>) => { ... }

// Works — the constraint disambiguates
const List = <T extends unknown>(props: ListProps<T>) => { ... }

And typing children as a function requires a custom interface — ReactNode doesn't include functions:

interface Props<T> {
  items: T[];
  children: (item: T) => React.ReactNode; // ReactNode alone won't work
}

It's not hard once you know the patterns. But it's a stumbling block for developers who haven't encountered it before.

Inline functions and memoization

An inline render function creates a new reference every render, which breaks React.memo:

// New function reference every render — defeats memo
<DataList renderItem={(item) => <Card item={item} />} />

The fix is useCallback or extracting the function. And in 2026, the React Compiler handles this automatically — it memoizes inline functions as part of its optimization pass. So this downside is shrinking. But if you're not on the React Compiler yet, it's worth knowing.

When I reach for render props vs hooks

Scenario	I use	Why
Sharing stateful logic between components	Custom hook	That's literally what hooks are for
Context/provider values	Hook (`useContext`)	Flat, composable, no nesting
Giving consumers control over rendering	Render prop	Inversion of control — hook can't do this
Container/Presentational separation	Render prop	Makes the architecture boundary visible
Conditional hook execution	Renderless component	Rules of hooks escape hatch
Per-item state in lists	Extracted component	Each instance gets its own hooks
Headless UI building	Both	Hook for logic, render prop for UI delegation
Animation lifecycle rendering	Render prop/callback	Library controls when your render runs

The pattern I keep coming back to: hooks for logic, render props for rendering control. They're complementary, not competing.

The one-liner bridge

If this article convinced you that render props have value but you don't want to rewrite your hooks, here's the bridge:

// Turn any hook into a render prop component
const Toggle = ({ children, ...props }) => children(useToggle(props));
const Auth = ({ children }) => children(useAuth());
const MediaQuery = ({ query, children }) => children(useMediaQuery(query));

One line each. Hook manages state. Component exposes it via children. You can use the hook directly when you want, and the render prop version when you need inversion of control or conditional rendering.

This is how modern libraries work. Downshift has useCombobox and <Downshift>. They're not alternatives — they're the same logic with different interfaces for different use cases.

I know render props aren't coming back as the default. Hooks won that war, and for good reason — they're simpler for 80% of use cases. But that other 20%? The cases where you need rendering control, explicit architecture boundaries, or inversion of control? Render props are still the cleanest tool I've found. And every time a new headless UI library ships with a children-as-a-function API, I feel a little vindicated.

If you want another example of looking past the conventional wisdom, check out why I stopped using TypeScript enums — sometimes the "obvious" tool isn't the right one.

You Don't Need Zustand: useSyncExternalStore Is All You Need

Maryan Mats — Mon, 06 Apr 2026 16:25:49 +0000

I love Zustand. Let me get that out of the way. It's one of my favorite libraries in the React ecosystem — simple, fast, well-maintained.

But a few months ago, I dug into Zustand's source code. Not to find bugs or contribute a PR. Just curiosity — "how does it actually work?"

What I found surprised me.

The core of Zustand — the thing that connects your store to React's rendering cycle — is about 5 lines of code. And those 5 lines use a built-in React hook that most developers have never heard of.

// This is essentially what Zustand does (simplified)
const slice = React.useSyncExternalStore(
  store.subscribe,
  () => selector(store.getState()),
  () => selector(store.getInitialState()),
);

That hook is useSyncExternalStore. And once you understand it, you can build your own state management solution — type-safe, SSR-compatible, zero dependencies — in about 30 lines of TypeScript.

More importantly, you'll understand why it exists, what problem it solves, and why every serious state library in the React ecosystem uses it under the hood.

The useState + useEffect bug in React state management

Let me show you a pattern that's in thousands of React codebases right now. It looks correct. It passes code review. It works in development. And it has a subtle, devastating bug.

function useExternalValue() {
  const [value, setValue] = useState(store.getValue());

  useEffect(() => {
    return store.subscribe(() => {
      setValue(store.getValue());
    });
  }, []);

  return value;
}

This is the classic "subscribe to external store" pattern with useState + useEffect. What's wrong with it?

Problem 1: The double render. On mount, useState captures the initial value. Then useEffect fires (after the DOM is painted), subscribes, and immediately reads the store again. If the value changed between render and effect — which is totally possible — you get a flash of stale data followed by a correction. Users see a flicker.

Problem 2: The subscription gap. Between the first render and the useEffect callback, there's a window where store changes are invisible. If the store updates during that gap, you miss the change entirely until the next render.

Problem 3 — the big one: Tearing.

This is the bug that will never show up in your tests but will haunt your users.

What is tearing?

React's rendering is concurrent. It can pause mid-render to handle higher-priority work (like user input), then resume. This is what makes startTransition and Suspense work smoothly — and it's been the default since React 18.

But here's the issue. Imagine 10 components reading from the same store:

React starts rendering. Components 1-4 read store.value = "hello".
React yields — pauses rendering to handle a click event.
During the pause, the store updates: store.value = "world".
React resumes. Components 5-10 read store.value = "world".
React commits. The user sees a UI where some components show "hello" and others show "world".

That's tearing. Half your UI shows one version of reality, half shows another. The term comes from graphics programming — it's like screen tearing when your monitor shows parts of two different frames.

In synchronous rendering (React 17), this couldn't happen because rendering was uninterruptible. Concurrent rendering broke that guarantee for external stores.

The React team spent years trying to solve this. They first built useMutableSource, which tried to maintain concurrent rendering for external stores. It had critical flaws — selector resubscription, Suspense fallback issues, unpredictable behavior. They scrapped it entirely.

The replacement is useSyncExternalStore. The trade-off is in the name: sync. When an external store changes, React renders synchronously (no time-slicing). You lose concurrent rendering for store updates, but you get a guarantee: every component in the tree sees the same snapshot. No tearing. Ever.

How useSyncExternalStore works — three arguments, zero magic

const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?);

Argument	What it does
`subscribe(callback)`	Tell the store to call `callback` when it changes. Return an unsubscribe function.
`getSnapshot()`	Return the current value. Must return the same reference if nothing changed (`Object.is` comparison).
`getServerSnapshot()`	Return the initial value for SSR. Optional — but React throws if you're server-rendering without it.

That's it. No providers. No context. No reducers. No middleware. Three functions.

React calls getSnapshot synchronously during render. If the store changes during a concurrent render, React detects the mismatch (by calling getSnapshot again before committing) and restarts the render synchronously. This is the anti-tearing mechanism.

Building a type-safe React store from scratch

Enough theory. Let's build a store that's:

Type-safe (full TypeScript inference)
SSR-compatible
Supports selectors (subscribe to a slice, not the whole state)
Has no dependencies
Fits in 30 lines

import { useCallback, useSyncExternalStore } from 'react';

type Listener = () => void;

export function createStore<T>(initialState: T) {
  let state = initialState;
  const listeners = new Set<Listener>();

  const getState = () => state;
  const getInitialState = () => initialState;

  const setState = (updater: T | ((prev: T) => T)) => {
    const next = typeof updater === 'function'
      ? (updater as (prev: T) => T)(state)
      : updater;
    if (Object.is(state, next)) return;
    state = next;
    listeners.forEach((l) => l());
  };

  const subscribe = (listener: Listener) => {
    listeners.add(listener);
    return () => listeners.delete(listener);
  };

  function useStore(): T;
  function useStore<S>(selector: (state: T) => S): S;
  function useStore<S>(selector?: (state: T) => S) {
    const sel = selector ?? ((s: T) => s as unknown as S);
    return useSyncExternalStore(
      subscribe,
      useCallback(() => sel(getState()), [sel]),
      useCallback(() => sel(getInitialState()), [sel]),
    );
  }

  return { getState, setState, subscribe, useStore };
}

That's it. 30 lines. Let's use it:

// store.ts
const counterStore = createStore({ count: 0, name: 'My Counter' });

export const { useStore: useCounter, setState: setCounter } = counterStore;

// Counter.tsx
function Counter() {
  const count = useCounter((s) => s.count);
  return (
    <div>
      <span>{count}</span>
      <button onClick={() => setCounter((s) => ({ ...s, count: s.count + 1 }))}>
        +
      </button>
    </div>
  );
}

// Header.tsx — only re-renders when name changes, not count
function Header() {
  const name = useCounter((s) => s.name);
  return <h1>{name}</h1>;
}

The Header component subscribes to s.name. When count changes, getSnapshot returns "My Counter" — the same string reference. Object.is("My Counter", "My Counter") is true. React skips the re-render. No React.memo, no useMemo, no selector memoization libraries. Just Object.is.

Common useSyncExternalStore pitfalls and how to fix them

I wouldn't be honest if I didn't show you where this goes wrong.

Gotcha 1: Returning new objects from selectors

// BUG: new object every call → infinite re-render loop
const { count, name } = useCounter((s) => ({ count: s.count, name: s.name }));

The selector returns a new {} every time. Object.is({}, {}) is false. React thinks the store changed, re-renders, calls the selector again, gets another new object, re-renders again... forever.

Fix: Select primitives individually, or use a shallow comparison wrapper:

// Option 1: separate selectors (simplest)
const count = useCounter((s) => s.count);
const name = useCounter((s) => s.name);

// Option 2: shallow equality (what Zustand does with `useShallow`)
function useStoreShallow<T, S>(store: ..., selector: (s: T) => S): S {
  const prev = useRef<S>();
  return useSyncExternalStore(subscribe, () => {
    const next = selector(getState());
    if (prev.current && shallowEqual(prev.current, next)) return prev.current;
    prev.current = next;
    return next;
  });
}

This is exactly why Zustand has useShallow — it's not a Zustand feature, it's a useSyncExternalStore constraint.

Gotcha 2: Defining subscribe inline

// BUG: new function every render → resubscribes every render
function MyComponent() {
  const value = useSyncExternalStore(
    (cb) => store.subscribe(cb), // new arrow function each render!
    store.getSnapshot,
  );
}

React sees a new subscribe function, unsubscribes from the old one, subscribes with the new one. Every render. Define subscribe outside the component, or wrap it in useCallback.

Gotcha 3: Forgetting `getServerSnapshot`

If you server-render and omit the third argument, React throws:

Missing getServerSnapshot, which is required for server-rendered content.

For browser-only APIs, provide a sensible default:

const isOnline = useSyncExternalStore(
  subscribeOnline,
  () => navigator.onLine,
  () => true, // assume online during SSR
);

Real-world useSyncExternalStore examples

Recipe 1: Online status

const subscribe = (cb: () => void) => {
  window.addEventListener('online', cb);
  window.addEventListener('offline', cb);
  return () => {
    window.removeEventListener('online', cb);
    window.removeEventListener('offline', cb);
  };
};

export function useOnlineStatus() {
  return useSyncExternalStore(subscribe, () => navigator.onLine, () => true);
}

Recipe 2: Media queries (responsive breakpoints without CSS)

export function useMediaQuery(query: string) {
  const subscribe = useCallback((cb: () => void) => {
    const mql = window.matchMedia(query);
    mql.addEventListener('change', cb);
    return () => mql.removeEventListener('change', cb);
  }, [query]);

  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    () => false,
  );
}

// Usage
const isMobile = useMediaQuery('(max-width: 768px)');
const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');

Recipe 3: localStorage with cross-tab sync

This one's my favorite. localStorage has no built-in subscription mechanism — except for the storage event, which fires in other tabs when a value changes. Combined with useSyncExternalStore, you get cross-tab reactive state for free:

export function useLocalStorage<T>(key: string, initial: T) {
  const subscribe = useCallback((cb: () => void) => {
    const onStorage = (e: StorageEvent) => { if (e.key === key) cb(); };
    window.addEventListener('storage', onStorage);
    return () => window.removeEventListener('storage', onStorage);
  }, [key]);

  const getSnapshot = useCallback((): T => {
    const raw = localStorage.getItem(key);
    return raw ? JSON.parse(raw) : initial;
  }, [key, initial]);

  const value = useSyncExternalStore(subscribe, getSnapshot, () => initial);

  const setValue = useCallback((v: T) => {
    localStorage.setItem(key, JSON.stringify(v));
    // Trigger re-render in THIS tab (storage event only fires in other tabs)
    window.dispatchEvent(new StorageEvent('storage', { key }));
  }, [key]);

  return [value, setValue] as const;
}

Now open two tabs. Change the value in one. Watch the other update instantly. No WebSockets. No polling. Just the platform.

How Zustand and Redux use useSyncExternalStore internally

Let me show you where useSyncExternalStore lives in the wild:

Zustand v5 — the useStore hook:

// From zustand/src/react.ts (simplified)
const slice = React.useSyncExternalStore(
  api.subscribe,
  React.useCallback(() => selector(api.getState()), [api, selector]),
  React.useCallback(() => selector(api.getInitialState()), [api, selector]),
);

React-Redux v8 — the useSelector hook:

// Internally uses useSyncExternalStoreWithSelector
return useSyncExternalStoreWithSelector(
  store.subscribe,
  store.getState,
  getServerState,
  selector,
  equalityFn,
);

React-Redux v7 had hundreds of lines of custom subscription logic, manual batching hacks, and complex synchronization code. v8 replaced it all with this hook. The public API (useSelector, useDispatch, Provider) didn't change at all.

TanStack Query, Jotai, Valtio — same story. Different APIs on top, same hook underneath.

The next time someone asks you "Zustand or Redux?", you can answer: "They both use the same React primitive. The question is which API you prefer on top."

When NOT to use useSyncExternalStore

To be fair, there are cases where useSyncExternalStore is the wrong tool:

For React-managed state — useState and useReducer work with concurrent rendering natively. They don't need the sync fallback.
If you already use Zustand/Redux — they call this hook internally. Adding your own layer on top adds complexity for no benefit.
For one-shot reads — if you need a value once (not a subscription), useEffect with a ref is simpler.
For high-frequency updates — scroll position, mouse coordinates, animation frames. At 60+ events per second, you need requestAnimationFrame batching or a coarse-grained getSnapshot (e.g., round to nearest 50px). Raw useSyncExternalStore will trigger 60 re-renders per second.

React state: internal vs external — the mental model

Here's how I think about it now:

useState is for state that React owns. Component-local values, form inputs, UI toggles. React controls when and how these update, and gets full concurrent rendering in return.

useSyncExternalStore is for state that lives outside React. Browser APIs, WebSocket connections, shared stores, third-party SDKs. React can't control when these update, so it trades concurrent rendering for consistency.

The boundary between these two is the boundary between "React's world" and "everything else." Once you see it, you see it everywhere.

Zustand is still great. Redux Toolkit is still great. You should probably keep using them. But now you know what's inside — and if you ever need a tiny, custom store for a specific use case, you know exactly how to build one. In 30 lines.

If you enjoyed this deep dive into React internals, you might like my series on designing a web framework from scratch — where I explored signals, compilers, and why I ultimately abandoned the whole thing.

Why I Stopped Building My JavaScript Framework After 1,500 Lines of Spec

Maryan Mats — Mon, 06 Apr 2026 16:20:46 +0000

In Part 1, I showed you the vision: a web framework where two imports replace twenty, the compiler does the heavy lifting, and islands keep your JavaScript budget honest.

In Part 2, I took you through the technical depth: the Transfer vs. Expression problem, cross-module compiler analysis, TypeScript type hacks, and the growing list of edge cases that made the specification simultaneously more impressive and more terrifying.

Now it's time to tell you why I stopped.

Not because the ideas were bad — they weren't. Not because I lost interest — I didn't. I stopped because I finally understood something that every senior engineer knows but nobody teaches you: the distance between "I know exactly how this should work" and "someone can npm install this" is measured in person-years, not pages.

The spreadsheet of doom

One evening, I opened a fresh document and listed every component of the MVP. Not the hand-wavy "compiler, runtime, server" version from the spec. The actual work:

Component	Estimated effort	Why it's hard
Two-pass cross-module compiler	4-6 months	Scope analysis, closures, async, re-exports, barrel files, circular deps
Signal + derived + effects runtime	2-3 months	Glitch-free batching, dynamic dependency tracking, memory management
`.mut()` with Immer-like drafts	1-2 months	Structural sharing, proxy traps, rollback on throw
Hydration engine	2-3 months	Tree walking, browser normalization, comment markers, extension resilience
SSR pipeline	2-3 months	Async components, streaming, request deduplication, serialization
Server function proxy + CSRF	1-2 months	Code generation, validation from TS types, error propagation
File-based router + layouts + middleware	1-2 months	Dynamic segments, catch-all routes, nested layouts
DOM morphing for navigation	1-2 months	Focus preservation, scroll restoration, form state, media playback
CSS scoping + dead code elimination	1-2 months	Another compiler pass, specificity handling, critical CSS
HMR with signal state preservation	1-2 months	Module graph invalidation, component boundary detection
CLI + dev server + error overlay	1 month	Vite integration, diagnostic formatting
TypeScript types without plugins	1 month	And then building the plugin anyway for edge cases

Conservative total: 18-29 months of full-time work.

For one person with a day job, working evenings and weekends, call it 3-5 years.

I stared at that spreadsheet for a long time. Then I did something I should have done months earlier: I looked at who else had tried this.

Every framework has a story you don't see

Svelte. Rich Harris started working on it in 2016. Seven years and four major versions later, Svelte 5 shipped with compiler-based signal transforms ($state, $derived). Not Rich alone — a core team of 5+ engineers, backed by Vercel (a company with hundreds of millions in funding), with thousands of community contributors stress-testing every edge case. The compiler alone is tens of thousands of lines of code.

And Rich Harris isn't some random developer. He built D3 components at The New York Times, created Rollup (one of the most used JavaScript bundlers), and is one of the most recognized figures in web development. He gave the talks. He built the community. He spent years earning the trust that makes people try a new framework.

Solid. Ryan Carniato worked on it for five years before version 1.0. Five years of evenings and weekends while holding a full-time job. He's now full-time at Netlify, with a team building SolidStart (the meta-framework). When I read Solid's source code, I see the scars of every edge case I documented in my spec — and a hundred more I hadn't thought of.

Astro. Founded by Fred K. Schott with venture capital funding, a team of 10+ full-time engineers, a dedicated documentation team, and community managers. Even with those resources, Astro 1.0 took about 18 months.

Qwik. Created by Misko Hevery — the person who built Angular. Backed by Builder.io with a full engineering team. Even with Misko's decades of framework experience and corporate resources, Qwik still struggles with adoption.

See the pattern? Every successful framework has an organization behind it. Not just code — an organization. Funding, or full-time employment, or both. A team, not a person. Conference talks, blog posts, Discord communities, Stack Overflow answers, tutorials, example repos, deployment guides, migration paths.

I had a Markdown file.

The 80% trap

Here's the thought that seduced me for weeks: "I could build 80% of the MVP in three months. Ship something, get feedback, iterate."

This is the most dangerous thought in software engineering. Because 80% of a framework is 0% of a framework.

Think about it. If the compiler handles 80% of signal transforms correctly but crashes on async closures inside .map() callbacks — nobody can use it. If hydration works for 80% of HTML structures but breaks on <table> elements — the first person who renders a data table files a bug and walks away. If cross-module tracking resolves 80% of import patterns but fails on barrel files — every project with a components/index.ts is broken on day one.

Frameworks don't degrade gracefully. They either work for your use case or they don't. And every developer's use case is a unique snowflake that includes at least one of the 20% of patterns you haven't implemented yet.

React can afford edge cases because it has a decade of production battle-testing and a team at Meta whose full-time job is fixing them. I would be a single person responding to GitHub issues at 11 PM after a full workday, trying to figure out why someone's const { data } = useQuery() isn't reactive inside a Promise.all() callback that's wrapped in a try/catch inside an async IIFE.

I could feel the burnout from here, and I hadn't written a single line of implementation code.

The ecosystem problem

Let's say I somehow built the framework. Let's say it works. A developer installs it, creates a project, and starts building a real application. They need:

Authentication. NextAuth, Clerk, Lucia — none work with my framework. Custom integration needed.
UI components. Shadcn, Radix, Headless UI — all React-specific. Start from scratch.
Database. Prisma and Drizzle are framework-agnostic, but the integration patterns (types, server functions) need to be built.
Deployment. I had "deployment adapters" in my post-MVP list. Translation: on launch day, there's no way to deploy to Vercel, Netlify, Cloudflare, or AWS.
Error tracking. Sentry integration? Doesn't exist.
Analytics. Custom event tracking? Manual.

A framework without an ecosystem is like a city with roads but no buildings. Technically impressive, practically uninhabitable.

And here's the chicken-and-egg problem: nobody writes libraries for a framework with no users, and nobody uses a framework with no libraries. Every successful framework broke this cycle somehow — React through Facebook's internal adoption, Vue through exceptional documentation and gradual adoption from jQuery projects, Svelte through Rich Harris's media presence and Vercel's backing.

My plan for breaking this cycle was... well, I didn't have one. That should have been a sign.

What the specification actually was

Here's where the story turns.

For weeks after the spreadsheet, I felt like I'd wasted months of my life. All those late nights spent on a framework that would never exist. All that careful documentation of edge cases nobody would ever encounter. A 55 KB monument to overambition.

Then I realized I was looking at it wrong.

The specification wasn't a failed framework. It was the most thorough education in web platform engineering I could have given myself.

Before writing it, I knew how to use React, Solid, Svelte, Astro. After writing it, I understood why they work the way they do. Every frustrating API decision, every seemingly arbitrary limitation, every "why can't they just..." — I now had the answer. Because building the alternative is orders of magnitude harder than it looks.

Let me give you specific examples.

Lesson 1: Every "unnecessary" API has a body count behind it

Remember how I dismissed useMemo, $derived(), and computed() as boilerplate? My framework would have auto-derived const — the compiler would just know.

Then I discovered that auto-derived const changes the semantics of JavaScript. const x = a * b in standard JS means "compute once." In my framework, it means "recompute whenever dependencies change." Terser (a popular minifier) could inline or eliminate these expressions because it assumes const means const. ESLint rules would give wrong advice. Code reviewers would misunderstand behavior.

Svelte 5 uses $derived() not because they couldn't figure out auto-detection, but because explicitness prevents an entire category of bugs. The "boilerplate" is the feature. It tells humans and tools "this expression re-runs."

I thought I was removing ceremony. I was removing clarity.

Lesson 2: Edge cases ARE the product

My specification described the happy path beautifully. PriceCalculator worked. Counter worked. TodoMVC would have worked.

But frameworks aren't judged by their demos. They're judged by what happens when:

A developer uses a browser extension that injects DOM nodes
An async operation completes after the component unmounts
A library passes your signal through JSON.stringify
Two islands import the same shared signal module
A circular dependency exists between server functions
The SSR output differs from the client due to timezone differences
Intl.DateTimeFormat returns different strings on the server and the browser

For each of these, React has a documented solution (or at least a documented known issue). For my framework, each would be an undefined behavior discovered in production.

Senior engineers don't estimate a project by counting the happy-path features. They estimate it by counting the edge cases. My specification had 28 features and approximately zero edge case resolutions.

Lesson 3: The compiler is not a free lunch

Compiler-based frameworks (Svelte, Solid to some degree, Qwik) feel magical. You write simple code, the compiler outputs optimized code. Everybody wins.

What I learned: the compiler is a trade. You get performance and DX. You pay with:

Debuggability. The code in your editor isn't the code that runs. Stack traces point to generated code. console.log shows internal signal objects, not your variables.
Tooling compatibility. Every tool in the JavaScript ecosystem — linters, formatters, bundlers, test runners, coverage tools — assumes standard JS semantics. A compiler that changes const semantics breaks assumptions everywhere.
Error messages. When something goes wrong, is it your code or the compiler's output? The error occurs in generated code. You need source maps, custom error formatting, and a mental model of what the compiler did.
Contribution barrier. An open-source runtime (React, Vue) can be debugged by anyone who reads JavaScript. An open-source compiler requires understanding AST transforms, scope analysis, code generation, and source maps. The contributor pool is 10x smaller.

This doesn't mean compilers are wrong. Svelte and Solid prove they're powerful. It means that building a compiler-based framework is 10x harder than building a runtime-based one, and I was already looking at 2-3 years for a runtime-based scope.

Lesson 4: Design is easy, survival is hard

I could design an API in an afternoon. A beautiful, minimal, orthogonal API that solves real problems elegantly.

But a framework isn't an API. It's:

Code + documentation + tutorials + migration guides
Community + Discord + GitHub issues + Stack Overflow answers
Conference talks + blog posts + video courses + podcasts
Deployment adapters + starter templates + example repos
Security patches + breaking change management + LTS policy
A person (or team) who responds when something breaks at 3 AM

Vue succeeded not because it was technically superior to React, but because Evan You wrote the best framework documentation in the history of open source and personally answered thousands of community questions. Astro succeeded not because islands are a novel concept, but because they found the right niche ("the web framework for content-driven websites") and executed relentlessly on developer experience.

The specification was the easiest 10% of the work. The other 90% is what separates an idea from a product.

Lesson 5: Understanding "how" is not wasted

This is the lesson that took longest to internalize, and it's the one I'm most grateful for.

After I closed the specification for the last time, I went back to my day job writing React. And everything looked different.

When a colleague asked "why does React re-render the whole component?", I could explain exactly what the alternative looks like and why React's team made the trade-offs they did.

When I reviewed a PR that used useMemo for a simple derived value, I felt a twinge of recognition — and a deeper appreciation for why explicit derivation markers exist.

When I read about React Server Components and "use client", I didn't roll my eyes. I understood the Transfer vs. Expression problem from the inside. I knew that the boundary between server and client code is fundamentally a compiler problem, and every solution has the same constraints I'd mapped in my specification.

When a junior developer asked me "should we use Astro or Next.js for this project?", I didn't give a surface-level answer about "static vs. dynamic." I explained islands architecture, hydration costs, JavaScript budgets — with the kind of depth that only comes from having tried to build the alternative yourself.

The specification didn't ship. The knowledge did.

Lesson 6: Know when the spec is the product

Here's a realization that surprised me: the specification itself had value. Not as a framework blueprint, but as a way of thinking about web platform trade-offs.

Every design decision was a miniature essay on the tension between DX and performance, between magic and explicitness, between compiler power and JavaScript semantics. The "rejected alternatives" sections — where I explained why each option fails — were more educational than any blog post I'd ever read about framework internals.

If I'd started writing code on day one instead of specifying, I would have hit each problem blindly, one at a time, over months. The specification let me hit them all in weeks, on paper, where the cost of a wrong decision is deleting a paragraph rather than rewriting a compiler pass.

Sometimes the spec is the product. Sometimes understanding the problem is the solution.

What I'd do differently

If I could go back to the evening when I first sketched let count = signal(0) on my screen, I wouldn't tell myself to stop. The exploration was worth it. But I'd change the path:

Build a proof-of-concept first, specify later. Write the simplest possible Vite plugin that transforms signal() in a single file. No cross-module analysis, no hydration, no server functions. See how far the basic transform gets. Hit real problems before theoretical ones.
Scope the MVP to one idea, not all four. "Signals + compilation + islands + server-first" is four frameworks. Pick one. A Vite plugin that adds auto-derived const to any existing framework would be genuinely useful and shippable in weeks.
Find one other person. Not ten. Not a team. One person who's excited enough to pair on a compiler pass. The difference between 1 and 2 people on a project like this isn't 2x — it's 10x, because you have someone to test your assumptions against.
Write the blog posts first. Seriously. "Here's a problem with React, here's how a compiler could solve it, here's a proof-of-concept" would have gotten more feedback than a private specification ever could. The community would have told me which ideas were worth pursuing and which were dead ends — before I spent months documenting dead ends.

The file is still there

The specification lives in my repository. project-idea.md. 1,500 lines. 55 KB.

Sometimes I open it. I read the section on Transfer vs. Expression, and I still think it's one of the clearest explanations of a compiler boundary I've ever written. I read the hydration section, and I appreciate how thoroughly I documented each marker type. I read the reactive batching section, and I notice the push-pull contradiction I never resolved.

I don't feel failure when I read it. I feel something closer to the way you feel about a really good trip. I went somewhere, I saw things clearly, and I came back changed.

The part where I tell you what to do

If you're reading this and you have your own ambitious side project — a framework, a language, a tool, a library that will change everything — I'm not going to tell you to stop. I don't know your situation, your skills, or your ambition. Maybe you're the next Rich Harris. Somebody has to be.

But I'll tell you what I wish someone had told me:

The strength of your vision is not evidence of your capacity to execute it. Understanding exactly how something should work is a necessary condition for building it, but it's not a sufficient one. The gap between the two is filled with time, money, people, and stamina. Be honest about how much of each you have.

A shipped proof-of-concept teaches you more than an unshipped specification. My specification was thorough. A working prototype of just the signal transform would have been more valuable, because real code reveals problems that paper hides.

The best outcome of an abandoned project isn't the project. It's you. I am a measurably better engineer than I was before this project. I understand compilers, reactive systems, hydration, and framework design at a depth I couldn't have reached by reading documentation or watching conference talks. That understanding compounds every day I write code, review PRs, and mentor others.

And finally:

The framework landscape doesn't need another framework. It needs engineers who understand why the existing ones work the way they do. When you deeply understand React's trade-offs, you use React better. When you understand why Svelte chose $derived(), you appreciate explicitness. When you understand why Astro exists, you pick the right tool for the right job.

I set out to build a framework. I built something better — a mental model of the entire web platform that I carry with me into every project, every code review, every architectural decision.

The best code I ever wrote was the code I decided not to ship.

This is Part 3 of a three-part series. Part 1 covers the vision and API design. Part 2 covers the technical deep dive. Thanks for reading the whole journey.

I Built a Reactive Compiler for JavaScript — Here's Where It Broke

Maryan Mats — Mon, 06 Apr 2026 16:20:22 +0000

In Part 1, I showed you the vision: a framework where you write let count = signal(0), const doubled = count * 2, and the compiler handles the rest. Two imports, zero ceremony, Solid-level performance with React-like syntax.

It was elegant. It was exciting. And it immediately raised a question that nearly broke my brain.

The question that changes everything

Consider this innocent-looking code:

let count = signal(0);

// Case 1: Returning from a composable
function useCounter() {
  return { count };
}

// Case 2: Logging
console.log(count);

// Case 3: Passing to a child component
<Display value={count} />

// Case 4: Arithmetic
const doubled = count * 2;

In all four cases, count appears as a plain variable. But the compiler needs to do completely different things depending on where it appears:

Case 1 (return): Should pass the signal object — so the call site can still subscribe to changes
Case 2 (log): Should pass the current value — console.log doesn't know what a signal is
Case 3 (JSX prop): Should pass the signal object — so the child component re-renders when it changes
Case 4 (arithmetic): Should pass the current value — you can't multiply a signal object by 2

Same variable. Four different behaviors. Welcome to the Transfer vs. Expression problem.

The principle behind the rule

After weeks of thinking about this (and filling a notebook with diagrams that would alarm any psychologist), I found a clean principle:

Let me explain what this means:

Transfer positions — the compiler transforms both the sender and receiver:

1. return count         → return __count (signal object)
   const { count } = useCounter()  → compiler transforms this too ✓

2. return { count }     → return { count: __count }
   const { count } = useCounter()  → compiler transforms this too ✓

3. <Child val={count}/> → <Child __props={{ get val() { return __count.get() } }} />
   function Child({ val }) → compiler transforms prop access too ✓

Expression positions — the compiler can't control the other side:

1. console.log(count)   → console.log(__count.get())
   // console.log is native code, compiler can't touch it ✗

2. someLib.process(count) → someLib.process(__count.get())
   // third-party code, compiler can't touch it ✗

3. count * 2             → __count.get() * 2
   // multiplication operator expects a number, not an object ✗

4. `${count} items`      → `${__count.get()} items`
   // template literal coercion, not compiler-controlled ✗

The insight is almost philosophical: a compiler can only be "magic" within its own jurisdiction. The moment data crosses into code the compiler doesn't control — native APIs, third-party libraries, JavaScript operators — the magic must resolve into plain values.

This isn't arbitrary. It's a consequence of what compilation means.

Why this matters (and why it's dangerous)

This rule has an uncomfortable implication. Watch what happens when you refactor:

let count = signal(0);

// Version 1: Works — count is in a derived expression
const doubled = count * 2; // → __derived(() => __count.get() * 2) ✓

// Version 2: Broken — extract to function
function double(n) { return n * 2; }
const doubled = double(count); // → double(__count.get()) ✗ NOT reactive!

A perfectly reasonable refactoring — "extract expression into a function" — silently kills reactivity. Because count in a function argument is an expression position (the compiler can't control what double() does with it), it unwraps to a plain value. The derived computation runs once and never updates.

This is the kind of thing that makes you stare at the ceiling for an hour. You've designed a system where extracting a function changes behavior. Every linting rule, every code review instinct, every IDE refactoring shortcut becomes potentially dangerous.

Svelte 5 solved this by requiring explicit $derived() — making it clear where reactive computation happens. I rejected $derived() as "boilerplate" in my initial design. Now I was paying for that choice.

Cross-module analysis: two passes, infinite edge cases

The compiler needs to know which variables are signals — not just in the current file, but across the entire project. If useCounter() in lib/counter.ts returns a signal, the consuming file needs to know.

I designed a two-pass system:

Pass 1: Scan ALL files → collect metadata
  - Which exports are signals?
  - Which functions return signals?
  - Which files import signal-creating code?

Pass 2: Transform each file using Pass 1 metadata
  - Now we know that `count` from `useCounter()` is a signal
  - Transform accordingly

Sounds clean, right? Now consider reality:

Barrel files:

// lib/index.ts
export * from './counter';
export * from './timer';
export * from './auth';
// 50 more re-exports...

Pass 1 must recursively resolve every export *, including circular re-exports, to determine which symbols carry signal metadata. For a large project, this is O(n * m) where n is files and m is symbols.

Dynamic imports:

const mod = await import(`./stores/${storeName}`);
mod.count++; // Is this a signal? 🤷

The compiler can't statically determine what storeName will be at runtime. This is fundamentally unsolvable with static analysis.

The Vite problem:

This was the showstopper I didn't see coming. I had "Build tool: Vite" in my implementation plan. But Vite's plugin API calls transform() per file. Each file is transformed independently. My two-pass cross-module analysis requires seeing all files before transforming any file.

This means either:

Don't use Vite — build a custom pipeline (months of work, lose the entire Vite ecosystem)
Work around Vite — cache metadata between transforms, handle invalidation (fragile, hard to debug)
Limit cross-module tracking — only track signals within component files (lose the composables story)

None of these options is good. TypeScript itself took years to build program-wide analysis, and it's still slow on large projects. I was planning to replicate this as a side project.

The TypeScript trick (and its lies)

For the developer experience to work, TypeScript needs to understand signal types without custom plugins. I came up with an intersection type hack:

function signal<T>(value: T): T & {
  mut: (fn: (draft: T) => void) => void;
  peek: () => T
};

let count = signal(0);
// type: number & { mut, peek }

count++;         // number++ → works ✓
count * 2;       // number * 2 → works ✓
count.peek();    // .peek() method → works ✓
count.mut(d => d + 1); // .mut() method → works ✓

TypeScript is happy. The IDE gives you autocomplete. No plugins needed. I was unreasonably proud of this.

Then I tried:

function identity<T>(x: T): T {
  return x;
}

const result = identity(count);
// TypeScript says: type is number & { mut, peek }
// Reality: identity(__count.get()) returns a plain number
// result.peek() → runtime error 💥
// TypeScript won't warn you

The intersection type is what I called a "compile-time fiction." It works perfectly inside the compiler's jurisdiction — components, composables, JSX. But the moment a signal touches generic code that the compiler doesn't transform, the type lies.

Svelte 5 started with a similar approach and eventually built a custom language server (svelte-language-tools). The "no plugins needed" claim was true for the happy path. For real-world code with generics, utility functions, and library interop — you'd need exactly the plugin I said wasn't necessary.

Lesson learned: if your types describe something that doesn't exist at runtime, someone will eventually call .peek() on a plain number and file a very confused bug report.

Hydration: finding DOM nodes in a haystack

Server-side rendering generates HTML. The browser parses it into a DOM tree. Now JavaScript needs to find the specific text node that shows subtotal so it can update it when qty changes.

Most frameworks solve this with markers — data attributes, special IDs, or comment nodes scattered throughout the HTML. My approach was different: since the compiler knows the exact DOM structure at build time, it can generate direct paths:

// The component renders:
<div>
  <h1>Shop</h1>
  <span>{count} items</span>
  <button onClick={() => count++}>+</button>
</div>

// The compiler knows the structure:
// root.children[0] = h1 (static, ignore)
// root.children[1] = span
// root.children[1].childNodes[0] = TextNode ← this is reactive
// root.children[2] = button ← needs event handler

// Generated hydration code:
function hydrate(root) {
  const countText = root.children[1].childNodes[0];
  const button = root.children[2];

  __effect(() => { countText.data = String(__count.get()); });
  button.addEventListener('click', () => __count.set(__count.get() + 1));
}

No markers. No querySelector. No data-* attributes. The compiler generates a precise address for every reactive node.

Beautiful, right? Now install Grammarly.

Grammarly (and password managers, and ad blockers, and browser extensions) inject DOM nodes into the page. Your carefully calculated children[1].childNodes[0] now points to a Grammarly <span> instead of your text node. Silently. In production. On your users' browsers.

And then there's browser HTML normalization. Try this:

<table>
  <tr><td>Data</td></tr>
</table>

The browser automatically inserts a <tbody> that doesn't exist in your source HTML:

<table>
  <tbody>        <!-- 👋 hi, I'm new here -->
    <tr><td>Data</td></tr>
  </tbody>
</table>

Your tree walking path table.children[0] expected <tr>. It got <tbody>. Every path below is broken.

I wrote in my specification: "The compiler knows HTML rules and generates tree walking that accounts for normalization." One sentence. For a problem that the Marko Framework (built by eBay) spent years making production-ready. One sentence for years of work. That's the gap between designing a framework and building one.

For dynamic content, I added comment markers as a fallback:

<p>
  Hello, <!--t-->Alex<!--/t-->! You have
  <!--t-->5<!--/t--> items.
</p>

So much for "no markers, clean HTML." By the end of the hydration section, I had four types of markers (, , , <mats-island>), a browser normalization compatibility layer, and the dawning realization that I'd described something much harder than I thought.

Destructuring: the elegant trap

One of my proudest design moments was making destructuring reactive:

let user = signal({ name: 'Alex', age: 25 });

const { name, age } = user;
// Compiler output:
// const name = __derived(() => __user.get().name)
// const age = __derived(() => __user.get().age)

// Works with props too:
function UserCard({ user }) {
  const { name, age } = user;
  // Same transformation — reactive destructuring
}

Nested destructuring, aliases, defaults, array destructuring, rest patterns — all reactive. I was thorough. I documented every case.

Then someone (okay, me at 3 AM) asked: "What about props spread?"

function Wrapper(props) {
  return <Inner {...props} />;
}

In JavaScript, {...props} calls all getters and creates a plain object. If props has getter-based reactive properties (which is how my framework passes props), spreading them creates a static snapshot. Reactivity is gone.

This isn't an edge case. It's one of the most common React patterns. Wrapper components, higher-order components, compound components, design systems — they all use spread. The workaround? "List every prop explicitly." But a generic wrapper doesn't know which props it'll receive.

Solid.js solved this with splitProps() and mergeProps(). I put "mergeProps utility" in "Post-MVP features." Translation: I didn't have a solution and was hoping future-me would figure it out. (Future-me did figure it out: don't build the framework.)

The reactive model nobody can explain

I designed the batching system with three properties:

Signal writes mark dependents as dirty (push-based notification)
Derived values recompute lazily on read (pull-based evaluation)
DOM updates flush through queueMicrotask (batched scheduling)

This gives you glitch-free updates:

let a = signal(1);
let b = signal(2);
const sum = a + b; // derived

function handler() {
  a = 10; // marks sum as dirty
  b = 20; // marks sum as dirty
  // → after handler: sum recalculates ONCE → DOM updates ONCE
  // → intermediate state (a=10, b=2, sum=12) never reaches the DOM
}

Sounds great. But when I tried to write a precise specification of the execution model, I kept contradicting myself.

"Flush processes dirty nodes in topological order" — but if derived values are lazy (recompute on read, not on write), what exactly does "flush" do? Does it push updates through the graph, or does it trigger reads that pull updates? Is this push-based or pull-based?

The answer is "hybrid, like the TC39 Signals proposal." But describing a hybrid reactive model precisely requires formal semantics — mathematical rules that define behavior in every case. I had examples. I didn't have rules.

Specification-by-example always has gaps. I could show you 20 cases that work correctly. Case 21 would be undefined behavior, and neither of us would know until runtime.

The 3.2 KB runtime that wasn't

In my specification, I had a beautiful table:

Module	Size
Navigation	~400 bytes
DOM morphing	~2 KB
Island loader	~400 bytes
Server function proxy	~300 bytes
Event bus	~100 bytes
Total	~3.2 KB

I was so proud of that number. Then I started tallying what was missing:

Signals + derived + effects runtime: ~800 bytes (per island, not shared)
Watch with cleanup: ~1 KB
.mut() (Immer-like mutations): ~2 KB
Keyed list reconciliation: ~1.5 KB
devalue deserialization: ~1 KB
Error boundaries and cleanup: ~300 bytes

Realistic total for a page with one interactive island: 8-10 KB. Still smaller than React (35 KB+). But not "3.2 KB." I'd been marketing to myself.

Every framework author does this, by the way. Preact claimed 3 KB and grew to 4 KB. It's not dishonesty — it's optimism meeting reality. But when you're writing a specification, optimism is a liability.

The specification reaches 55 KB

By this point, my specification had grown to 1,500 lines. Every decision was documented. Every alternative was considered. Every edge case I could think of was addressed.

I knew exactly how the compiler should handle closures, async/await, re-exports, barrel files, conditional dependencies, dynamic imports, browser normalization, Grammarly-injected nodes, circular module dependencies, <tbody> auto-insertion, and fourteen other things that would make this paragraph even longer.

I could explain the Transfer vs. Expression distinction to anyone. I could draw the reactive dependency graph for any component. I could tell you why early return isn't reactive and why {...props} breaks getter-based reactivity and why const in my framework doesn't mean what const means in JavaScript.

I had a comprehensive, detailed, internally consistent specification for a framework that would genuinely improve web development.

What I didn't have was a single line of implementation code.

And I was starting to count the months.

The weight of knowing

There's a peculiar kind of clarity that comes from deep specification work. You understand the problem space so well that you can see both the solution and its impossibility simultaneously.

I could see that the compiler transform would require handling every JavaScript scope pattern — closures, async continuations, generator yields, class methods, proxy traps. That Svelte's team of 5+ engineers spent two years on this, with the advantage of controlling a custom .svelte file format. That I was proposing to do the same thing in arbitrary .tsx files, alone, as a side project.

I could see that cross-module analysis was fundamentally incompatible with Vite's per-file transform pipeline. That the two-pass approach required either abandoning Vite or building a fragile caching layer that would be the source of mysterious bugs for years.

I could see that "3.2 KB runtime" was an estimate made by someone who hadn't written the code yet — and that the real number would be 3x larger, which is still impressive, but not the number in the pitch.

Each of these was a red flag. Together, they formed a pattern.

The specification wasn't wrong. The vision wasn't wrong. But the distance between "a beautiful specification" and "a framework someone can npm install" is measured not in pages, but in person-years.

And I had a day job.

What's next

In the final part of this series, I'll tell you why I walked away. Not because the ideas were bad — they weren't. Not because I lost interest — I didn't. But because I learned something about the difference between understanding a problem and solving it.

I'll also share the specific lessons that made me a better engineer, even though I never shipped a single line of framework code.

Part 3: Why I Stopped Building My JavaScript Framework →

The best code you'll ever write might be the code you decide not to ship. The specification is still in my repo. Sometimes I open it and think, "yeah, this would've been amazing." Then I close it and open a React component. Life goes on.

I Designed a Web Framework That Replaces React Hooks With Two Imports

Maryan Mats — Mon, 06 Apr 2026 16:11:14 +0000

There's a moment every frontend developer knows. You're staring at a React component, and the hook count is climbing like your electricity bill in winter.

const [items, setItems] = useState([]);
const [filter, setFilter] = useState('');
const [sort, setSort] = useState('date');

const filtered = useMemo(
  () => items.filter((i) => i.name.includes(filter)),
  [items, filter],
);
const sorted = useMemo(
  () => [...filtered].sort(comparators[sort]),
  [filtered, sort],
);
const total = useMemo(() => sorted.reduce((s, i) => s + i.price, 0), [sorted]);

useEffect(() => {
  document.title = `${sorted.length} items — $${total}`;
}, [sorted.length, total]);

Seven hooks. For a filtered list with a page title.

I looked at this code one evening and thought: what if you could write it like this instead?

let items = signal([]);
let filter = signal('');
let sort = signal('date');

const filtered = items.filter((i) => i.name.includes(filter));
const sorted = [...filtered].sort(comparators[sort]);
const total = sorted.reduce((s, i) => s + i.price, 0);

watch(() => {
  document.title = `${sorted.length} items — $${total}`;
});

Same logic. Two imports: signal and watch. No dependency arrays. No useMemo. No useCallback. No stale closures haunting your dreams at 2 AM.

That thought turned into a 1,500-line specification, months of architectural exploration, and eventually — one of the most valuable failures of my career.

This is the first part of a three-part series. I'll walk you through the vision, the technical design, the impossible problems I hit, and why I ultimately abandoned the whole thing. Buckle up — it's going to be a ride.

The problem isn't React. It's the ceremony

Let me be clear: React is a remarkable piece of engineering. The component model changed how we think about UIs. JSX is one of the best ideas in web development history.

But React was designed in 2013. The core mental model — "your component is a function that re-runs on every state change" — has consequences that compound over time.

Here's one:

function PriceCalculator({ product }) {
  const [qty, setQty] = useState(1);
  const [promo, setPromo] = useState('');

  const discount = promo === 'SALE50' ? 0.5 : 0;
  const subtotal = qty * product.price;
  const total = subtotal * (1 - discount);

  return (
    <div>
      <h2>{product.name}</h2>
      <input value={qty} onChange={(e) => setQty(+e.target.value)} />
      <input value={promo} onChange={(e) => setPromo(e.target.value)} />
      <span>{subtotal} USD</span>
      <span>{total} USD</span>
    </div>
  );
}

When qty changes from 1 to 3, here's what React does:

Re-executes the entire function — all variables, all computations
Creates ~15 virtual DOM objects — a tree describing what the UI should look like
Diffs the new tree against the old tree — comparing every node
Finds 3 differences — the input value, subtotal, and total
Patches 3 DOM nodes — the actual work that needed to happen

Steps 1–4 are overhead. The useful work is step 5.

Now imagine you didn't re-run anything. Imagine a compiler analyzed your code at build time, saw that subtotal depends on qty and product.price, and generated a tiny reactive graph:

signal qty ──────► derived subtotal ──────► derived total
                                                 ▲
signal promo ──► derived discount ─────────────┘

When qty changes: subtotal recalculates, total recalculates, two text nodes update. Three DOM operations. Zero diffing. Zero virtual DOM. Zero re-rendering.

The result is the same. The path is 10x shorter.

That's the idea I couldn't get out of my head.

Every brick already exists

Here's the thing that made this feel possible rather than delusional: none of these concepts are new.

Signals — Solid.js proved that fine-grained reactivity without a virtual DOM isn't just possible, it's faster. createSignal, createMemo, createEffect — the reactive primitive model works beautifully.
Compiler transforms — Svelte proved that a compiler can analyze your code, track which variables are reactive, and generate optimal update instructions. Svelte 5's $state() takes this even further with explicit markers.
Islands architecture — Astro proved that most pages don't need JavaScript at all. Ship HTML. Hydrate only the interactive bits. A blog post with one "like" button doesn't need 150KB of client-side framework code.
Server-first — Remix (and later React Server Components) proved that data loading belongs on the server. Don't fetch-on-mount, just render with data.

Each of these is a breakthrough. But each lives in its own ecosystem with its own trade-offs:

Approach	Framework	Trade-off
Signals	Solid	Custom `.svelte` file format (Svelte) or accessor API like `.get()/.set()` (Solid)
Compilation	Svelte	Locked into `.svelte` format, separate toolchain
Islands	Astro	No built-in fine-grained reactivity in islands
Server-first	Remix/Next	Full-page hydration ships too much JS

What if you could combine all four — in standard TypeScript + JSX?

That's what I set out to design.

The two-import API

Here's the core idea. The entire developer-facing API for reactivity fits in two words:

`signal` — reactive state

import { signal } from 'mats';

let count = signal(0);

// Read it like a normal variable
console.log(count); // 0

// Write it like a normal variable
count = 5;
count++;
count += 10;

No .value. No .set(). No [getter, setter] tuple. Just... a variable.

The trick? The compiler transforms every read and write behind the scenes:

// What you write:
let count = signal(0);
count++;
const doubled = count * 2;

// What the compiler outputs:
const __count = __signal(0);
__count.set(__count.get() + 1);
const __doubled = __derived(() => __count.get() * 2);

You write JavaScript. The compiler makes it reactive.

`watch` — side effects

import { watch } from 'mats';

watch(() => {
  document.title = `${count} items`;
});

Auto-tracks dependencies. Re-runs when they change. Returns a cleanup function for event listeners, timers, subscriptions.

That's it. Two imports. Everything else — derived computations, DOM updates, dependency tracking — is the compiler's job.

The magic of `const`

This is where it gets interesting. Look at this:

let price = signal(100);
let qty = signal(2);

const TAX_RATE = 0.2; // no signal dependency → calculated once
const subtotal = price * qty; // depends on signals → auto-derived
const total = subtotal * (1 + TAX_RATE); // depends on derived → auto-derived
const label = `${total} USD`; // depends on derived → auto-derived

The compiler scans each const declaration. If the expression on the right side touches a signal (directly or through another derived value), it wraps it in __derived(). If not, it's a plain constant.

No useMemo. No computed(). No $derived(). Just const.

I know what you're thinking: "Wait, const in JavaScript means 'assigned once, never changes.' You're making it reactive?"

Yes. And I'm fully aware that this is controversial. More on that later — it's one of the reasons this project taught me so much.

How server and client split automatically

Here's where islands come in. The framework doesn't need "use client" or "use server" directives. The compiler figures it out:

// This component has NO signals, NO watch, NO event handlers
// → Server component. 0 KB JavaScript. Just HTML.
function ProductCard({ product }) {
  return (
    <div>
      <h2>{product.name}</h2>
      <p>{product.description}</p>
      <span>{product.price} USD</span>
    </div>
  );
}

// This component HAS a signal
// → Automatically becomes an "island". Ships minimal JS.
function AddToCartButton({ productId }) {
  let adding = signal(false);

  return (
    <button
      disabled={adding}
      onClick={async () => {
        adding = true;
        await addToCart(productId);
        adding = false;
      }}
    >
      {adding ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

No decisions to make. No directives to remember. Use signal → you get an interactive island. Don't use it → pure HTML, zero cost.

For a typical content page with 50 components and 3 interactive ones:

Traditional SSR (Next.js):  All 50 components hydrate → ~80-150 KB JS
Islands approach:           Only 3 islands hydrate   → ~5-6 KB JS

That's a real difference. Not in benchmarks — in user experience. On a 3G connection in rural Ukraine, 150 KB vs 6 KB is the difference between "usable" and "still loading."

Server functions without the ceremony

For server-side code, I designed a convention: anything in a server/ directory is server-only. Always. No imports from the framework needed:

// server/catalog.ts — plain TypeScript, runs on the server
export async function searchProducts(query: string) {
  const res = await fetch(`${process.env.API_URL}/search?q=${query}`, {
    headers: { Authorization: `Bearer ${process.env.API_SECRET}` },
  });
  return res.json();
}

When an island imports this function, the compiler automatically replaces it with a fetch proxy:

// In an island component:
import { searchProducts } from '~/server/catalog';

// The compiler turns this into:
// const searchProducts = (query) =>
//   fetch('/__mats/fn/catalog/searchProducts', {
//     method: 'POST',
//     body: JSON.stringify({ args: [query] }),
//     headers: { 'X-CSRF-Token': __csrfToken },
//   }).then(r => r.json());

CSRF protection, input validation, error handling — all automatic. The developer writes a function. The compiler builds the bridge.

Compare this to the Next.js dance of "use server", server actions, revalidatePath, and the mental gymnastics of "is this running on the server or the client right now?".

The PriceCalculator, fully compiled

Let me show you what the compiler would output for our earlier example. This is where the vision comes together.

What you write:

import { signal } from 'mats';

function PriceCalculator({ product }) {
  let qty = signal(1);
  let promo = signal('');

  const discount = promo === 'SALE50' ? 0.5 : 0;
  const subtotal = qty * product.price;
  const total = subtotal * (1 - discount);

  return (
    <div>
      <h2>{product.name}</h2>
      <input value={qty} onInput={(e) => (qty = +e.target.value)} />
      <input value={promo} onInput={(e) => (promo = e.target.value)} />
      <span>{subtotal} USD</span>
      <span>{total} USD</span>
    </div>
  );
}

What the compiler generates:

function PriceCalculator(__props) {
  // 1. Signals
  const __qty = __signal(1);
  const __promo = __signal('');

  // 2. Auto-derived (detected from const expressions)
  const __discount = __derived(() => (__promo.get() === 'SALE50' ? 0.5 : 0));
  const __subtotal = __derived(() => __qty.get() * __props.product.price);
  const __total = __derived(() => __subtotal.get() * (1 - __discount.get()));

  // 3. DOM — created once, never recreated
  const div = createElement('div');
  const h2 = createElement('h2');
  const span1 = createElement('span');
  const span1_text = createText('');
  const span2 = createElement('span');
  const span2_text = createText('');
  // ... inputs, assembly ...

  // 4. Reactive bindings — surgical DOM updates
  __effect(() => {
    span1_text.data = __subtotal.get() + ' USD';
  });
  __effect(() => {
    span2_text.data = __total.get() + ' USD';
  });
  __effect(() => {
    input1.value = __qty.get();
  });

  return div;
}

When qty changes from 1 to 3:

qty.set(3)
  │
  ├──► subtotal recalculates: 3 * 100 = 300  → YES, changed
  │    ├──► span1 text updates: "300 USD"      ← 1 DOM operation
  │    └──► total recalculates: 300 * 1 = 300  → YES, changed
  │         └──► span2 text updates: "300 USD"  ← 1 DOM operation
  │
  ├──► input1.value = 3                         ← 1 DOM operation
  │
  └──► discount does NOT recalculate (doesn't depend on qty)
       promo does NOT recalculate
       h2 does NOT update (static)

TOTAL: 3 DOM operations. Zero diffing. Zero VDOM.

I won't lie — when I first sketched this out on a whiteboard (okay, in a Markdown file at 1 AM), I felt like I'd discovered something profound. The elegance was intoxicating.

Everything fit together. Signals for state. Compiler for reactivity. Islands for delivery. Server functions for data. Two imports for the developer.

It was beautiful.

It was also the moment I should have asked: "Okay, but how hard is it to actually build the compiler?"

The specification grows

What started as a napkin sketch turned into a 55 KB specification. Every design decision led to three more. Every edge case revealed two siblings.

How does destructuring work with signals? What happens when you spread reactive props? When should the compiler pass a signal object vs. unwrap its value? How does hydration find DOM nodes without littering the HTML with markers? How does cross-module dependency tracking interact with Vite's per-file transform pipeline?

I documented everything. Every decision, every trade-off, every alternative I considered and rejected.

The specification became the most thorough technical document I've ever written. And that, paradoxically, is when I started to realize I might be in trouble.

But that's a story for Part 2.

What's next

In the next article, I'll take you into the deepest technical rabbit hole of this project: the problem of when a reactive variable should behave like an object and when it should behave like a plain value. It sounds simple. It nearly broke my brain.

I'll also cover cross-module compiler analysis, TypeScript type hacking, the hydration challenge, and the moment I realized that JavaScript doesn't always play on your side.

Part 2: I Built a Reactive Compiler for JavaScript — Here's Where It Broke →

If you're building something ambitious and wondering whether it's genius or insanity — it's probably both. The trick is figuring out which part is which before you burn out.

DEV Community: Maryan Mats

Why I Stopped Using Enums in TypeScript (I Use `as const` Instead)

What TypeScript enums compile to (and why it matters)

The numeric enum footgun

String enums are better — but still weird

TypeScript enums and tree-shaking

const enum — the escape hatch that isn't

TypeScript enum alternatives: what I use instead

Pattern 1: as const objects (enum replacement)

Pattern 2: Plain union types

Migrating from enum to as const: before and after

The type helper I keep in every project

When TypeScript enums are still the right choice

Quick comparison: enum vs as const vs union type

The deeper lesson

Stop Writing try/catch — Your TypeScript Errors Deserve Types

The man who decided this — twice

catch (e: unknown) — the narrowing nightmare

The async/await tax

Every modern language figured this out

The fix: return your errors

Want better ergonomics? Meet neverthrow

You're already using this pattern (you just don't know it)

Eric Lippert's razor: most of your catch blocks shouldn't exist

When try/catch is still the right tool

The pattern across everything I've written

Stop Using Booleans Everywhere — Use Union Types Instead

The call that broke my brain: createUser("John", true, false, true)

This bug has a name: Boolean Blindness

The math that should scare you: 2^n impossible states

This isn't a TypeScript thing — every language figured it out

Rust: enums are the default

Python: keyword-only arguments and linting rules

Swift and Kotlin: the language enforces readability

Even .NET has official guidelines

The libraries already know this

The gotcha nobody warns you about

When booleans are still fine

The deeper pattern

Render Props Are Not Dead — React Hooks Didn't Replace What Actually Matters

The thing nobody talks about: Container/Presentational separation

The real reason render props survive: inversion of control

What hooks literally cannot do

You can't call hooks conditionally

You can't use hooks inside .map()

A hook returns data. It doesn't control when you render.

The libraries that chose render props in 2025-2026

Children as a function — the underrated variant

The container pattern, revisited

Real downsides — the honest ones

The nesting problem is real

DevTools get noisy

TypeScript generics get awkward

Inline functions and memoization

When I reach for render props vs hooks

The one-liner bridge

You Don't Need Zustand: useSyncExternalStore Is All You Need

The useState + useEffect bug in React state management

What is tearing?

How useSyncExternalStore works — three arguments, zero magic

Building a type-safe React store from scratch

Common useSyncExternalStore pitfalls and how to fix them

Gotcha 1: Returning new objects from selectors

Gotcha 2: Defining subscribe inline

Gotcha 3: Forgetting getServerSnapshot

Real-world useSyncExternalStore examples

Recipe 1: Online status

Recipe 2: Media queries (responsive breakpoints without CSS)

Recipe 3: localStorage with cross-tab sync

How Zustand and Redux use useSyncExternalStore internally

When NOT to use useSyncExternalStore

React state: internal vs external — the mental model

Why I Stopped Building My JavaScript Framework After 1,500 Lines of Spec

The spreadsheet of doom

Every framework has a story you don't see

The 80% trap

The ecosystem problem

What the specification actually was

Lesson 1: Every "unnecessary" API has a body count behind it

Lesson 2: Edge cases ARE the product

Pattern 1: `as const` objects (enum replacement)

Quick comparison: enum vs `as const` vs union type

`catch (e: unknown)` — the narrowing nightmare

The `async/await` tax

Want better ergonomics? Meet `neverthrow`

When `try/catch` is still the right tool

The call that broke my brain: `createUser("John", true, false, true)`

You can't use hooks inside `.map()`

Gotcha 3: Forgetting `getServerSnapshot`

`signal` — reactive state

`watch` — side effects

The magic of `const`