DEV Community: nyaomaru

How I Made JavaScript Execution Visual and Rewindable (DSA View View 👀👀)

nyaomaru — Wed, 29 Jul 2026 10:42:13 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who was recently knocked off my feet by how good the zeetong (sole) from a Dutch fish shop was. 🐟😸

In the previous article, I explained how DSA View View takes the TypeScript written by a user, analyzes the function or class signature, and generates a Verification form.

nyaomaru

Jul 22

How I Built the Editor and Compile Pipeline for a TypeScript DSA Visualizer (DSA View View 👀👀)

#typescript #react #webdev #opensource

10 min read

This time, we are entering the heart of DSA View View: the Runtime and Visualization layers.

If you call an ordinary JavaScript function, the direct result you get back is usually the final return value.

But when I am studying DSA, that is not the part I really want to see.

I want to know:

What happened in the middle of the loop?
When did the pointer move?
At which exact moment did the variable change?
How deep did the recursion go?

In other words, I want to see the journey to the answer, not only the answer itself.

JavaScript, unfortunately, does not provide an API that accepts:

"Excuse me, could you move the current line one step backward?"

So how does DSA View View rewind execution?

Here is the answer up front. 😸

Before execution, DSA View View rewrites the code into a version that can record its intermediate state, then runs it until it completes or reaches a configured limit.

The UI then plays those recorded states forward and backward like security-camera footage.

In this article, we will look at that record-and-replay system through:

AST transformation with Babel
Injecting recordStep calls
Preserving the original meaning of the code
ExecutionStep and snapshot patches
Rewinding and jumping to variable changes
Running code inside a Web Worker
Detecting the appropriate Visualization
Tests that protect the AST transformation

The source code is available here 👇

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, MinHeap, MaxHeap, PriorityQueue, nested arrays matrices, strings, numbers, and class-style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse…

View on GitHub

All right, let’s open the Runtime and see what Mr. View has been watching. 👀👀

📝 The Big Picture: Turning Execution into an Array of Steps

The Runtime pipeline looks roughly like this.

User TypeScript
      ↓
Prepare common DSA classes
      ↓
Parse the code into an AST with Babel Parser
      ↓
Visitors inject recordStep(...)
      ↓
Transform TypeScript into JavaScript with Babel
      ↓
Execute it with new Function inside a Web Worker
      ↓
Generate ExecutionStep[]
      ↓
React moves currentStep forward and backward
      ↓
Display the Visualization that matches the trace

The most important design decision here is that the user’s code is not connected directly to a React component.

Instead, ExecutionStep[] acts as a shared recording format.

That lets arrays, pointers, recursion, trees, heaps, and other structures all live on the same timeline.

Let’s walk through how that works.

🔭 Runtime: Planting Observation Points in the Code

This is the heart of DSA View View. 💖

The Runtime needs intermediate states, so it does not execute the user’s code exactly as written.

First, Babel transforms the AST and injects calls to recordStep.

Injecting `recordStep` into the AST

Suppose the user writes.

let left = 0;

while (left < right) {
  left++;
}

DSA View View parses it into an AST and transforms it into something roughly like this.

let left = 0;
recordStep("variable-declaration", 1, "let left = 0", { left });

while (left < right) {
  recordStep("loop-iteration", 3, "while (left < right)", { left, right });

  left++;
  recordStep("assignment", 4, "left++", { left, right });
}

The second argument to recordStep is the original source line number, not the execution-step number.
Because line 2 is empty, the recorded lines are 1, 3, and 4.

In the real implementation, dedicated visitors handle AST nodes such as:

FunctionDeclaration
FunctionExpression
ArrowFunctionExpression
ClassMethod
VariableDeclaration
AssignmentExpression
UpdateExpression
CallExpression nodes that mutate arrays
for / while / for...of / for...in
ReturnStatement

A step can therefore be recorded when:

A function is entered
A variable is declared
A loop completes an iteration
A value is assigned
An array is mutated
A function returns

Current limitation
callback bodies inside methods such as sort, reduce, map, filter, and forEach are intentionally excluded from instrumentation for now.

The goal is not to trace every corner of JavaScript immediately. I am starting with patterns that are useful for DSA traces and can be instrumented without breaking the original behavior.

Injecting the Code Is Easier Than Not Breaking It

The hardest part of the AST transformation was not calling recordStep.

The hard part was making sure that,

after adding the recording logic, every original expression is still evaluated the same number of times and still returns the same value.

For example, if a return expression were evaluated once for recording and once for the actual return, its side effects would run twice.

return someFunction();

So the transformed code first stores the value in a temporary variable.

const algorithmVisualizerReturnValue = someFunction();

recordStep("return", line, description, {
  "return value": algorithmVisualizerReturnValue,
  "return location": returnLocation,
});

return algorithmVisualizerReturnValue;

Assignment expressions are another fun little trap.

Consider this.

const result = (arr[i++] = 7);

The transformed code must preserve all three facts:

i++ runs exactly once
The pre-increment value of i is used as the array index
The assignment expression itself evaluates to 7

DSA View View wraps the assignment in a synthetic arrow function, stores the result in a temporary variable, records the step, and returns the same value.

Using an arrow function also avoids accidentally stealing the surrounding this or arguments.

AST transformation cannot be "close enough".

If adding more visible steps changes the answer, the visualizer has somehow become the least trustworthy character in the story.

Not ideal.

🖍️ `ExecutionStep`: Making Execution Replayable

The Runtime records each observed state as an ExecutionStep.

A shortened version of the real type looks like this.

type ExecutionStep = {
  stepNumber: number;
  type: ExecutionStepType;
  line: number;
  column?: number;
  description: string;
  variables: Record<string, unknown>;
  timestamp: number;
  callStack?: string[];
  scope?: string;
  metadata?: {
    loopIteration?: number;
    conditionResult?: boolean;
    functionName?: string;
    heapTrace?: HeapTraceSnapshot;
  };
};

The Runtime currently generates steps including:

function-call
function-entry
variable-declaration
assignment
array-mutation
loop-iteration
return

line and description are used in the timeline.

variables provides the data needed to reconstruct the UI at that moment.

Recursive traces also use callStack, while prepared heap implementations can attach metadata.heapTrace.

Saving References Would Rewrite the Past

Suppose an array reference were stored directly inside a step.

const stack = [0, 1];
recordStep(/* save stack */);

stack.pop();

If the recorded step keeps the same reference, the earlier state will also appear as [0] after pop() runs.

That is not a historical record.

That is the past quietly editing itself.

So values passed to recordStep are deep-cloned at that moment.

The Runtime normally uses structuredClone. When it encounters values that need different handling, it falls back to a cloning implementation that supports cycles, Map, Set, Date, RegExp, and other cases.

The "Delta Snapshot" Is Really More Like a Patch

The implementation contains a name called variableDeltas, but this deserves a more precise explanation.

The current Runtime does not compare every value with the previous state and store only the keys that truly changed.

Instead:

The first step stores the initial state, including the inputs
Later steps deep-clone the visible variables passed to that recordStep
When a full snapshot is needed, the patches are merged in order
Reconstructed snapshots are cached

So, strictly speaking, these are closer to per-step patches than minimal deltas.

Step 0 patch: { left: 0, right: 5 }
Step 1 patch: { left: 1 }
Step 2 patch: { right: 4 }

Reconstructing them produces.

Step 0 snapshot: { left: 0, right: 5 }
Step 1 snapshot: { left: 1, right: 5 }
Step 2 snapshot: { left: 1, right: 4 }

The variables property of each ExecutionStep is a getter.

It starts from a previously cached snapshot and merges only the patches needed to reach the requested step.

There is one more implementation detail worth mentioning.

The Runtime sends state from the Worker to the UI with postMessage. During that structured clone, reading the getter also materializes the snapshot.

So the data does not remain a tiny delta forever and magically arrive on the main thread in that form.

The design mainly reduces eager reconstruction and cloning while the execution is being recorded. 📽️

Why Can the Timeline Move Backward?

DSA View View is not reversing JavaScript while it runs.

Inside the Web Worker, it first rewrites the code into an instrumented version and records the execution.

During playback, the main value that changes is currentStep.

type ExecutionState = {
  currentStep: number;
  totalSteps: number;
  steps: ExecutionStep[];
  isComplete: boolean;
  returnValue?: unknown;
  error?: string;
};

Moving forward displays the snapshot for currentStep + 1.

Moving backward displays the snapshot for currentStep - 1.

So rewinding means,

selecting an earlier recorded frame, not undoing the execution itself

Once recording has finished, users can navigate without rerunning their code:

Pause
Move one step forward or backward
Jump to any step in the timeline
Move to the first or final step

Users can also select a variable and jump directly to the previous step where its value changed.

That is especially useful for pointers such as i, left, and right.

No more clicking the Back button 47 times while whispering, "Where did you go wrong?" 😸

There Is a Generator, but It Does Not Suspend the User’s Code Line by Line

The Runtime API contains a Generator<ExecutionStep, ...>.

That might make it look as if the user’s code itself is being paused line by line with yield.

It is not.

After yielding the first function-call step, the instrumented code runs once and accumulates steps inside the execution context.

The generator then yields the already-recorded steps in order.

In the path used by the UI, the Worker consumes the generator completely and returns the finished ExecutionState.

Separating execution from playback is what makes the rewind behavior relatively simple.

⚙️ Web Worker: Do Not Take the UI Down with You

User code runs inside a dedicated Web Worker instead of the main thread.

new Worker(new URL("./execution-worker.ts", import.meta.url), {
  type: "module",
  name: "algorithm-execution",
});

An infinite loop or expensive computation on the main thread would freeze the entire page.

By moving execution into a Worker:

The React UI stays on the main thread
Starting a new run or leaving the page can terminate the Worker through an AbortController

The Runtime also has limits:

Execution timeout: 10 seconds
Maximum recorded steps: 3,000

When a limit is reached, the Worker can be terminated or execution can stop early with a warning.

A Worker Is Not a Security Sandbox

A Web Worker does not have access to the page DOM, localStorage, or sessionStorage.

DSA View View also does not execute user code on a server.

However, a Web Worker is not a security boundary that makes untrusted code safe.

The user code runs through new Function in the Worker global scope.

Web APIs available inside Workers, including fetch, are not automatically disabled.

The purpose of this architecture is to:

Isolate heavy execution from the main thread
Terminate an execution unit on timeout or cancellation

It is an execution boundary for responsiveness and control, not a magical prison for JavaScript.

JavaScript has watched enough escape-room videos to know better.

👀 Visualization: Variables Alone Are Not Enough

The Runtime returns an ExecutionState and snapshots for each step.

The next problem is deciding which View should display that trace.

DSA View View does not ask AI,

"Hey, does this look like Binary Search?"

on every run.

Instead, visualization candidates are detected through logic based on:

Variable names
Variable types and data structures
Whether arrays or matrices actually changed
Pointers such as left, right, and mid
The call stack
Function-entry and return history
Heap metadata
Changes across multiple steps

For example, displaying a Sort Graph whenever a number[] exists would classify algorithms that only read an input array as sorting algorithms.

So the detection logic checks whether the numeric array actually changes between steps.

It also looks for context such as sort, swap, partition, and pivot in descriptions or the call stack.

Some representative mappings are 👇

Runtime state	Displayed View
A changing numeric array	Sort Graph
An array used as a stack	Stack View
Search using `left` / `right` / `mid`	Index View
Sliding Window pointers	Sliding Window View
A two-dimensional array	Matrix View
DP arrays or rolling state	DP View
`TreeNode`	Tree Graph
`ListNode`	List Graph
Recursive function entry and return	Recursion Tree
Logic using `Map`	Map View
Logic using both `MinHeap` and `MaxHeap`	Heap View
Word Ladder-style BFS	Word Ladder View
Container / rain-water / histogram pointers	Area View
Calculator character positions and sign stack	Expression View

When multiple candidate Views are found, DSA View View assigns priorities and selects a primary Visualization.

For example, if heap state is available, Heap View takes priority over an ordinary array View.

Visualization Is Built from `ExecutionState`

Each Visualizer knows nothing about the user’s source code.

It extracts what it needs from the current ExecutionState and converts that data into View-specific state.

<BinarySearchVisualizer
  data={data}
  indexState={{
    left,
    right,
    mid,
  }}
/>

When currentStep changes, the same Visualizer receives a new state.

CSS transitions and Framer Motion animate the difference, making pointers and nodes appear to move.

This creates a clean separation of responsibilities:

Runtime creates a correct trace while preserving the original behavior
Detection decides which View best represents the trace
Visualization focuses on how to display that state

Adding a new visualization generally follows this path:

Detect the target execution state
Convert it into View-specific state
Render it with a React component
Add it to the primary-visualization selection
Add the smallest reproducible code sample as a test

🧪 Tests: Reducing the Number of "It Happened to Work" Cases

Users can write code freely, which means they can also write it in ways I never expected.

AST transformations are especially dangerous because fixing one syntax pattern can quietly break another.

So when a real issue appears, I keep the smallest version of that code as a regression test.

Examples include:

Arguments and local variables for each recursive call
Postfix i++
XOR assignment
Nested array mutations
Class constructors and super()
TreeNode / ListNode inputs
Heap operations
Binary Search and Sliding Window pointers
Word Ladder BFS state
Worker timeouts and step limits

Trusting human memory to say,

"Surely this syntax still works."

is not a particularly strong testing strategy.

Memory is surprisingly optimistic.

And it would be a little embarrassing to build a tool for avoiding confusion in DSA, only to get lost inside the tool’s own behavior.

🎯 Summary

DSA View View is not simply turning an array into a bar chart.

At a high level, it works like this:

Write TypeScript in Monaco
Analyze the source code and signature with Babel
Inject recordStep into the AST
Execute the code inside a Web Worker
Record variable snapshots and the call stack
Replay the steps with React
Display a View matching the data structure

The most important step was converting the user’s code into an array of ExecutionSteps.

Once execution becomes a sequence of steps, the same ExecutionState can power:

Pause
Forward and backward navigation
Timeline jumps
Navigation to the previous variable change
Reconstruction of recursion trees
Data-structure visualizations

The key idea is "Do not try to reverse JavaScript itself. First, transform execution into a recordable domain model".

Then,

"Runtime focuses on producing a correct trace, while Visualization focuses on presenting that trace."

Keeping Editor, Runtime, and Visualization independent from one another has been essential to making the tool extensible. Stable models such as ExecutionStep and ExecutionState connect these layers without coupling them directly.

There are still unsupported algorithms and syntax patterns, so I would love to hear from you if:

An implementation does not run
You want another data structure visualized
You think a trace would be clearer in a different View

Issues and PRs are always welcome 👇

https://github.com/nyaomaru/dsa-view-view

Now let’s run our code and watch what it is doing inside together. 👀👀

And if you enjoy the project, I would be very happy if you left a GitHub ⭐!

How I Built the Editor and Compile Pipeline for a TypeScript DSA Visualizer (DSA View View 👀👀)

nyaomaru — Wed, 22 Jul 2026 14:06:50 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer. Thanks to my daily Duolingo streak, Dutch is finally starting to sound slightly less like one extremely long word. Progress! 🦉

In my previous article, I introduced DSA View View, a tool for visualizing data structures and algorithm execution.

Features a timeline to step backward mid-loop

nyaomaru

Jul 15

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

#showdev #typescript #dsa #react

7 min read

That article covers:

Why I decided to study DSA again
What DSA View View is
How to use it
How I plan to study with it

So if this is your first time meeting Mr. View, the previous article is a good place to start.

This time, we're opening the hood.

This is the first half of the implementation story, covering everything from the moment a user writes TypeScript to the moment DSA View View generates an input form for that implementation.

We'll mainly look at:

The overall architecture and FSD
Runtime type guards with is-kit
The Monaco Editor
Static TypeScript analysis
Compilation with Babel
Extracting function signatures from the AST
Generating the Verification form

You can find the source code here:

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, MinHeap, MaxHeap, PriorityQueue, nested arrays matrices, strings, numbers, and class-style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse…

View on GitHub

All right, let's take a look together!

📝 Designing DSA View View

DSA View View has four main responsibilities:

Editor
Compile
Runtime
Visualize

There is also a Verification step in the UI, where the user provides input values before the code is executed.

The overall flow looks like below.

Each part is already a little complicated on its own, and they interact with one another quite deeply.

I could see during the design phase that a flat project structure would eventually leave future-me wandering around the repository like a lost hiker. 🌲

So I decided to use FSD (Feature-Sliced Design).

I previously wrote about how I learned FSD here.

https://dev.to/nyaomaru/lets-learn-feature-sliced-design-fsd-15bb

A simplified version of the project structure looks like this.

src/
├── app/                # App startup and global styles
├── pages/
│   └── main/           # Main page that composes the features
├── widgets/
│   ├── editor-panel/   # UI around the editor
│   ├── control-panel/  # Compile / Verification / Runtime controls
│   └── header/
├── features/
│   ├── code-editing/   # Monaco Editor, formatting, and parsing
│   ├── compilation/    # Compile behavior
│   ├── code-execution/ # AST transforms, execution, step recording, input forms
│   ├── visualization/  # Visualization detection and views
│   └── shareable-url/
├── entities/
│   ├── code/           # Code, types, and compile results
│   ├── execution/      # ExecutionState and ExecutionStep
│   ├── data-structure/ # TreeNode, ListNode, and friends
│   └── algorithm-example/
└── shared/
    ├── ui/             # Generic components such as Button, Card, and Dialog
    └── lib/            # Guards, cloning, serializers, and other utilities

For example, features/code-execution owns the behavior of executing code.

On the other hand, ExecutionState and ExecutionStep describe domain concepts, so they live in entities/execution.

Then pages/main combines the individual features and coordinates the overall flow:

After Compile succeeds, extract the signature and move to Verification
After receiving the inputs, start the Runtime
When the Runtime step changes, highlight the corresponding line in the Editor

Each slice is consumed through a public API such as index.ts, and dependencies are allowed to flow only from higher layers to lower layers.

I also verify those dependency directions and public API boundaries with architecture tests.

Drawing those boundaries helps prevent the classic.

"I changed the Runtime. Why is the Editor broken now?"

A mystery nobody ordered.

🛡️ `is-kit`: Protecting the App from `unknown` Hell

FSD can organize dependency directions, but it cannot automatically make values entering the application safe.

In DSA View View, mysterious unknown values come flying in from many directions:

AST nodes returned by Babel Parser
Messages sent between Web Workers
JSON restored from a shareable URL
Runtime snapshots recorded from user code
Arrays, trees, graphs, and heaps being inspected as visualization candidates

TypeScript is wonderfully reliable at compile time.

But at runtime, it does not interrogate a value and ask.

"Are you really an ExecutionState, or are you just wearing its name tag?"

That is where my type guard library, is-kit, comes in.

is-kit is a small, zero-dependency library for building and composing reusable TypeScript type guards.

import {
  and,
  arrayOf,
  define,
  hasKey,
  isArray,
  isNumber,
  isObject,
  isString,
  not,
  oneOfValues,
  or,
  predicateToRefine,
  type Guard,
} from "is-kit";

const isNumericString = and(
  isString,
  predicateToRefine<string>((value) => {
    return value.trim() !== "" && Number.isFinite(Number(value));
  }),
);

const isNonArrayObject = and(isObject, not(isArray));
const isNumericValue = or(isNumber, isNumericString);
const isNumericArray = arrayOf(isNumericValue);

Small guards can be combined like LEGO bricks to create more complicated runtime checks.

For example, the code that finds class methods in an AST defines a guard.

const isMethodNodeType = oneOfValues("ClassMethod", "MethodDefinition");

const hasType = hasKey("type");

const isMethodLikeNode: Guard<MethodLikeNode> = and(
  isObject,
  define<MethodLikeNode>(
    (value) => hasType(value) && isMethodNodeType(value.type),
  ),
);

After a value passes this guard, it is narrowed from a plain unknown to MethodLikeNode.

The guard can then be passed directly to filter.

const members = classNode.body.body.filter(isMethodLikeNode);

This is extremely convenient.

Without is-kit, checks like this would have multiplied across the repository:

typeof value === "object" &&
value !== null &&
"type" in value &&
Array.isArray(...)

Eventually, slightly different versions of the same guard would appear everywhere.

Six months later, I would be asking:

"What is the difference between this isObject and that isObject?"

And congratulations—we would have built a second maze inside the first maze.

At the time of writing, shared guards are used from around 69 files under src.

If Monaco and Babel are the stars on stage, is-kit is the very serious bouncer standing at every entrance to the AST, Worker, share URL, Runtime, and Visualization layers.

Mr. Unknown is not getting in.

I also use Zod in the Verification forms, but the responsibilities are different:

is-kit: Internal narrowing, filtering, and reusable runtime guards
Zod: Input form schemas, validation messages, and user-facing errors

Instead of making one library solve every problem, is-kit handles internal runtime safety while Zod handles user input validation.

I am very glad I built is-kit before building this application. Fighting all those unknown values with my bare hands would have made me the first thing that needed visualizing.

✏️ Editor

The Editor uses Monaco Editor.

Monaco is the browser-focused editor component also used by VS Code, giving the application syntax highlighting, completion, and TypeScript diagnostics.

The downside is that Monaco is not exactly tiny.

Loading everything immediately made the initial display heavier, so DSA View View first renders a lightweight textarea.

The same textarea is also used as the <Suspense> fallback, preventing the editor area from becoming empty while Monaco is loading.

<textarea
  aria-label="Code Editor"
  value={value}
  onChange={(event) => onChange(event.target.value)}
  onFocus={onActivate}
/>

Behind the scenes, DSA View View waits briefly and prepares Monaco with requestIdleCallback.

If the browser does not support requestIdleCallback, loading starts normally. If the user focuses the textarea before that, Monaco preparation begins immediately.

const CodeEditor = lazy(() =>
  prepareCodeEditorModule().then((module) => ({
    default: module.CodeEditor,
  })),
);

Once loading finishes, the lightweight editor is replaced by Monaco while preserving the same source code.

It looks like an editor, but secretly it is still a textarea.

A tiny editor body-double strategy.

Static `TypeScript` Analysis

Static analysis uses the TypeScript Worker included with Monaco.

The TypeScript Language Service runs in a separate Worker from the editor itself and returns type and syntax problems as markers.

Those markers are converted into the application's CompilationError model and used to control the Compile button and display errors.

type CompilationError = {
  line: number;
  column: number;
  message: string;
  severity: "error" | "warning";
};

The Compile button is disabled only when an error exists. Warnings alone do not prevent compilation.

One important detail is that Babel does not perform TypeScript type checking.

The responsibilities are:

Monaco's TypeScript Worker: Diagnose types and syntax
Babel: Transform TypeScript syntax into JavaScript

Keeping that distinction clear saved me from blaming Babel for crimes it did not commit.

Registering DSA Classes in the Editor

Many LeetCode problems provide classes such as TreeNode and ListNode automatically.

DSA View View also provides common classes so users do not have to declare them every time:

TreeNode
ListNode
GraphNode / _Node
TrieNode
PriorityQueue
MinHeap / MaxHeap
Deque
UnionFind / DSU
Counter

Monaco provides a mechanism called setExtraLibs, which lets the application add these type definitions to the Editor:

monaco.typescript.typescriptDefaults.setExtraLibs([
  {
    content,
    filePath: "ts:algorithm-visualizer-prepared-classes.ts",
  },
]);

However, setExtraLibs only supports type analysis inside the Editor. It does not magically create those classes at Runtime.

So the Compile and Runtime pipelines also prepend the same class definitions to the user's code as a prelude.

If the user declares a class, interface, or type with the same name, DSA View View skips injecting the prepared definition.

Imagine carefully writing your own ListNode, only for another ListNode to emerge from behind it.

That is not type safety. That is a summer horror movie.

Formatting

Formatting uses Prettier.

The Prettier core, TypeScript plugin, and Estree plugin are dynamically imported only when needed and registered as Monaco's Document Formatting Provider.

Users can therefore format their code with Command/Ctrl + S or Shift + Alt + F.

📌 From the Compile Button to Verification

So far, I have described "Compile" as if it were one large operation.

Internally, however, the FSD slice features/compilation does not own the whole flow.

When the user presses the Compile button, pages/main coordinates these operations:

features/compilation checks whether the TypeScript can be transformed into JavaScript
The parser in features/code-editing extracts the function or class signature
If everything succeeds, the UI moves to Verification
features/code-execution displays an input form matching that signature

To the user, this feels like one continuous Compile step.

Inside the application, each responsibility remains separate.

Transforming `TypeScript` with Babel

The application uses Babel to transform TypeScript.

const prepared = prepareTypeScriptCodeWithClasses(code);

const result = transform(prepared.code, {
  presets: ["typescript"],
  filename: "input.ts",
});

DSA View View runs entirely in the browser, so it is not invoking tsc on a Node.js server.

Instead, it uses @babel/standalone to transform TypeScript syntax into JavaScript in the browser.

Before transformation, the application prepends any prepared classes that the user has not declared themselves.

If the source contains imports for those prepared classes, they are removed because the browser execution environment cannot resolve those modules.

Again, an important reminder:

Babel's TypeScript preset primarily removes type information. It does not type-check the program.

Monaco handles type errors. Babel checks whether the syntax can be transformed.

The generated JavaScript from this stage is also not executed directly on the main thread.

For the Runtime, the original source is instrumented separately and then executed inside a Web Worker.

That is the fun part—and the topic of the next article.

Extracting Function Signatures from the AST

After Compile succeeds, DSA View View needs to build an input form.

Suppose the user writes this function:

function trap(height: number[]): number {
  // ...
}

The source code is parsed into an AST with Babel Parser, and DSA View View extracts information like this:

{
  name: "trap",
  parameters: [
    {
      name: "height",
      type: "number-array",
      optional: false,
    },
  ],
  returnType: "number",
}

The parser supports more than ordinary function declarations:

Function declarations
Arrow functions assigned to variables
Function expressions assigned to variables
LeetCode-style factory functions that return another function
Class declarations

For a class, the parser extracts the constructor and callable methods. private methods are currently excluded.

For class-design problems such as LRUCache and MedianFinder, it extracts the class name, constructor, method names, and arguments.

When the source contains multiple helper classes, DSA View View avoids prioritizing prepared classes as solution candidates and compares the number of callable methods to select the likely design class.

This selection is heuristic, so it cannot perfectly identify every possible class structure yet.

There are always more creative ways to write JavaScript than I expect. JavaScript considers this a feature.

Generating the Verification Form

For ordinary functions, the input form is built from the extracted signature using React Hook Form and Zod.

Supported input types include:

number
string
boolean
number[] / string[] / boolean[]
number[][] / string[][] / boolean[][]
TreeNode
ListNode
GraphNode / _Node

The input UI and validation behavior change depending on the type.

For example, a number[] accepts both:

1, 2, 3

and:

[1, 2, 3]

Both formats are converted into a real array that can be passed to the Runtime.

For TreeNode, the application constructs a tree from a level-order array.

When a problem has multiple TreeNode parameters, users can also select a specific node from the first root.

For ListNode, users can build a linked list from an array or node-based input and specify the cycle position.

For GraphNode, a cyclic graph structure is constructed from a LeetCode-style adjacency list.

Class-design problems use a different UI.

Instead of the normal parameter form powered by React Hook Form and Zod, DSA View View displays the same Operations and Arguments JSON format used by LeetCode.

For example, MedianFinder uses:

Operations: ["MedianFinder", "addNum", "addNum", "findMedian"]
Arguments:  [[], [1], [2], []]

This form validates class-design-specific requirements, including:

The number of operations matches the number of argument lists
The first operation matches the class name

So the Compile button starts a chain of separate responsibilities:

Babel verifies that transformation is possible
AST analysis extracts the signature
The Verification layer generates the appropriate input form
pages/main connects the entire flow from the Editor to Verification

🎯 Summary

In this article, we followed the path from writing TypeScript in DSA View View to generating the inputs needed for execution.

The broad flow is:

Render a lightweight textarea first
Prepare Monaco Editor in the background
Diagnose types and syntax with the TypeScript Worker
Use Babel to check whether the TypeScript can be transformed into JavaScript
Extract the function or class signature from the AST
Generate a Verification form based on the detected types

The important design decision was not forcing the Editor, diagnostics, syntax transformation, and input UI into one giant operation.

Instead:

is-kit safely narrows unknown values from the AST, Workers, JSON, and runtime snapshots
Monaco's TypeScript Worker diagnoses types and syntax
Babel transforms TypeScript syntax into JavaScript
AST analysis extracts the signature needed by the Verification UI
The Verification form validates inputs and converts them into Runtime values
pages/main connects the separate steps and advances the UI

Keeping those responsibilities separate made the flow much easier to understand and extend.

In the next article, we will finally enter the heart of DSA View View: the Runtime.

That is where Mr. View stops politely waiting beside the Editor and starts watching every move your variables make. 👀

There are still unsupported patterns and types, so Issues and PRs are always welcome!

And if you enjoy the project, I would be very happy if you left a GitHub ⭐!

https://github.com/nyaomaru/dsa-view-view

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

nyaomaru — Wed, 15 Jul 2026 12:04:25 +0000

Hoi hoi!

I’m @nyaomaru, a frontend engineer currently fighting the intense European heatwave by building DIY window screens here in the Netherlands. 🛠️

https://medium.com/data-science-collective/should-you-still-learn-to-code-in-2026-034685e17707

As this article also discusses, I believe that improving our fundamental engineering skills is still essential in the age of AI.

Imagine that AI makes an F1 car fully autonomous. 🏎️

Would you let someone without even a driver’s license enter a race as its driver?

Or imagine that AI completely automates maintenance during pit stops.

Would you put someone who knows absolutely nothing about cars, their parts, or their internal structure in charge of that AI?

AI is certainly reducing the amount of code we need to write by hand. Typing quickly and memorizing every small piece of syntax or every method are becoming less important.

But can we confidently release a product without understanding its fundamental concepts or implementation? If something goes wrong in production, can we take responsibility and fix it?

My answer was no.

Building things faster is obviously a good thing. But if we build without understanding, we may simply produce fragile software with no long-term sustainability at a faster rate.

The real value comes from building meaningful things quickly.

Then, how can we develop the fundamental skills we still need in the AI era?

I believe one useful approach is learning DSA: Data Structures and Algorithms. So I decided to start learning DSA again.

However, while solving problems on LeetCode, I repeatedly ran into the same problem.

I want to visualize the data flow and understand what is happening, but I still can’t clearly see it.

So I used the skills I have developed through frontend engineering and built a tool that visualizes the execution flow of DSA implementations! 🚀

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, nested arrays, matrices, strings, numbers, and class style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse by category, and jump into…

View on GitHub

In this article, I’ll explain how DSA View View works and how we can use it to study DSA.

Let’s take a look together!

Disclaimer
I may sound confident so far, but I’m definitely not a DSA expert. I’m still learning, just like many of you.

In fact, I built this tool precisely because I was struggling. When I realized that I couldn’t immediately solve Binary Search, I started to panic a little. 😸

🖥️ What Is DSA View View?

DSA View View is a tool that executes functions and classes written in TypeScript and lets you inspect how variables and return values change on each line through a runtime timeline.

The easiest way to understand is to try it yourself!

Open the tool and click the Run Demo button.

You’ll quickly see how the workflow works:

Write your implementation
Compile it
Enter the input values
Run it

That’s really it.

Although I created it primarily for DSA problems, you can also use it to inspect and test smaller TypeScript implementations.

And, of course, it’s completely free!

🤔 What Can It Do?

With DSA View View, you can:

Write DSA implementations in TypeScript
Test implementations with different input values
Move forward and backward through runtime steps
Visualize supported data structures and algorithms
Review LeetCode solutions and confirm your understanding

You can also use it as a lightweight environment for executing functions or formatting code blocks for technical articles such as Dev.to 😸

Feel free to experiment with it and find your own use cases!

🧑‍🏫 How to Use It

The main workflow consists of three modes:

Editor
Verification
Runtime

Let’s look at each one.

Editor

First, write your implementation!

The Editor is designed to feel similar to a basic IDE.

TypeScript diagnostics are available by default, so the editor can detect some errors while you write.

You can also press Cmd/Ctrl + S to format your code with Prettier, so feel free to write first and clean it up afterward.

Common classes used in DSA problems, such as TreeNode and ListNode, are already available.

You don’t need to declare or import them every time.

You can also define your own classes or replace the provided definitions when necessary.

Once your implementation is ready, click Compile Code.

If compilation fails, the tool displays the relevant location and error message so that you can fix it.

There is also an Example menu containing several common implementations.

For example, if you want to quickly inspect a Heap Sort implementation and see how it behaves, you can load the example instead of writing everything manually.

Verification

In Verification mode, you define the input values that should be passed to your function or class.

Enter a test value for each argument.

For arrays, both of the following formats are supported:

[1, 2, 3]

1, 2, 3

Once your input values are ready, click Run.

Runtime

Finally, let’s inspect the runtime!

When you click Run in Verification mode, your implementation is executed.

Runtime mode then lets you play through the execution steps or move backward and forward manually.

When the tool recognizes supported logic, an additional visualization is displayed in a modal.

Not every possible implementation is supported yet, of course. If something you need is missing, I would be happy to receive an issue or pull request!

You can move backward and forward through the executed lines to inspect:

Which line is currently running
How variables change
Where values are returned
How the execution reaches its final result

You can return to the beginning, jump directly to the end, or move through the timeline one step at a time.

The main execution process runs entirely in the browser.

Share 🐈

DSA View View also includes a sharing feature.

You can create a URL that preserves your implementation and share it with someone else.

Use the Share button at the top of the page to post it on social media or copy the link directly.

Share your implementations, compare different solutions, and let’s learn together!

Important: The shared URL contains your implementation. Do not paste private, confidential, or proprietary code into the tool before sharing it.

What Is That Thing in the Top-Right Corner? 👀👀

Meet Mr. View.

Mr. View watches over your implementation.

Nothing more.

Nothing less.

He is simply there to support you.

When you need to concentrate, press the TV button to hide him. Press it again to bring him back.

However, if Mr. View is enough to distract you, you may not be ready for an attack from ten simultaneous Slack notifications. 😸

✏️ How Should We Study DSA?

Now you know how to use DSA View View.

The next question is probably

Which problems should I solve?

LeetCode is an obvious place to start, and the study plan from Tech Interview Handbook also provides a useful collection of practice problems. 👇

https://www.techinterviewhandbook.org/coding-interview-study-plan/

Try solving these problems with DSA View View.

Once your implementation works, use the runtime timeline to inspect the data flow and understand exactly how the algorithm reaches its answer.

You can also use tools such as ChatGPT, Codex, Claude, Claude Code, Gemini, and Grok to explore your solution further.

Don’t limit yourself to asking

Is this implementation correct?

Try asking questions such as:

What would happen if I rewrote this DFS solution using BFS?
Could Dynamic Programming solve this problem?
Are there any other reasonable approaches?
What are the time and space complexities?
Why is this approach better than the alternatives?
Under which conditions would another approach be better?

AI becomes much more useful for learning when it helps us compare and understand different approaches instead of only generating a final answer. 👍

Why TypeScript Instead of Python? 🐍

The simple answer is that TypeScript is my favorite language.

I mainly work as a frontend engineer, so TypeScript is also the language in which I feel most comfortable experimenting and learning.

However, I designed the tool so that additional languages could be supported in the future.

If there is enough demand for another language, please leave a comment or open an issue!

🎯 Conclusion

AI is helping us write code faster and faster.

However, understanding what happens inside an implementation remains an important engineering skill.

In fact, I believe that this ability may become even more valuable as AI-generated code becomes increasingly common.

I built DSA View View because I wanted a tool that could help me strengthen those fundamental skills from the ground up.

To be honest, I still have a lot to learn about DSA.

That is exactly why I hope we can learn together.

Please leave a comment or open an issue if:

You want support for a particular problem or data structure
You have an idea for a new visualization
You find a bug
You want support for another programming language

Let’s train our DSA muscles together! 💪😸

If you like it, please give a star ⭐

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, nested arrays, matrices, strings, numbers, and class style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse by category, and jump into…

View on GitHub

And I also launched on ProductHunt! Come say hello and let me know what you think 😸 👇

producthunt.com

Trying Declarative Partial Updates: A Future API for Replacing HTML Later

nyaomaru — Wed, 01 Jul 2026 12:42:05 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who was cheering for the World Cup during tropical nights in the Netherlands while nearly melting from heat exhaustion. 🫠⚽ (But yesterday was comfortable 😺)

How do you usually build frontend applications?

Do you build SPAs with React / Vue / Svelte?

Do you use SSR / SSG / ISR frameworks like Next / Remix / Nuxt / Astro?

There are many ways to build frontend applications, but today it is very common to update the DOM on the client side using JavaScript.

Even when using UI libraries and frameworks like React / Vue / Svelte, or SSR frameworks like Next / Remix / Nuxt / Astro, there are still many cases where part of the screen is eventually updated by client-side JavaScript.

But is that really always the best answer?

Are there cases where we are forcing JavaScript on the client to handle work that could naturally be handled on the server?

In response to that kind of question, the Chrome team introduced an experimental API called DPU, or Declarative Partial Updates. 🚀

Declarative partial updates | Blog | Chrome for Developers

Learn about new out-of-order streaming capabilities and the renewed HTML insertion and streaming methods available for testing from Chrome 148

developer.chrome.com

In this article, I want to explore what Declarative Partial Updates are, what problems they try to solve, and why they might matter.

I will focus especially on the out-of-order streaming mechanism that can replace parts of HTML later without writing client-side JavaScript for the replacement itself.

Let's dive in!

🧩 What are Declarative Partial Updates?

Declarative Partial Updates are, roughly speaking

A mechanism where you declare part of your HTML as “this area will be replaced later”, and then update only that part with HTML that arrives later.

For example, imagine you want to return the overall page HTML immediately, but some data is slower to fetch.

The header is instant
The layout is fast
The user profile is also pretty fast
But only the recommendations API is slow

In that case, we often show a loading state on the client, fetch data, and update the DOM with JavaScript. In React, you might reach for something like <Suspense>.

With DPU, the server can first return HTML like this.

<section>
  <h2>Recommendations</h2>

  <?start name="recommendations">
    <p>Loading recommendations...</p>
  <?end>
</section>

The area surrounded by <?start name="recommendations"> and <?end> is a region that can be replaced later.

Then, when the recommendations HTML is ready on the server, it can stream HTML like this later.

<template for="recommendations">
  <ul>
    <li>Advanced CSS Layouts</li>
    <li>Modern HTML APIs</li>
    <li>Web Performance Basics</li>
  </ul>
</template>

At that point, the browser finds the region named recommendations and replaces the loading UI with the contents of this <template>.

Wait, does that feel a bit weird?

Exactly. The wild part is that up to this point, we did not write any JavaScript for the replacement, and no framework is involved.

In other words, you no longer need to write client-side JavaScript like this just to replace that area:

const element = document.querySelector("#recommendations");
element.innerHTML = html;

You stream HTML, and the browser understands where that HTML should go.

That is the interesting part of Declarative Partial Updates.

DPU also has <?marker>, not only <?start> / <?end>.

<?marker> is basically a marker that says, “insert later HTML here.”

<div>
  <?marker name="placeholder">
</div>

<template for="placeholder">
  <p>Here is streamed content!</p>
</template>

In this case, the browser finds the marker named placeholder and inserts the contents of the later <template for="placeholder"> at that position.

On the other hand, the <?start> / <?end> pair used mainly in this article is for showing placeholder content, such as a loading UI, and replacing that entire range later.

So, roughly

<?marker> means “insert here”
<?start> / <?end> means “replace this range”

That mental model should be enough to start.

Note

<?marker> can also be used by leaving the same marker inside streamed content, which lets you append list items one by one. That is pretty interesting too.

In the first half of this article, I focus mainly on replacing loading UI, so I mostly use <?start> / <?end>.

In the later sample, I also try an example that uses <?marker> to append asset links sequentially.

🤔 Why do we need Declarative Partial Updates?

At this point, you might think

Wait, frameworks like React or Astro can already do this, right?

Yes. They can.

With React / Vue / Svelte / Next / Remix / Nuxt / Astro, you can show loading states, receive API results, and update parts of the screen. Many of us do this every day.

But wait a second. A lot of that is implemented by client-side JavaScript updating the DOM, right?

A common flow looks like this:

The server returns HTML
The browser displays the HTML
Client-side JavaScript is loaded
JavaScript calls an API
The API result is put into state
The framework updates the DOM

Of course, this is an extremely common frontend architecture today.

But if part of the screen is “something the server can already produce as HTML”, do we really need to make client-side JavaScript do that work every time?

For example, the recommendations HTML can be generated on the server like this:

<ul>
  <li>Advanced CSS Layouts</li>
  <li>Modern HTML APIs</li>
  <li>Web Performance Basics</li>
</ul>

If all we want to do is send that to the browser, it can feel a bit indirect to do this.

fetch("/api/recommendations")
  .then((res) => res.json())
  .then((items) => {
    setRecommendations(items);
  });

You fetch JSON, convert it to HTML on the client, update state, and then update the DOM.

That is convenient, but it is also a bit roundabout.

What makes DPU interesting is that it points in another direction

If the server can produce HTML, why not stream that HTML directly and let the browser insert it into the right place?

So DPU is not a replacement for React / Vue / Svelte. It is more like a lower-level browser primitive.

It may allow the browser to understand, as part of HTML itself, some of the partial update work that frameworks currently handle.

If that happens, the boundary between client-side responsibility and server-side responsibility becomes even more important.

What can be done with HTML?
What should be done with JavaScript?

By redesigning these boundaries and declaring things in a way that fits the browser, we may be able to unlock browser capabilities that we are not fully using yet.

But we should not misunderstand the client still has responsibilities.

This discussion is not about replacing state management, and interactive features still need JavaScript.

For example, forms, modals, charts, and similar UI should still be managed on the client side, while static text or server-generated HTML based on slower API responses may be a better fit for HTML streaming.

The responsibility split becomes more complex, but the UX may improve a lot. This is definitely something worth watching.

🏠 This may expand what SPAs can do

DPU is not about rejecting SPAs.

Personally, I see it as something that may expand the possibilities of SPAs.

Until now, SPAs have often followed this mental model.

Fetch data as JSON
    ↓
Put it into client-side state
    ↓
Re-render components
    ↓
Update the DOM

But if DPU and the new HTML insertion / streaming APIs become available, another option appears.

The server returns HTML
    ↓
HTML is streamed
    ↓
The browser inserts it into the existing DOM

That means an SPA could potentially choose different update strategies for different parts of the UI:

Fetch JSON and render on the client
Generate HTML on the server and insert it directly
Return only the shell initially, then stream slower parts later
Perform page-transition-like updates with HTML partials

That is really interesting.

SPAs often carry the image of “doing everything with client-side JavaScript”, but they may become more hybrid in the future. The meaning of the word SPA itself may change.

State that belongs on the client stays on the client
HTML that can be produced on the server is produced on the server

And the browser does not merely display that HTML. It also understands where and how to insert it.

If this direction continues, frontend architecture may become even more flexible and deeper than it is today.

🧪 APIs for streaming HTML from JavaScript are also coming

The interesting part of DPU is not only out-of-order streaming with <template for="...">.

The Chrome team is also proposing a new set of APIs for inserting and streaming HTML from JavaScript.

Even today, there are several ways to dynamically insert HTML.

element.innerHTML = html;
element.outerHTML = html;
element.insertAdjacentHTML("beforeend", html);

But they all have slightly different behavior.

For example:

Does it overwrite existing content?
Does it append after the existing content?
Are <script> tags executed?
What happens with sanitization?
How does it interact with Trusted Types?

There are a lot of subtle differences.

Honestly, I do not think many developers can confidently explain all of those differences from memory. I definitely cannot.

The new APIs try to make HTML insertion easier to understand with more consistent names.

For example, static HTML insertion looks like this.

const newHTML = "<p>This is a new paragraph</p>";
const contentElement = document.querySelector("#content-to-update");

contentElement.setHTML(newHTML);

This is not an API that appends to the end, like insertAdjacentHTML("beforeend", html). It replaces the existing contents of contentElement with newHTML.

A useful way to understand the difference is

setHTML() is the safer API that runs through a sanitizer
setHTMLUnsafe() disables the sanitizer by default and lets you handle HTML more directly

Then comes the really interesting part of streaming versions.

const contentElement = document.querySelector("#content-to-update");

const response = await fetch("/api/content.html");

response.body
  .pipeThrough(new TextDecoderStream())
  .pipeTo(contentElement.streamHTMLUnsafe());

This is pretty wild.

It means we may be able to take HTML returned by fetch() and stream it directly into an element without waiting for the entire response to finish downloading.

SPAs have not benefited much from HTML streaming after the initial document load.

The initial document can be streamed from the server, but later screen updates often become JSON fetch + client render.

With APIs like this, SPA updates may also be able to benefit from HTML streaming.

That is why I think this may expand the possibilities of SPAs.

⚠️ “unsafe” does not mean “never use it”

When you see a name like streamHTMLUnsafe(), you might think

Unsafe!? That sounds terrifying.

I thought that too at first.

But this unsafe does not mean “you must never use it.” It is closer to a warning that the sanitizer is disabled by default, so you need to think carefully about whether the input is trusted.

For example, it would be dangerous to stream user-generated HTML directly into the DOM.

But if the HTML is generated by your own trusted server, there may be valid use cases.

Of course, before using this in production, you need to think carefully about sanitizers, Trusted Types, script execution, browser support, and other security concerns.

➕ What happens when DPU and the streaming APIs are combined?

This is the most interesting part.

DPU’s <template for="..."> and the new HTML streaming APIs are separate APIs.

But combining them makes the story even deeper.

For example, imagine placing placeholders in an SPA screen.

<main>
  <?start name="page-title">
    <h1>Loading...</h1>
  <?end>

  <?start name="page-content">
    <p>Loading content...</p>
  <?end>
</main>

Then, during a page update, the server streams HTML.

<template for="page-title">
  <h1>Dashboard</h1>
</template>

<template for="page-content">
  <section>
    <p>This is the dashboard content.</p>
  </section>
</template>

Instead of manually targeting the DOM with JavaScript.

document.querySelector("#page-title").innerHTML = titleHTML;
document.querySelector("#page-content").innerHTML = contentHTML;

the browser may be able to understand where page-title and page-content should be applied.

In other words, even in SPA-style page transitions, something like this may become possible.

Fetch a new page's HTML partial
    ↓
Stream the HTML
    ↓
Update only the necessary places via template for

Part of the work that frameworks currently handle with Virtual DOM, compilers, or fine-grained reactivity may be shifted to browser-native HTML streaming / partial updates.

That makes DPU feel like more than just a small HTML API. It feels like something that could expand the design space of frontend architecture.

Of course, this is still experimental. This is not a “let's all use this in production right now” kind of API.

But the old assumption

An SPA fetches JSON and renders on the client

may start to change.

HTML may evolve from “a static document loaded once at the beginning” into “a UI unit that can be streamed, replaced, and updated.”

That is pretty exciting, right?

🚀 Trying it with Node.js DPU samples

So far, we have talked about the concept. I also built a small Node.js sample app to try this out.

nyaomaru / declarative-partial-updates-sample

Sample repository for DPU (Declarative Partial Updates)

Declarative Partial Updates sample

A small Node.js sample app for trying Chrome's experimental Declarative Partial Updates (DPU) feature.

Images under public/ are served through the Node.js stream handler at /public/... then inserted from later DPU or HTML streaming chunks.

Styles live in public/styles.css. Shared timing and image constants live in features/shared.mjs, while public asset metadata and GitHub links live in features/public-assets.mjs so the sample behavior is easier to inspect and adjust.

The server is split by feature:

features/home/: DPU document streaming sample HTML and stream chunks
features/hybrid-shell/: hybrid shell HTML and route partial HTML
features/set-apis/: static and streaming HTML insertion sample HTML
features/public-assets.mjs: public asset metadata and stream handler
features/layout/: shared document layout HTML
features/layout.mjs: layout template renderer
features/shared.mjs: common helpers and demo timing constants
public/html-stream.js: client-side static / streaming HTML insertion helper

Run

npm start

Open:

http://localhost:3000/…

View on GitHub

Note

This is an experimental feature, so you need Chrome Canary (Chrome v148 or later) or a Chrome build that includes this feature, with the experimental flag enabled.

Open the following URL in Chrome’s address bar:

chrome://flags/#enable-experimental-web-platform-features

Enable it, click “Relaunch”, and then run the sample. This article assumes a supported build with this flag enabled.

The demo app has roughly three pages:

/              ... Document streaming
/hybrid-shell  ... Hybrid shell + streamed HTML route updates
/set-apis      ... Static / Streaming HTML APIs

The first page, /, demonstrates DPU out-of-order streaming.

The server first returns an HTML shell, and slower server-rendered fragments are streamed later as <template for="...">.

For example, the initial HTML contains a placeholder.

<article class="panel">
  <h2>Recommendations</h2>

  <?start name="recommendations">
    <p class="loading">Waiting for recommendations...</p>
  <?end>
</article>

At this point, the browser shows the loading UI.

Then, once the recommendations HTML is ready on the server, it streams a chunk.

<template for="recommendations">
  <ul class="list">
    <li>Advanced CSS Layouts</li>
    <li>Modern HTML APIs</li>
    <li>Web Performance Basics</li>
  </ul>
</template>

The browser finds the DPU range named recommendations and replaces the loading UI with the list.

On this page, I stream multiple named regions at different timings, not only recommendations:

hero image
metric
asset strip
team activity
streamed code block

The asset strip also uses <?marker>. The initial HTML has a marker.

<section class="panel asset-panel">
  <h2>Streamed public assets</h2>
  <div class="asset-grid">
    <?marker name="asset-list">
  </div>
</section>

Then the server streams chunks one by one whenever each asset link becomes ready.

<template for="asset-list">
  <!-- streamed asset link -->
  <?marker name="asset-list">
</template>

By leaving the same marker again inside the streamed content, the next asset link can continue to be appended in the same place.

So HTML does not have to wait until everything is complete from top to bottom. Fragments can be streamed in later as soon as they are ready.

That is the really interesting part of DPU.

Note

<template for> has several subtle rules, including constraints related to parent elements.

This demo is a sample for exploring the direction of the API, but if you want to use it in production someday, you should carefully check the applicable range of <template for>, DOM movement during streaming, Trusted Types, sanitizers, and related details.

🌓 Trying a hybrid shell style architecture

Next, /hybrid-shell demonstrates streaming HTML route updates inside a hybrid shell style architecture.

This is not a “pure SPA where everything is rendered on the client”. It is closer to an architecture where the whole document is not reloaded, the URL changes through the History API, and only the route content inside the shell is updated.

The goal is

Keep client-side state alive, while replacing only the route content with server-generated HTML.

For example, this page has a counter:

<div>
  Counter: <strong id="counter">0</strong>
  <button id="increment" class="primary" type="button">Increment</button>
</div>

This counter is managed by client-side JavaScript.

document.querySelector("#increment").addEventListener("click", () => {
  counter.textContent = String(Number(counter.textContent) + 1);
});

So this is clearly a client-side responsibility.

On the other hand, route content is fetched from the server as HTML.

const loadRoute = async (route, { push = false } = {}) => {
  setActiveRoute(route);

  if (push) {
    const nextUrl =
      route === "dashboard"
        ? "/hybrid-shell/dashboard"
        : `/hybrid-shell/${route}`;
    window.history.pushState({ route }, "", nextUrl);
  }

  const response = await fetch(`/partials/hybrid-shell/${route}`);
  view.replaceChildren();

  if ("streamHTMLUnsafe" in Element.prototype && response.body) {
    await response.body
      .pipeThrough(new TextDecoderStream())
      .pipeTo(view.streamHTMLUnsafe());
    return;
  }

  const template = document.createElement("template");
  template.innerHTML = await response.text();
  view.replaceChildren(template.content.cloneNode(true));
};

What this does is not “fetch JSON and render components on the client.” Instead, it streams HTML generated by the server directly into the view.

The counter state remains on the client.

That means we can split responsibilities:

Interactive state such as the counter belongs to the client
Server-generated route body can be streamed as HTML

This feels close to the thinking behind island architecture in frameworks like Astro / Fresh.

Instead of making the client do everything, we separate HTML that can be returned statically or from the server from interactive client state.

Personally, I find this very interesting.

At the very least, a shell with SPA-like navigation does not have to mean “everything is rendered by client-side JavaScript.” It may also expand into a hybrid shape that combines client state with streamed HTML.

Note

This /hybrid-shell sample is not a demo that replaces a range inside the shell using DPU’s <?start> / <template for>.

The Chrome team article also introduces the possibility of SPA-style page loads by combining streamHTMLUnsafe() and <template for>.

However, in my local tests, I could not confirm that streaming <template for="..."> into streamHTMLUnsafe() in this shell architecture updates an existing DPU range.

The SPA-style page load described in the official article seems to point toward an outline page with processing instructions, where the new page’s <template for> elements are streamed toward the end of the HTML and slotted into those instructions.

So in this /hybrid-shell sample, I do not handle DPU range replacement. Instead, I use the HTML streaming insertion API to stream server-generated route partials directly into #hybrid-shell-view.

🎁 Trying Static / Streaming HTML APIs

Finally, /set-apis tries the new HTML insertion / streaming APIs separately from DPU’s out-of-order streaming.

This page first checks whether the browser has the APIs.

support.innerHTML = `
  <ul class="list">
    <li>setHTMLUnsafe: ${"setHTMLUnsafe" in Element.prototype}</li>
    <li>streamHTMLUnsafe: ${"streamHTMLUnsafe" in Element.prototype}</li>
  </ul>
`;

For static insertion, if setHTMLUnsafe() is available, the demo uses it. Otherwise, it falls back to <template> and replaceChildren().

if ("setHTMLUnsafe" in Element.prototype) {
  staticTarget.setHTMLUnsafe(markup);
  return;
}

const template = document.createElement("template");
template.innerHTML = markup;
staticTarget.replaceChildren(template.content.cloneNode(true));

For streaming insertion, it pipes the fetched HTML response directly into streamHTMLUnsafe():

const response = await fetch("/partials/set-apis/stream");

streamTarget.replaceChildren();

if ("streamHTMLUnsafe" in Element.prototype && response.body) {
  await response.body
    .pipeThrough(new TextDecoderStream())
    .pipeTo(streamTarget.streamHTMLUnsafe());
  return;
}

If this works, we can stream chunks into an existing element as they arrive, instead of waiting until the entire HTML response has downloaded and inserting it all at once.

Traditionally, SPAs could benefit from HTML streaming for the initial document, but subsequent screen updates often became JSON fetch + client render.

With APIs like this, SPAs may be able to benefit from HTML streaming even for later updates.

That is the exciting part of DPU and the new HTML streaming APIs.

The static insertion partial is returned from /partials/set-apis/static, and the streaming insertion partial is returned from /partials/set-apis/stream.

🎯 Summary

In this article, I looked at Declarative Partial Updates introduced by the Chrome team.

Declarative Partial Updates are, roughly

A mechanism where you declare part of your HTML as “this area will be replaced later”, and then update only that part with HTML that arrives later.

Of course, DPU does not replace React / Vue / Svelte / Next / Remix / Nuxt / Astro.

Interactive UI, client-side state management, forms, modals, charts, drag and drop, and similar features still need JavaScript.

But on the other hand, there may be more cases where we do not need to handle everything with client-side JavaScript.

HTML that can be generated on the server should be generated on the server
State that should be managed on the client should be managed on the client

And the browser may come to understand not only how to display HTML, but also where streamed HTML should be inserted.

If this responsibility split progresses, frontend architecture may become more hybrid.

Especially for SPAs, there may be another path beyond

Fetch JSON and render on the client

Instead, we may also be able to

Fetch / stream HTML partials and update via browser-native behavior

I do not see this as the end of SPAs. I see it as something that may expand what SPAs can do.

This is still experimental, so it is not an API to use in production right away.

But the direction where HTML changes from “a document loaded once at the beginning” into “a UI unit that can be streamed, replaced, and updated” feels very important for the future of frontend development.

DPU is definitely something to keep an eye on. 😺

References

https://developer.chrome.com/blog/declarative-partial-updates?hl=en

https://github.com/WICG/declarative-partial-updates

https://github.com/GoogleChromeLabs/template-for-polyfill

https://github.com/GoogleChromeLabs/html-setters-polyfill

https://github.com/nyaomaru/declarative-partial-updates-sample

The Difference Between satisfies, as, and Generics in TypeScript

nyaomaru — Wed, 17 Jun 2026 12:43:50 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who recently obsessed with playing video game of "inscryption". 🃏

In TypeScript, there are several syntaxes that look like they are "specifying a type."

For example:

as
satisfies
generics using T extends xxx

But these are not the same thing.

Roughly speaking:

as asks TypeScript to trust you
satisfies asks TypeScript to check the value
generics let you encapsulate that check inside an API

They all look type-related, but the responsibility lives in different places.

You may see AI-generated code overusing as, or codebases using satisfies casually, or libraries using generics to enforce stricter APIs. These patterns appear quite often in real-world development.

In this article, I want to explain the difference between as, satisfies, and generics not as "ways to specify a type," but as ways to decide where type responsibility should live.

Let's jump in.

🙏 `as` asks TypeScript to trust you

In TypeScript, as lets you tell the compiler:

Please treat this value as this type, please 😭

For example, the runtime value below is still a string, but TypeScript treats it as a number.

const value = "123" as unknown as number;

console.log(typeof value); // "string"

value.toFixed();
// TypeScript thinks this is a number, so there is no compile-time error.
// But at runtime, this throws: "value.toFixed is not a function"

The important point is 👇

as does not transform the runtime value.

So using it for external data can be very dangerous.

type User = {
  id: string;
  name: string;
};

const user = JSON.parse(input) as User;

This does not check whether the parsed value is actually a User.

It only tells TypeScript:

Trust me. This is a User. Maybe.

In other words, as is for cases where a human knows something TypeScript cannot know.

It is useful, but it does not guarantee anything by itself.

If you write as, the responsibility is on you.

🔍 `satisfies` asks TypeScript to check the value

Now let's look at satisfies, which was introduced in TypeScript 4.9.

type RouteConfig = Record<
  string,
  {
    path: string;
    label: string;
  }
>;

const routes = {
  home: {
    path: "/",
    label: "Home",
  },
  about: {
    path: "/about",
    label: "About",
  },
} satisfies RouteConfig;

With this, TypeScript checks whether the declared value matches the expected type structure.

For example, if you add a property that does not exist on a route item, TypeScript reports an error.

const routes = {
  home: {
    path: "/",
    label: "Home",
  },
  about: {
    path: "/about",
    label: "About",
    nyaomaru: "cat", // Type error: nyaomaru does not exist on the route item type 😼
  },
} satisfies RouteConfig;

The interesting part is 👇

Even though routes is checked against RouteConfig, the type of routes itself is not collapsed into RouteConfig.

routes is checked as RouteConfig.

But the inferred type of routes remains close to the actual object literal you wrote.

So keyof typeof routes becomes the union of the actual keys, not just string.

type RouteName = keyof typeof routes;
// "home" | "about"

In other words, satisfies checks that a value satisfies a given type while preserving the original inference as much as possible.

Compare that with a regular type annotation.

const routes: RouteConfig = {
  home: {
    path: "/",
    label: "Home",
  },
  about: {
    path: "/about",
    label: "About",
  },
};

type RouteName = keyof typeof routes;
// string

When you annotate routes as RouteConfig, TypeScript treats it as RouteConfig.

Since RouteConfig is a Record<string, ...>, RouteName becomes string.

So when you want to validate a value against a type while keeping the concrete information from the actual value, satisfies is often a better fit.

In short:

satisfies checks that a value matches a type without unnecessarily widening the value's inferred type.

🎁 Generics encapsulate the check inside an API

At this point, you might think:

Okay, then I should just use satisfies everywhere. 😹

And yes, sometimes that works well.

But writing satisfies every time can be annoying.
And if someone forgets to write it, the intended check disappears.

So what if we move that check into a function?

That is where generics come in.

As a quick recap, we could write this

const routes = {
  home: {
    path: "/",
    label: "Home",
  },
} satisfies RouteConfig;

But we can also wrap the pattern inside a function using generics.

function defineRoutes<const T extends RouteConfig>(routes: T) {
  return routes;
}

const routes = defineRoutes({
  home: {
    path: "/",
    label: "Home",
  },
});

Nice and clean.

Now we get:

validation that the value matches RouteConfig
preservation of the concrete key "home"
no need for users to write satisfies every time

But then this appears

<const T extends RouteConfig>

What is going on here???

Let's break it down.

T extends RouteConfig means: "T must be assignable to RouteConfig."
const T asks TypeScript to infer object literals and array literals as narrowly as possible.

Here, const is not the same as a const variable declaration.

It is not about whether a value can be reassigned.

It is about making generic type parameter inference preserve literal information as much as possible.

📊 Comparing the three with config objects

Here is the comparison so far.

Syntax	What it does	Main responsibility
`as Type`	Asks TypeScript to believe the value is that type	The person writing the code
`satisfies Type`	Checks whether the value matches the type	The value declaration
`<T extends Type>`	Constrains what an API can accept	The API designer

So, in casual terms:

as means: "Trust me. 🙏"
satisfies means: "Please check if this is correct. 🔍"
generics mean: "Only pass values that fit this API. 🎁"

So far, we have looked at config objects.

But in real-world development, this difference becomes even more important when dealing with external data.

API responses, localStorage, URL params, and form input cannot be protected by TypeScript types alone.

For those values, we need runtime guards.

And once we start writing runtime guards by hand, another problem appears 👇

The existing TypeScript type and the handwritten schema can drift apart.

🤔 Thinking through `typedStruct`

This becomes easier to understand if we use a small validator API as an example.

I'll use my type guard library, is-kit.

nyaomaru / is-kit

Lightweight, zero-dependency toolkit for building `isFoo` style type guards in TypeScript. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨. npm -> https://www.npmjs.com/package/is-kit

is-kit

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

📚 Documentation Site

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter, and other TypeScript control flow
compose validation logic…

View on GitHub

is-kit is a lightweight library for building small type guards like isString and isNumber, then composing them with helpers like and, or, and struct, while still allowing TypeScript narrowing to work naturally.

Suppose an external API returns a User like this

type User = {
  id: string;
  name: string;
};

With a normal struct, we can create a guard for that object shape.

const isUser = struct({
  id: isString,
  name: isString,
});

This is useful.

struct can infer the return type from the schema, so isUser can validate a value that looks like a User.

But there is one problem.

It is easy for the schema and the existing type to drift apart.

For example, suppose the User type already exists, but we accidentally write the wrong key in the schema.

type User = {
  id: string;
  name: string;
};

const isUser = struct({
  id: isString,
  displayName: isString,
});

This struct call itself is valid.

From the perspective of struct, this is a perfectly valid schema for:

{
  id: string;
  displayName: string;
}

So struct is useful for creating a type from a schema.

But it does not synchronize that schema with an existing User type.

A common dangerous workaround is to use as.

const isUser = struct({
  id: isString,
  displayName: isString,
}) as Predicate<User>;

This is extremely dangerous. ⚠️⚠️⚠️

The schema says displayName, but we are telling TypeScript

Trust me. This is a guard for User. Please 🙏

That as is not a check.

It is just a self-declaration.

Now, satisfies can improve this.

If the library exposes a schema shape type, we could write something like:

const userSchema = {
  id: isString,
  name: isString,
} satisfies TypedStructShape<User>;

Now TypeScript checks whether the schema corresponds to User.

If we write an unknown key or forget a required key, TypeScript can report an error.

const userSchema = {
  id: isString,
  displayName: isString,
  // name is missing, and displayName does not exist on User
} satisfies TypedStructShape<User>;

This is better.

But writing this every time is a bit annoying.

Also, if the user forgets to write satisfies TypedStructShape<User>, the schema and the type can drift apart again.

So we can use generics to encapsulate this check inside the API.

const isUser = typedStruct<User>()({
  id: isString,
  name: isString,
});

With this shape, users do not need to write satisfies TypedStructShape<User> every time.

Instead, the typedStruct<User>() API itself checks 👇

Does this schema correspond to User?

So, using the framing from earlier:

we are not using as to ask TypeScript to trust us
we are not asking users to write satisfies every time
we are using generics to encapsulate the check inside an API

That is the core idea.

Let's look a little more concretely.

The implementation idea for typedStruct looks like this:

type OptionalKeys<T> = {
  // WHY: Optional keys accept an empty object when picked in isolation.
  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
}[keyof T];

type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;

type TypedStructShape<T extends object> = {
  readonly [K in Extract<RequiredKeys<T>, string>]-?: Predicate<T[K]>;
} & {
  readonly [K in Extract<OptionalKeys<T>, string>]-?: OptionalSchemaField<
    Predicate<T[K]>
  >;
};

type NoExtraKeys<S, Shape> = S & {
  readonly [K in Exclude<keyof S, keyof Shape>]: never;
};

type TypedStructFields<
  T extends object,
  S extends TypedStructShape<T>,
> = NoExtraKeys<S, TypedStructShape<T>>;

export function typedStruct<T extends object>() {
  return <const S extends TypedStructShape<T>>(
    fields: TypedStructFields<T, S>,
    options?: { exact?: boolean },
  ): Predicate<InferSchema<TypedStructFields<T, S>>> =>
    // WHY: `typedStruct` keeps `struct` runtime behavior while using the target
    // type only to check that hand-written guard fields stay in sync.
    struct(fields, options);
}

We can ignore the small details for now.

The important part is this:

typedStruct<T extends object>()

First, typedStruct receives the target type T.

Then this part:

<const S extends TypedStructShape<T>>

means the actual schema S passed by the user must correspond to T.

But here is an important detail

S extends TypedStructShape<T> alone cannot completely prevent extra keys.

TypeScript uses structural typing.

If a type has the required properties, it may still satisfy a constraint even if it also has additional properties.

For example, if User is { id: string; name: string }, then a schema like { id, name, displayName } has all required keys and one extra key.

The constraint S extends TypedStructShape<User> alone may still allow that.

So we use NoExtraKeys to make keys that do not exist in TypedStructShape<T> become never.

Now let's look at how TypedStructShape<T> works.

It separates required keys and optional keys from T.

type OptionalKeys<T> = {
  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
}[keyof T];

type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;

OptionalKeys<T> is used to pick optional properties like name?: string.

Then TypedStructShape<T> treats the keys differently:

required keys become Predicate<T[K]>
optional keys become OptionalSchemaField<Predicate<T[K]>>

That means if a key is optional in the target type, the schema must also mark it as optional using something like optionalKey(...).

type TypedStructShape<T extends object> = {
  readonly [K in Extract<RequiredKeys<T>, string>]-?: Predicate<T[K]>;
} & {
  readonly [K in Extract<OptionalKeys<T>, string>]-?: OptionalSchemaField<
    Predicate<T[K]>
  >;
};

Here, OptionalSchemaField is the internal type used to represent a schema field created by a helper like optionalKey(...).

Next, TypedStructFields<T, S> prevents schema fields from having keys that do not exist in T.

Roughly speaking, NoExtraKeys takes keys that exist in S but not in Shape, and turns them into never.

For example, if User does not have displayName, but the schema includes displayName, that field becomes never.

Since a normal guard cannot be assigned to never, TypeScript rejects the extra key.

type NoExtraKeys<S, Shape> = S & {
  readonly [K in Exclude<keyof S, keyof Shape>]: never;
};

type TypedStructFields<
  T extends object,
  S extends TypedStructShape<T>,
> = NoExtraKeys<S, TypedStructShape<T>>;

So typedStruct is not just a helper that adds a type to struct.

It is an API for making an existing object type and a handwritten runtime guard harder to drift apart.

One important point 👇

typedStruct does not automatically generate a runtime validator.

TypeScript types do not exist at runtime.

Also, we cannot automatically generate isString or isNumber from the User type.

So the guard itself still has to be written by hand.

const isUser = typedStruct<User>()({
  id: isString,
  name: isString,
});

But the API can check whether the handwritten schema is still in sync with User.

It's the tasty part of typedStruct.

This is especially useful when you already have API response types generated from something like OpenAPI.

Here, imagine ApiResponse is a generated response type.

type ArticleResponse = ApiResponse<"/articles/{id}", "get">;

const isArticleResponse = typedStruct<ArticleResponse>()({
  id: isNumber,
  title: isString,
  summary: optionalKey(isString),
});

Here, optionalKey(isString) means the object key itself may be missing.

But if the key exists, the value must pass isString.

So as a runtime check, this does not allow { summary: undefined }.

It means:

if summary exists, it must be a string
if summary does not exist, that is OK

This is a small but important distinction.

The idea is not ❌

The TypeScript property is optional, so I can omit the schema field.

Instead, the idea is ✅

The runtime guard should explicitly say that this key is optional.

That way, when the target type changes, the mismatch becomes easier to notice.

Also, the compile-time key check in typedStruct and the runtime check in struct(..., { exact: true }) are different things.

const isUser = typedStruct<User>()(
  {
    id: isString,
    name: isString,
  },
  { exact: true },
);

NoExtraKeys is a compile-time check that prevents the schema author from writing extra keys in the schema.

On the other hand, { exact: true } is a runtime check that rejects actual runtime objects if they contain keys outside the schema.

They may look similar, but they check different things.

NoExtraKeys checks mistakes in the handwritten schema
{ exact: true } checks extra keys in runtime data

This is exactly the theme of the article.

Instead of silencing TypeScript with as, we take a satisfies-like check and encapsulate it inside an API with generics.

One more important design point 👇

The return type is not directly forced to T.

Instead, it is inferred from the actual fields passed to the function.

Predicate<InferSchema<TypedStructFields<T, S>>>;

So T is used to check whether the schema is in sync with the existing type.

But the actual guard type is inferred from the schema, just like struct.

In other words, we are not doing this

as Predicate<User>

Instead, the existing type synchronization is handled by the generic constraint, while the actual guard type is derived from the schema.

🎯 Summary

In this article, we looked at the difference between as, satisfies, and generics through the lens of where type responsibility lives.

Syntax	Role	Where the responsibility lives
`as Type`	Asks TypeScript to trust you 🙏	The person writing the code
`satisfies Type`	Checks whether a value matches a type 🔍	The value declaration
`<T extends Type>`	Constrains what an API accepts 🎁	The API designer

as is not evil.

Sometimes TypeScript cannot know something, and a human has to take responsibility for that missing information.

But as is not a check.

When you use as for external data or handwritten schemas, the code can look type-safe while skipping the actual validation.

AI-generated code often papers over uncertainty with as, so this is something worth watching for.

When you really want to check whether a value has the right shape, first consider whether satisfies can help.

And when you find yourself repeating the same satisfies pattern again and again, consider moving that constraint into an API with generics.

Personally, I find this framing useful:

as means: "Trust me."
satisfies means: "Please check if this is correct."
generics mean: "Only pass values that fit this API."

typedStruct in is-kit is a good example of this difference.

When you want to keep an existing object type and a runtime guard in sync, do not silence TypeScript with as.

Instead, you can take a satisfies-like check and encapsulate it inside an API using generics.

This makes the safer way the natural way to use the API, and moves type responsibility closer to the API design.

Happy TypeScript life. 🫰

Bonus

The user-defined type guard library used in this article is is-kit.

nyaomaru / is-kit

Lightweight, zero-dependency toolkit for building `isFoo` style type guards in TypeScript. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨. npm -> https://www.npmjs.com/package/is-kit

is-kit

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

📚 Documentation Site

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter, and other TypeScript control flow
compose validation logic…

View on GitHub

typedStruct was added in v1.8, so please give it a try. 😻

CHANGELOG.md is for Both Humans and AI Now, So Let’s Automate It

nyaomaru — Wed, 03 Jun 2026 12:33:59 +0000

Hoi hoi!

I’m @nyaomaru, a frontend engineer who recently discovered the deliciousness of a cheese whose name sounds a bit like Al Capone. 🧀

Are you building personal projects?

Or contributing to OSS?

Or maybe you are busy playing Resident Evil 9 🧟 and CloverPit 🍀?

Whatever the case, I respect your admirable dedication as an engineer.

Now, when managing OSS on GitHub, one file that becomes very important is CHANGELOG.md.

Why is it important?

For example, when a library I use gets updated, the first thing I usually check is CHANGELOG.md.

Recently, I have been experimenting with an AI triage workflow. For Dependabot updates, I feed release notes and CHANGELOG.md into AI, then ask Claude Code to evaluate the risk and help with triage.

This has been very useful. I do not have to check everything manually, and that makes me happy 😺

In other words, CHANGELOG.md is becoming a document that is not only read by humans, but also read by AI as input for dependency update decisions.

So, CHANGELOG.md will continue to be very useful in the coming era.

But surprisingly, many projects do not maintain it well.

For example, even some very useful React development tools sometimes ship silent releases without any release notes at all.

When that happens, users have to dig through commit history and figure out things like:

What new features were added?
What changed?
Is it safe to upgrade?

Of course, busy engineers do not have time for that. I am not that busy, but if I had that time, I would rather play CloverPit 🍀.

So, to protect my precious game time, I built an OSS tool that automatically generates CHANGELOG.md.

nyaomaru / changelog-bot

Automatic create changelog with AI. 🤖 It provides CLI and github actions. 🚀 https://www.npmjs.com/package/@nyaomaru/changelog-bot

Releases should feel exciting, not tedious.

@nyaomaru/changelog-bot 🤖 turns your Git history and release notes into a polished changelog entry (and optional PR) in a single run. Drop it into CI, run it locally, or hand it to your release captain—either way, you ship with a crisp changelog and zero copy-paste fatigue.

Why changelog-bot?

Automated storytelling: Combines commit history, PR titles, and release notes to produce human-ready changelog sections.
LLM superpowers (optional): Connect OpenAI or Anthropic for tone-aware summaries or skip API keys entirely and rely on a robust heuristic fallback.
PR-ready output: Can open a pull request with updated changelog, compare links, and release notes already wired up.
Safe defaults: Detects duplicate versions, keeps compare links current, and won’t fail a release if AI is down.
CI-native: Works as a GitHub Action, reusable workflow, or plain CLI—no fragile scripting required.

Important

This project is currently in its early stages…

View on GitHub

In this article, I will walk through the changes from v0.1 and what I am planning next.

Let’s take a look!

🤖 What is changelog-bot?

changelog-bot is a CLI and GitHub Action that automatically creates a Pull Request to update CHANGELOG.md based on Git history, Pull Requests, and GitHub Release Notes.

What it does is simple:

Collect commits and PRs from the previous release to the current release
Categorize changes into sections such as Added, Changed, Fixed, Docs, and Chore
Add a new release section to CHANGELOG.md
Create a Pull Request with that change

If you configure an AI provider, it can use OpenAI, Anthropic, or Gemini to generate a more readable changelog section.

On the other hand, it also works with a fallback mode when no API key is provided.

So it is totally fine even if you do not use AI.

In other words, this is not:

A tool that can do nothing without AI.

It is more like:

An automation tool that works better with AI.

That is the key idea.

🐾 What was available up to v0.1

Up to v0.1, I focused on building the foundation of changelog-bot.

It already supported:

CLI and GitHub Action usage
Changelog generation from Git history
Importing GitHub Release Notes
OpenAI and Anthropic providers
Heuristic fallback
Dry-run mode

At this point, the basic experience was already there:

Automatically update CHANGELOG.md during a release workflow.

I also introduced it in this earlier article:

nyaomaru

Nov 30 '25

Generate CHANGELOG.md Automatically 🤖

#ai #typescript #ci #opensource

3 min read

But there were still some problems.

In particular, even though users could choose an AI provider, there was still no strong way to adjust the language or writing style of the generated CHANGELOG.md for each project.

For example, there was no good way to pass project-specific rules such as:

“Write it in Japanese.”
“Group internal changes under Chore.”
“Group dependency updates together.”

So the customization experience was still weak.

🚀 v0.2: Gemini provider support

In v0.2, I added Gemini as a new LLM provider.

Now changelog-bot supports these three providers:

OpenAI
Anthropic
Gemini

You can specify Gemini from the CLI like this:

changelog-bot \
  --provider gemini \
  --release-tag HEAD \
  --release-name 0.2.0 \
  --dry-run

You can also use it from GitHub Actions:

with:
  provider: gemini
env:
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

I also added dry-run diagnostics.

Provider: gemini
Model: gemini-3.5-flash
AI used: true
Fallback reasons: none

This makes it easier to check whether the AI provider was actually used, or whether changelog-bot fell back to the heuristic mode.

It is a small feature, but I think this kind of observability is very important for CI tools.

When something runs in CI, you want to quickly understand what actually happened.

🚀 v0.3: Changelog customization

In v0.3, I added customization support for changelog generation.

The newly added options are:

Option	Description
`--language`	Specifies the language of the generated `CHANGELOG.md`
`--instructions`	Passes inline instructions to the AI
`--instructions-file`	Passes instructions to the AI from a file

For example, if you want to generate a changelog in Dutch, you can write:

changelog-bot \
  --provider gemini \
  --release-tag HEAD \
  --release-name 0.3.0 \
  --language nl \
  --instructions "Schrijf kort en duidelijk in het Nederlands. Groepeer interne wijzigingen onder Chore." \
  --dry-run

You can also define project-specific rules in a file.

changelog-bot \
  --provider openai \
  --release-tag HEAD \
  --release-name 0.3.0 \
  --language nl \
  --instructions-file .github/changelog-instructions.md \
  --dry-run

For example, .github/changelog-instructions.md can contain rules like this:

Write concise release notes in Dutch.

Rules:

- Focus on user-facing changes.
- Group internal refactors under Chore.
- Group dependency updates together.
- Avoid mentioning commit hashes.

With this, changelog-bot is no longer just “a tool that generates changelogs with AI.”

It is moving toward:

A tool that can generate a CHANGELOG.md that feels right for each project.

Also, when customization is enabled, changelog-bot does not simply use GitHub Release Notes as-is, even if they exist.

Instead, it passes them to the model and lets the model rewrite them.

This means GitHub Release Notes can still be used as source material, while the final output reflects the specified language and instructions.

🥌 Roadmap toward v1

With customization added in v0.3, the shape of v1 is becoming much clearer.

Here are the main things I want to add before v1.

1. Config file support

Passing CLI options every time is annoying, so I want to support config files.

{
  "provider": "gemini",
  "language": "nl",
  "instructionsFile": ".github/changelog-instructions.md"
}

The goal is to make the same configuration usable from the CLI, GitHub Actions, and reusable workflows.

2. Choosing behavior when an AI provider fails

Right now, changelog-bot falls back when an AI provider fails.

This is convenient, but some projects may want the workflow to fail if AI generation fails.

So I am considering options like:

--fail-on-llm-error
--require-provider
--no-ai

Since changelog-bot is intended to be used in CI, users should be able to choose between:

“Fail when AI generation fails”
“Fallback and continue”

Both behaviors are valid depending on the project.

3. JSON report output

Dry-run diagnostics already exist, but I also want to add a JSON report.

changelog-bot --dry-run --report-json

For example, it would be useful to output machine-readable information such as:

provider
model
aiUsed
fallbackReasons
generated sections
PR title
labels

This should make it easier to integrate changelog-bot with other CI tools and bots.

4. Better changelog quality

I also want to keep improving the quality of the generated changelog.

Some areas I want to improve are:

Grouping dependency updates
Detecting breaking changes
Label-based include / exclude rules
Custom section names
Better duplicate detection

Especially in OSS, what should be included in a changelog differs from project to project.

I want changelog-bot to handle those differences better.

🎯 Summary

CHANGELOG.md is a very plain file, but for users, it is an important document.

Recently, it is also becoming more common to let AI read it and use it as input for dependency update decisions.

That is why CHANGELOG.md should not just be generated somehow.

It should be generated in a readable way that fits each project’s context.

But writing it carefully by hand every time is honestly a pain.

changelog-bot is a tool for automating that process with Git history, Pull Requests, GitHub Release Notes, and AI.

In v0.2, I added Gemini support.

In v0.3, I added customization through language, instructions, and instructions file.

With these changes, changelog-bot is moving from:

Just generating a changelog automatically

to:

Generating a changelog that fits each project

v1 is getting closer.

If you are interested, please give the repository a ⭐ and watch over it warmly!

nyaomaru / changelog-bot

Automatic create changelog with AI. 🤖 It provides CLI and github actions. 🚀 https://www.npmjs.com/package/@nyaomaru/changelog-bot

Releases should feel exciting, not tedious.

Why changelog-bot?

Automated storytelling: Combines commit history, PR titles, and release notes to produce human-ready changelog sections.
LLM superpowers (optional): Connect OpenAI or Anthropic for tone-aware summaries or skip API keys entirely and rely on a robust heuristic fallback.
PR-ready output: Can open a pull request with updated changelog, compare links, and release notes already wired up.
Safe defaults: Detects duplicate versions, keeps compare links current, and won’t fail a release if AI is down.
CI-native: Works as a GitHub Action, reusable workflow, or plain CLI—no fragile scripting required.

Important

This project is currently in its early stages…

View on GitHub

Now let’s auto-generate our CHANGELOG.md files and use the saved time to play some games! 🧟🍀

Which OpenAPI Codegen Should You Choose? openapi-typescript vs hey-api vs Orval vs Kubb

nyaomaru — Wed, 20 May 2026 13:34:57 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who thought OpenAPI codegen would make API clients easier, but somehow ended up lost in a forest of generated files. 🌳🌳🌳

Writing API clients by hand is painful.

Usually, we want things like:

generated TypeScript types
generated request functions
maybe TanStack Query hooks
maybe MSW mocks
maybe even Zod schemas
and, if possible, everything growing automatically from OpenAPI

That is where OpenAPI codegen tools are useful.

But after comparing several tools with a fairly large real-world schema, I realized something important:

OpenAPI codegen is not only about what a tool can generate.

The generated output itself also matters:

how many files it creates
how fast generation is
how friendly it is to linting
how easy it is for the IDE to index
how errors are modeled
how authentication is handled
how much generated code your team is willing to maintain

In this article, I compared the following four tools:

Tool	Version tested	Main setup
`openapi-typescript`	v7.13.0	types only
`@hey-api/openapi-ts`	v0.96.1	types + SDK + fetch client
`Orval`	v8.8.1	`mode: "tags-split"` / `client: "fetch"`
`Kubb`	v4.37.2	client / types / schemas generated by plugins

The OpenAPI schema used for this comparison was roughly this size. (It was generated by drf-spectacular)

Item	Value
`openapi.yaml` lines	about 75,000
`openapi.yaml` size	about 2 MB
operations	about 1,200

Note: Some endpoint names, schema names, type names, and directory names in this article are simplified or replaced for publication. Also, these libraries move fast, so the generated output and issues described here are based on the versions tested at the time of writing.

For a small API, honestly, any of these tools may work fine.

But at this scale, differences become very visible in generation speed, file count, lint behavior, enum handling, error models, and day-to-day maintainability.

Let's walk through the comparison.

🎯 TL;DR

My conclusion is this:

Situation	Tool I would choose
You only need TypeScript types	`openapi-typescript`
You want operationId-based SDK functions and interceptors	`@hey-api/openapi-ts`
You want `TanStack Query`, `Zod`, `MSW`, or `Faker` generated from OpenAPI	`Orval`
You value 1 operation = 1 file and plugin-based codegen architecture	`Kubb`

For my use case, hey-api felt the most practical.

The reasons were simple:

it generates functions from operationId
arguments are consistently shaped like { query, path, body }
it has a result-style error model
it supports axios-like interceptors
the generated output is much lighter than Orval or Kubb
it still leaves room for TanStack Query and Zod plugins later

That said, if your project already uses openapi-typescript + openapi-fetch and you are happy with it, I do not think you need to migrate immediately.

The difference is not huge enough to justify migration by itself.

I would consider switching only when you start feeling pain around SDK functions, interceptors, result handling, mocks, generated hooks, or schema-driven tooling.

In this article, I will call @hey-api/openapi-ts simply hey-api.

🌓 Two families of OpenAPI codegen tools

Before comparing each tool one by one, I think it is easier to divide them into two families.

Axis	Family A: thin output, client-focused	Family B: SDK-first, ecosystem generation
Representative tools	`openapi-typescript` / `hey-api`	`Orval` / `Kubb`
Main purpose	accurate types and lightweight runtime	generated SDK + hooks + mocks + validation
Error model	result-style `{ data, error, response }`	wrapper / throw / client-dependent
Output size	small: types only or compact SDK	large: tag-level or operation-level files
Ecosystem features	`TanStack Query` / `Zod` depending on tool	`TanStack Query` / `Zod` / `MSW` / `Faker` / `SWR` etc.
Configuration style	minimal	codegen platform

This distinction is important.

openapi-typescript and Kubb are both OpenAPI codegen tools, but they are not trying to solve the same problem.

openapi-typescript mainly focuses on generating accurate TypeScript types.

Kubb, on the other hand, is closer to a codegen platform that can generate clients, types, schemas, mocks, and other assets in a structured way.

Comparing them directly is a bit like comparing a kitchen knife with a full kitchen. 🧑‍🍳🔪

Both are related to cooking, but they are not the same kind of thing.

🏎️ Generation speed

First, generation speed.

I measured each command three times on WSL2 / Node v24.14 using npx <cmd>. So the numbers include npx startup overhead. (a custom-built PC)

Tool	1st run	2nd run	3rd run	Average	Max RSS
`openapi-typescript`	1.66 s	1.50 s	1.40 s	about 1.5 s	about 335 MB
`@hey-api/openapi-ts`	8.74 s	8.84 s	6.43 s	about 8.0 s	about 495 MB
`Orval`	6.01 s	6.12 s	4.48 s	about 5.5 s	about 415 MB
`Kubb`	17.29 s	19.82 s	17.13 s	about 18.1 s	about 880 MB

Relative to openapi-typescript, the difference looked like this:

Tool	Relative speed
`Orval`	about 3.7x slower
`hey-api`	about 5.3x slower
`Kubb`	about 12x slower

Why openapi-typescript is so fast

In this setup, openapi-typescript only generates types into a single file.

The workflow is basically:

read the schema
convert it into TypeScript types
write one file

That means very little file I/O.

The generated output was just types.gen.ts.

At about 1.5 seconds, it is fast enough that running it in CI, pre-commit, or during local development barely feels like a problem.

Why Kubb is slower

Kubb has a different philosophy.

It splits things much more aggressively.

In this test, I generated operation-level clients, operation-level types, and schemas.

So the cost is not only computation.

The number of files written to disk becomes a major factor.

The structure is clean from a bundling and organization perspective, but with around 1,200 operations, the file system cost becomes noticeable.

For this kind of schema, I would not treat Kubb as something I casually run on every small change unless the generation target is narrowed.

It feels more suitable for a workflow where generated files are committed, generated in CI, or carefully scoped.

Orval was faster than I expected

I expected Orval to be slower.

It can generate things like TanStack Query, Zod, and MSW, so I assumed it would be heavier.

But with tags-split, the main functions are grouped by tag.

In my schema, there were about 25 tags.

So Orval was not generating one giant file, but it also was not generating one file per operation.

That middle ground worked well for speed.

However, this does not mean the output was small.

It still generated more than 2,600 schema files.

🗺️ Output size

Next, generated output size and file count.

Tool	Output	File count	Total size
`openapi-typescript`	`src/api/types.gen.ts`	1	2.4 MB
`@hey-api/openapi-ts`	`src/api/hey-api/`	16	2.9 MB
`Orval`	`src/api/orval/`	2,719	14 MB
`Kubb`	`src/api/kubb/`	3,877	24 MB

Just from these numbers, the tools clearly live in different worlds.

My rough feeling was:

openapi-typescript: one house 🏠
hey-api: a small town 🏙️
Orval: a small forest 🌲🌲
Kubb: a deep forest 🌳🌳🌳

BTW, I love rural life so forest is better. 🌳

openapi-typescript

The output was only types.gen.ts.

It contained:

paths
components
operations

One file is simple and easy to understand.

But a 2.4 MB TypeScript file can still be uncomfortable for IDE indexing.

So even though the file count is tiny, the single file itself is large.

hey-api

hey-api generated 16 files.

The main files looked like this:

File	Purpose
`types.gen.ts`	request / response types
`sdk.gen.ts`	generated operation functions
`index.ts`	barrel exports
`client.gen.ts`	default client instance
`client/`	fetch client implementation
`core/`	auth, serializers, utils, etc.

types.gen.ts was about 1.7 MB, and sdk.gen.ts was about 750 KB.

With 1,200 operations, the SDK file naturally becomes large.

But compared with Orval and Kubb, the output still felt manageable.

Orval

I used Orval with tags-split.

The structure looked roughly like this:

src/api/orval/
├─ schemas/
│  ├─ ordersWriteRequest.ts
│  ├─ ordersListParams.ts
│  └─ ...
├─ order/
│  └─ order.ts
├─ product/
│  └─ product.ts
└─ ...

Functions were grouped by tag.

In this schema:

tag files: about 25
schema files: more than 2,600

The largest generated file was around 30,000 lines.

Kubb

Kubb generated an even more split structure.

src/api/kubb/
├─ types/
├─ clients/
├─ schemas/
└─ index.ts

Directory	Purpose
`types/`	operation-level types
`clients/`	operation-level functions
`schemas/`	individual schemas
`index.ts`	barrel exports

The nice part is that the structure is close to 1 operation = 1 file.

That makes grep easy and can be friendly to tree-shaking.

But the tradeoff is real:

large PR diffs
heavier IDE indexing
slower clone and checkout
more generated files to commit or ignore

🧪 Calling the same endpoint

Now let's compare the actual call sites.

Assume this endpoint:

GET /orders

It accepts common list query parameters like page and page_size.

openapi-typescript

openapi-typescript only generates types, so I used it with openapi-fetch.

import createClient from "openapi-fetch";
import type { paths } from "./api/types.gen";

const client = createClient<paths>({
  baseUrl: "http://localhost:8000",
});

const { data, response } = await client.GET("/orders", {
  params: {
    query: {
      page: 1,
      page_size: 20,
    },
  },
});

The important part is that the endpoint is specified as a path string:

client.GET("/orders");

This is simple and readable.

IDE autocomplete also works well.

But it is not operationId-based, so if the endpoint changes, rename refactoring is not as direct as function-based clients.

hey-api

hey-api generates SDK functions.

import { ordersList } from "./api/hey-api/sdk.gen";

const { data, response } = await ordersList({
  query: {
    page: 1,
    page_size: 20,
  },
});

The function name comes from operationId.

I like this because you can grep by function name and use IDE rename refactoring more naturally.

The argument shape is also consistent:

{
  query,
  path,
  body,
}

This consistency becomes useful later when building wrappers, logging, retries, auth handling, or tracing.

Orval

For Orval, I used fetch, tags-split, and useNamedParameters: true.

import { ordersList } from "./api/orval/orders/order";

const { data, status, headers } = await ordersList({
  page: 1,
  page_size: 20,
});

The return value is like:

{
  data,
  status,
  headers,
}

At first glance, this is easy to use.

But with the default fetch client, 4xx and 5xx responses are not thrown as errors.

That point is very important in real applications.

Kubb

Kubb generates operation-level functions.

import { ordersList } from "./api/kubb/clients/ordersList";

const data = await ordersList({
  page: 1,
  page_size: 20,
});

On success, it returns the response data directly.

So the call site is very short.

However, if you want to access response headers or status, the default return shape may not be enough.

Also, path parameters and body arguments can become positional depending on the endpoint, which can make generic wrappers harder to design.

🖇️ Path params and body arguments

A list endpoint does not show all differences, so let's compare path params and body arguments too.

GET by id

// openapi-typescript
const { data } = await client.GET("/orders/{id}", {
  params: {
    path: {
      id: "123",
    },
  },
});

// hey-api
const { data } = await ordersRetrieve({
  path: {
    id: "123",
  },
});

// Orval
const { data } = await ordersRetrieve({
  id: "123",
});

// Kubb
const data = await ordersRetrieve("123");

Summary:

Tool	Path param style
`openapi-typescript`	`params.path`
`hey-api`	`{ path: { id } }`
`Orval`	`{ id }`
`Kubb`	positional argument like `"123"`

Kubb is short.

But if an endpoint has multiple path params, positional arguments grow like (id1, id2, ...).

This is partly a preference issue, but for large API clients I usually prefer named object arguments.

POST body

// openapi-typescript
await client.POST("/orders", {
  body,
});

// hey-api
await ordersCreate({
  body,
});

// Orval
await ordersCreate(body);

// Kubb
await ordersCreate(body);

Orval and Kubb feel natural when the body is the first argument.

But for POST endpoints without a body, this can sometimes lead to explicit undefined arguments.

hey-api and openapi-typescript add one level with { body }, but the shape remains consistent with query and path.

For a large application, I personally prefer the consistency of hey-api.

💭 Function signature philosophy

Here is the broader comparison of call signatures.

Axis	`openapi-typescript`	`hey-api`	`Orval`	`Kubb`
endpoint selection	URL string	operationId function	operationId function	operationId function
query	`params.query`	`{ query }`	first argument	first argument
path	`params.path`	`{ path }`	`{ id }` or positional	positional
body	`{ body }`	`{ body }`	first argument	first argument
headers	options / middleware	options / interceptor	`RequestInit`	config
cross-cutting behavior	middleware	interceptor	mutator	config / custom client

The key strength of hey-api is that every endpoint moves toward the same shape:

await api({
  query,
  path,
  body,
  headers,
});

That makes cross-cutting behavior easier:

authentication
logging
retries
trace ids
request ids
custom headers

Orval and Kubb often produce shorter call sites, but signatures can vary more by endpoint.

In a small codebase, that is probably fine.

In a 1,200-operation API, consistency matters a lot more.

⚠️ Error model

This was one of the most important differences.

Tool	Default behavior	Can be changed?
`openapi-typescript` + `openapi-fetch`	`{ data, error, response }` result union	can throw via middleware
`hey-api`	`{ data, error, response }` result union	can throw with `throwOnError: true`
`Orval`	wrapper like `{ data, status, headers }`	can throw with custom fetch / mutator / config
`Kubb`	success returns `data`, failure throws	customizable via client

Result union in openapi-typescript and hey-api

With openapi-fetch and hey-api, non-2xx responses can be represented in error if the OpenAPI schema defines them.

But in my drf-spectacular schema, most non-2xx responses were not described.

So in practice, error was often close to never.

That means I still need a runtime check like this:

const { data, response } = await client.GET("/orders", {
  params: {
    query: {
      page: 1,
    },
  },
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

return data;

With hey-api, I can also opt into throwing behavior per call:

const { data } = await ordersList({
  query: {
    page: 1,
  },
  throwOnError: true,
});

I like having both options.

Sometimes I want a result-style response.

Sometimes I want HTTP errors to throw immediately.

Orval's default fetch behavior needs attention

With Orval's default fetch client, 4xx and 5xx responses do not throw automatically.

const res = await ordersList({
  page: 1,
});

if (res.status !== 200) {
  throw new Error(`HTTP ${res.status}`);
}

return res.data;

If the team forgets to check status, it is possible to treat an error response as if it were success data.

For example, the code may try to access data.results and then fail at runtime because the actual response body was an error shape.

This is easy to miss if you only look at TypeScript types.

If I used Orval in production, I would choose one of these patterns:

always check status at the call site
configure the fetch client with override.fetch.forceSuccessResponse: true
use override.mutator and write a custom fetch wrapper for auth, refresh, and errors

A custom fetch may look like this:

// custom-fetch.ts
export const customFetch = async <T>(
  url: string,
  options: RequestInit,
): Promise<T> => {
  const res = await fetch(url, options);

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  return res.json();
};

Orval is powerful, but this behavior should be made explicit as a team rule.

Kubb's throw model

Kubb is closer to a throw-based model by default.

const data = await ordersList({
  page: 1,
});

On success, you get the data directly.

On failure, it throws.

This is pleasant in UI code.

But if you need response metadata, such as:

Retry-After
ETag
rate limit headers
pagination headers

then the default return value may not be enough, and you may need a custom client or wrapper.

✅ Authentication and interceptors

Authentication handling also differs quite a bit.

openapi-fetch

openapi-fetch supports middleware.

client.use({
  onRequest: ({ request }) => {
    request.headers.set("Authorization", `Bearer ${getToken()}`);
    return request;
  },
});

If you already use openapi-typescript + openapi-fetch, this is clean and lightweight.

hey-api

hey-api has axios-like interceptors.

client.interceptors.request.use((request) => {
  request.headers.set("Authorization", `Bearer ${getToken()}`);
  return request;
});

This API feels familiar.

For common headers, logging, trace ids, and 401 refresh flows, this style is easy to work with.

Generated hey-api functions can also include security metadata.

export const ordersList = <ThrowOnError extends boolean = false>(
  options?: Options<ordersListData, ThrowOnError>,
) =>
  (options?.client ?? client).get<ordersListResponses, unknown, ThrowOnError>({
    security: [{ scheme: "bearer", type: "http" }],
    url: "/orders",
    ...options,
  });

This is a little more to understand at first, but useful for authenticated APIs.

Orval

Orval is closer to raw fetch.

await ordersList(
  { page: 1 },
  {
    headers: {
      Authorization: `Bearer ${getToken()}`,
    },
  },
);

You can pass headers per call.

But in a real app, I would usually create a custom fetch with override.mutator.

Kubb

Kubb can configure the client or accept per-call config.

client.setConfig({
  baseURL: "http://localhost:8000",
});

Headers can also be passed per call.

await ordersList(
  { page: 1 },
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);

But it does not feel like axios-style interceptors are the default mental model.

For things like 401 refresh, I would expect to wire my own client behavior.

🪛 TanStack Query, Zod, MSW, and Faker

This is where the second family of tools becomes attractive.

Feature	`openapi-typescript`	`hey-api`	`Orval`	`Kubb`
Type generation	Good	Good	Good	Good
Fetch client	external `openapi-fetch`	Good	Good	Good
TanStack Query	No	plugin	Good	plugin
Zod	No	plugin	Good	plugin
MSW	No	limited / roadmap-dependent	Good	Good
Faker	No	No	Good	Good
SWR / Vue Query	No	limited	Good	limited / plugin-dependent

Orval has strong built-in support around this area.

It can target tools like:

TanStack Query
SWR
Vue Query
Zod
MSW
Faker

Kubb also has a strong plugin-based approach.

hey-api is more focused around SDK generation, TanStack Query, and Zod.

If your goal is mainly API clients and types, openapi-typescript or hey-api may be enough.

If your goal is to generate a broader frontend ecosystem from OpenAPI, Orval or Kubb becomes more interesting.

In my case, I did not need MSW or Faker yet.

So Orval and Kubb felt a bit too much for the current problem.

🤯 Enum issue: drf-spectacular BlankEnum

One very real-world issue was enum generation.

drf-spectacular can represent nullable or blank enum values like this:

BlankEnum:
  enum: [""]

NullEnum:
  enum: [null]

Then a field may use anyOf like this:

status:
  anyOf:
    - $ref: "#/components/schemas/StatusEnum"
    - $ref: "#/components/schemas/BlankEnum"
    - $ref: "#/components/schemas/NullEnum"
  nullable: true

The intended TypeScript value is something like:

"WAITING" | "RUNNING" | "SUCCESS" | "FAILURE" | "" | null;

Generated BlankEnum

The generated output differed by tool.

// openapi-typescript
BlankEnum: "";

// hey-api
export enum BlankEnum {
  "" = "",
}

// Orval
export type BlankEnum = (typeof BlankEnum)[keyof typeof BlankEnum];

export const BlankEnum = {
  "": "",
} as const;

// Kubb
export const blankEnumEnum = {} as const;
export type BlankEnumEnumKey =
  (typeof blankEnumEnum)[keyof typeof blankEnumEnum];

export type BlankEnum = BlankEnumEnumKey;

In Kubb, the empty string disappeared, and the type effectively became never.

What happens after anyOf composition

As a result, only Kubb dropped "" from the final type.

Tool	Can represent `""` in the type?
`openapi-typescript`	Yes
`hey-api`	Yes
`Orval`	Yes
`Kubb`	No

This is not just a small type detail.

It can break real application code if fields like status, file_type, or update_type actually receive an empty string from the backend.

Possible workarounds are:

patch BlankEnum after generation
cast affected fields to string | null
wait for an upstream fix
avoid this schema shape if you control the backend

If you use drf-spectacular and have many BlankEnum / NullEnum patterns, I recommend checking this before adopting Kubb.

🥗 Body type reusability

POST body types also differed.

Tool	Body type style
`openapi-typescript`	`components["schemas"]["ordersWriteRequest"]`
`hey-api`	`ordersWriteRequest`
`Orval`	`ordersWriteRequest`
`Kubb`	`ordersCreateMutationRequest`

Kubb generated endpoint-scoped wrapper types.

This can be good because each operation is very explicit.

But if you want to reuse the same schema in app-level code, it can be a little less convenient.

For example, if a form wants to use ordersWriteRequest as its submit data type, openapi-typescript, hey-api, and Orval feel more natural.

With Kubb, I may need to alias the operation-scoped type:

import type { ordersCreateMutationRequest } from "./api/kubb/types/ordersCreate";

type OrderWriteRequest = ordersCreateMutationRequest;

This is not wrong.

It just depends on whether your app wants shared schema types or operation-scoped types.

🚪 Lint behavior

All four tools passed tsc --noEmit.

But linting showed differences.

Tool	oxlint + `no-explicit-any`	eslint recommended
`openapi-typescript`	0	36
`hey-api`	0	57
`Orval`	0	36
`Kubb`	1,549	1,585

openapi-typescript / hey-api / Orval lint errors

For the first three tools, the eslint errors were mainly no-irregular-whitespace.

In my schema, some Django docstrings contained full-width spaces.

Those comments were copied into generated code, and eslint complained.

This is more about source docstrings and lint configuration than generated code quality.

It can usually be handled by:

skipping comments
excluding generated files from lint
adding lint overrides for generated code

Kubb lint errors

Kubb produced many no-explicit-any errors.

Most were in the runtime client side.

This does not mean Kubb is unusable.

But if generated files are included in lint, Kubb almost certainly needs ignore rules or overrides.

Before adopting it, I would decide:

will generated files be committed?
will generated files be linted?
will generated files be checked in CI?
which rules are disabled for generated code?

📝 Configuration notes

Here are some issues I hit while setting up each tool.

openapi-typescript

This was the easiest setup.

A single CLI command worked well.

I did not hit any major configuration problems.

hey-api

hey-api uses openapi-ts.config.ts.

I hit a few small points:

output.format: "prettier" aborts if Prettier is not installed
runtimeConfigPath is emitted as an import path relative to output.path

I initially assumed runtimeConfigPath was relative to the project root.

That was easy to misunderstand.

I shared this with the author, and the related PR was merged the next day.

That fast response was a positive signal for adoption.

Orval

Orval uses orval.config.ts.

It can split outputs by target, which is useful if you want to generate SDKs, Zod schemas, MSW mocks, and other assets separately.

I did not hit major setup issues.

But if you care about auth, refresh, or error handling, you should understand override.mutator early.

Kubb

Kubb configuration is plugin-based.

Depending on your environment, generated imports with .ts extensions may require this tsconfig setting:

{
  "compilerOptions": {
    "allowImportingTsExtensions": true
  }
}

This is not necessarily bad, but it should match your TypeScript and bundler policy.

I had to adjust the setup a few times.

🗨️ My impression of openapi-typescript

openapi-typescript is the thinnest and fastest option.

It generates types and lets you choose the runtime layer yourself, often with openapi-fetch.

What I liked:

very fast generation
simple setup
small generated output
strong focus on type correctness
runtime is separate and flexible

What may be missing:

no generated SDK functions
endpoint calls are path-string based
weaker fit for operationId-based rename refactoring
TanStack Query, Zod, and MSW need separate handling

If you value simplicity, this is very strong.

Especially if codegen runs often in local development or CI, the speed is a real advantage.

🗨️ My impression of hey-api

hey-api felt like the best balance for my use case.

It is thicker than openapi-typescript, but much lighter than Orval or Kubb.

What I liked:

generated SDK functions
consistent { query, path, body } arguments
axios-like interceptors
result model and throwOnError option
shared schema types are easy to use
generated output remains manageable

Weak points:

generation takes longer than openapi-typescript
sdk.gen.ts can become large
weaker than Orval / Kubb for MSW and Faker
NullEnum may degrade into an empty enum in some cases

In my case, NullEnum was not a major practical issue because nullable fields still carried nullable: true through the composed type.

More importantly, BlankEnum preserved the empty string correctly.

For my needs:

I wanted operationId functions
I wanted interceptors
I wanted result-style handling
I did not need generated MSW or Faker yet

So hey-api was the most practical choice.

🗨️ My impression of Orval

Orval is strong if you want OpenAPI to generate a broader frontend layer.

What I liked:

supports TanStack Query, SWR, and Vue Query
can generate Zod
can generate MSW and Faker
can split outputs by target
faster than Kubb in this test
shared body schemas are easy to reuse

Things to watch:

default fetch client does not throw on 4xx / 5xx
auth and refresh usually require a mutator
file count can be large
tag files can become large
NullEnum may degrade into an empty const

If you only want an API client, Orval may feel too thick.

But if you want generated hooks, validation schemas, mocks, and test data, Orval becomes much more attractive.

If I moved deeper into the ecosystem-generation side, I would probably evaluate Orval first.

🗨️ My impression of Kubb

Kubb has a strong philosophy.

What I liked:

close to 1 operation = 1 file
friendly to grep and physical file navigation
structure can be tree-shake friendly
clear plugin-based architecture
can expand into MSW, Faker, TanStack Query, Zod, etc.
gives strong control over the codegen pipeline

What felt heavy in this schema:

slow generation
3,877 files / 24 MB output
many lint errors from any
possible .ts import extension requirements
positional path params make wrappers harder
body types are endpoint-scoped
BlankEnum became never and lost the empty string

Kubb is not a bad tool.

Actually, I like its design philosophy.

But if your main goal is simply "I want a type-safe API client for a normal frontend app," it may be too heavy as the first option.

I would choose Kubb when I have a clear reason, such as:

I strongly want 1 operation = 1 file
I want to design my own codegen pipeline
I want plugin-level control
I want to unify clients, schemas, mocks, and test data through plugins

The potential is high, but it needs commitment.

📓 Summary table

Axis	`openapi-typescript`	`hey-api`	`Orval`	`Kubb`
Family	A: type-focused	A: lightweight SDK	B: frontend asset generation	B: plugin/codegen platform
Generation time	1.5s	8.0s	5.5s	18.1s
Output files	1	16	2,719	3,877
Output size	2.4 MB	2.9 MB	14 MB	24 MB
Generates functions	No	Yes	Yes	Yes
Function split	none	one SDK file	one file per tag	one file per operation
Error model	result union	result union / throw	success wrapper	throw
Client object	external library	generated client	raw fetch / mutator	generated client
Interceptor	openapi-fetch middleware	axios-like	mutator	config / custom client
Path params	`params.path`	`{ path: { id } }`	`{ id }`	positional
Body type	shared schema	shared schema	shared schema	endpoint-scoped
TanStack Query	No	plugin	built-in support	plugin
Zod	No	plugin	built-in support	plugin
MSW / Faker	No	limited	strong	strong
Lint	minor adjustment	minor adjustment	minor adjustment	likely needs ignore/override
drf-spectacular BlankEnum	OK	OK	OK	needs care
Best fit	thin and safe	SDK + interceptors	generate frontend assets	design codegen pipeline

🤔 How I would choose

After this comparison, I would choose like this.

1. Start with openapi-typescript

If your project already works well with openapi-typescript + openapi-fetch, I would stay there.

It is fast, thin, and easy to understand.

A small wrapper like src/api/client.ts plus middleware-based auth may be enough.

There is no need to move to heavier codegen unless you have a concrete pain.

2. Move to hey-api when SDK functions become useful

The next step is usually wanting things like:

call APIs by operationId functions instead of URL strings
grep by function name
use rename refactoring
handle auth and refresh with interceptors
work with consistent endpoint options

At that stage, hey-api is a very good fit.

3. Use Orval when OpenAPI becomes the source of frontend assets

If OpenAPI becomes more than API client generation, Orval becomes strong.

For example:

generated TanStack Query hooks
generated Zod schemas
generated MSW mocks
generated fake data
multiple generation targets

This is where Orval's value becomes much clearer.

4. Choose Kubb when you love the architecture

Kubb is powerful.

But at this schema size, it was also heavy.

I would choose it when I strongly care about:

1 operation = 1 file
plugin architecture
tree-shake-friendly structure
codegen pipeline control
generating many kinds of artifacts consistently

It may not be my first choice for a normal frontend app, but it is very interesting if you want to design codegen itself.

🚀 Final conclusion

OpenAPI codegen should not be chosen only by asking:

Which tool has the most features?

A better question is:

How much generated code are we willing to own?

My final choice looks like this:

Goal	Choice
I only want types	`openapi-typescript`
I want SDK functions and interceptors	`hey-api`
I want to generate frontend assets together	`Orval`
I want to control codegen structure and plugins	`Kubb`

For my current project, hey-api had the best balance of SDK functions, interceptors, result handling, and output size.

The more useful codegen becomes, the bigger the generated forest becomes.

So the important question is:

Who maintains that forest, how much of it, and with what team rules?

That is the real OpenAPI codegen decision.

What does your team generate from OpenAPI?

Only types?
SDK functions?
Hooks?
Mocks?

or the whole forest? 🌳🌳🌳

Why I Didn’t Let AI Handle My Scroll Animation: Astro, React, and TypeScript Architecture

nyaomaru — Thu, 07 May 2026 12:41:31 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who once panicked because I triggered a fire alarm while roasting chashu at home in the Netherlands. 🐖

This time, I want to write about how I built the corporate website for Necoz B.V.

Necoz | Software Development Studio in Amsterdam

Necoz B.V. is a software development studio based in Amsterdam, the Netherlands. We build well-designed systems, clean architecture, and scalable web applications.

necoz.co

The site is built with:

Astro for the base structure
React only where interactive UI is needed
TypeScript for the main animation control
responsive behavior for both desktop and mobile
virtual scrolling to control the scroll amount itself

Because this is a corporate website, I did not want to break SEO.

But I also wanted the motion to feel good.

And I did not want the experience to fall apart on mobile.

When you take these requirements seriously, the important question is not only:

Which technology should I use?

It becomes:

Which responsibility should belong to which layer?

In the end, the hardest part was the animation.

AI was useful. It helped me move fast. It gave me rough ideas and initial implementations.

But the animation it produced was not something I could use as-is.

This article is about why, and how I ended up designing the animation system.

The repository is here:

nyaomaru / necoz

Official Necoz B.V. website with custom scroll animations.

necoz

Necoz B.V. website built with Astro, React islands, and custom scroll / walker animation logic.

Scroll down and enjoy the animations!

You can check it on mobile too 😸

Project Structure

The project is organized like this:

/
├── public/                     # Static files served as-is
├── src/
│   ├── components/
│   │   ├── home/               # Homepage sections
│   │   └── ui/                 # Reusable UI primitives and shared shells
│   │       ├── block/
│   │       ├── button/
│   │       ├── layout/
│   │       ├── mail/
│   │       ├── nyaomaru/
│   │       ├── scene/
│   │       ├── scroll/
│   │       └── text/
│   ├── layouts/                # Shared page layout shells
│   ├── lib/                    # Non-visual shared logic
│   │   ├── nyaomaru/           # Walker controller, scene logic, scene models
│   │   ├── math.ts
│   │   └── site-links.ts
│   ├── pages/                  # Route entrypoints
│   │   ├── index.astro
│   │   └── privacy-policy.astro
│

…

View on GitHub

Let's get into it.

🤔 Why I did not use AI-generated animation as-is

AI-generated animation often looks nice at first glance.

It usually has:

some movement
some easing
some visual atmosphere

But when I looked more carefully, I often felt:

The direction is right, but the timing is wrong.

For example:

the movement was too fast
everything moved with the same rhythm
elements did not stop where they should
there was no pause
there was no sense of timing

AI can generate the rough idea of "how something moves".

But in real animation, what matters is also:

where it stops
where it waits a little
where one element reacts slightly later
where the rhythm changes

Animation is not just about moving from position A to position B.

A small pause, a tiny delay, or a slightly different easing curve can completely change how it feels.

I think this is one of the current gaps between AI and human judgment:

AI can produce motion quickly, but humans still have better sensitivity for timing and rhythm.

So I used AI for rough drafts, structure, and experiments.

But I adjusted the final timing by hand.

🧑‍🚀 Why Astro?

This site is a corporate website.

So I wanted:

real HTML content
good SEO
fast initial loading
no unnecessary SPA architecture

That is why I chose Astro.

https://astro.build/

The page structure is mainly built around src/pages/index.astro and src/layouts/Layout.astro.

The header, sections, footer, and base layout are handled by Astro.

<Layout title={DEFAULT_TITLE} description={DEFAULT_DESCRIPTION} canonicalPath="/">
  <main id="top">
    <Header />
    <HeroIntro />
    <WorkSection />
    <StudioSection />
    <ContactSection />
    <NyaomaruWalker />
  </main>
  <Footer />
</Layout>

The layout also switches between native scrolling and virtual scrolling.

<body class:list={[virtualScroll ? "virtual-scroll-body" : "native-scroll-body"]}>
  {virtualScroll ? <VirtualScroll><slot /></VirtualScroll> : <slot />}
</body>

What I like about Astro is that I do not have to turn the whole site into JavaScript.

Astro lets me output clean HTML first, and then hydrate only the parts that need client-side behavior.

For a corporate website, this is very useful.

In this project, I wanted:

solid page structure
metadata and SEO
client-side animation only where necessary

Astro did not make the animation better by itself.

But it helped me separate structure and behavior cleanly.

That separation was very important.

⚖️ I used React, but not for everything

The site also uses React.

But it is not a full React app.

The responsibility is divided like this:

Astro owns the page structure
React owns small interactive UI parts
TypeScript owns the animation system

For example, the mail dialog is hydrated with client:load.

<div class="contact-links">
  <MailDialogTrigger client:load />
  <SocialLinks />
</div>

The dialog trigger itself is a React component.

export default function MailDialogTrigger() {
  const [isOpen, setIsOpen] = useState(false);

  useEffect(() => {
    if (!isOpen) return;

    const previousOverflow = document.body.style.overflow;
    document.body.style.overflow = "hidden";

    return () => {
      document.body.style.overflow = previousOverflow;
    };
  }, [isOpen]);

  // ...
}

This is a good use case for React.

There is local UI state.

There is user interaction.

There is a dialog.

But that does not mean the entire website needs to become a React application.

This was an important decision:

Using React does not mean everything has to be React.

React is great for UI.

But I did not want React to become responsible for the motion system.

🌊 Animation is controlled by TypeScript, not React state

The core animation logic lives under src/lib/nyaomaru/.

It handles things like:

the walking character
scene progression
scroll-based state updates
DOM measurement
animation phases

Some of the main files are:

File	Responsibility
`walker-controller.ts`	Controls the main walker progression
`work-scene.ts`	Controls the work section scene
`studio-scene.ts`	Controls the studio section scene
`contact-scene.ts`	Controls the contact section scene

This is not a purely declarative animation system.

It is much more direct:

read the current scroll position
determine the active scene
calculate progress
calculate the pose
update the DOM

A simplified version looks like this:

const update = () => {
  const scrollY = getSceneScrollY();
  const activeSceneState = getActiveSceneState(scrollY);

  if (!activeSceneState) return;

  const progress = getSceneProgress(scrollY, activeSceneState.snapshot);
  const pose = activeSceneState.scene.getPose(
    progress,
    activeSceneState.snapshot,
  );

  walker.style.transform = `translate(${pose.x}px, ${pose.y}px)`;
  walker.dataset.phase = pose.phase;
};

const requestUpdate = () => {
  cancelAnimationFrame(rafId);
  rafId = window.requestAnimationFrame(update);
};

The flow is simple:

read the scroll value
find the active scene
calculate progress
calculate the pose
apply it to the DOM

This was easier to tune than putting everything into React state.

React is strong for UI state.

But animation timing often needs a thinner, more direct control layer.

This does not mean React is bad for animation.

It only means that, for this project, the responsibilities were different:

React was for UI
TypeScript was for motion

That separation worked well.

💎 Why I did not avoid direct DOM manipulation

In modern frontend development, we often try to avoid direct DOM manipulation.

Usually, I agree with that direction.

Declarative UI is easier to reason about in many cases.

But scroll-driven animation is a little different.

Sometimes, the important state is not:

What state does this component have?

It is:

What is actually visible on the screen right now?

For this project, I needed to measure things like:

getBoundingClientRect()
viewport width
which block is currently visible
whether the desktop or mobile layout is active
where the walker is currently positioned

This was similar to what I learned while building a browser game before:

nyaomaru

Apr 8

Building a Browser Game with React: What Doesn’t work well (Run Away From Work)

#gamedev #typescript #react #webdev

6 min read

The animation depends on the actual layout.

So the DOM is not just an output target.

It is also something the animation system has to observe.

In this case, directly measuring the DOM made the intention clearer.

It also avoided unnecessary indirection.

So I did not avoid direct DOM manipulation completely.

I used it only where it made sense.

😿 Responsive design was not only a CSS problem

The site also supports mobile.

But responsive behavior here was not only about changing layout with CSS.

For several sections, I have different block structures for desktop and mobile.

For example, the hero, work, and studio sections have:

desktop blocks
mobile blocks

The visible block changes depending on the viewport.

The TypeScript animation logic also uses a 430px mobile breakpoint and changes things like scene progress, landing positions, and offsets.

const workStack = isMobileViewport()
  ? getVisibleElement("[data-work-mobile-origin]")
  : getVisibleElement("[data-work-scene-display]");

const stackRect = workStack.getBoundingClientRect();
const walkerRect = walker.getBoundingClientRect();

const shotX =
  walkerRect.right +
  (isMobileViewport() ? MOBILE_SHOT_OFFSET_X : SHOT_OFFSET_X);

The markup also separates desktop and mobile blocks.

<div class="block block-three block-three--desktop">...</div>
<div class="block block-three block-three--mobile">...</div>

So responsive design in this project affected:

DOM structure
scroll progression
animation targets
movement distance
position correction

If I handled only the visual layout, the desktop version might feel good, but the mobile version would break quickly.

For scroll-driven animation, responsive design is not only layout adjustment.

It is also motion redesign.

📏 Why I used virtual scroll

One of the most important parts of this site is virtual scrolling.

The layout uses VirtualScroll.astro, and inside that layer, a custom scroll controller runs.

The goal was not just to make scrolling look fancy.

The real goal was to separate:

visual scroll
scene scroll
scrollbar behavior
smooth scroll following
animation progression

In the implementation, I separate visualScrollY and sceneScrollY.

const applyScroll = () => {
  const visualScrollY = getVisualScrollY();
  const sceneScrollY = getSceneScrollY();

  content.style.top = `${-visualScrollY}px`;
  setScrollState({ sceneScrollY, visualScrollY });
  window.dispatchEvent(new CustomEvent("necoz:virtual-scroll"));
};

The scroll values are read like this:

export const getVisualScrollY = () => window.__necozScrollY ?? window.scrollY;

export const getSceneScrollY = (visualScrollY = getVisualScrollY()) =>
  window.__necozSceneScrollY ?? visualScrollY;

This separation was very important.

If everything depends directly on native scroll, it becomes harder to control the rhythm.

For example, I wanted to adjust cases like:

the page visually moved down, but the scene should wait a little more
the footer area needs denser animation
mobile should use a different scroll progression
some scenes should feel slower or more deliberate

With virtual scroll, I can separate:

how much the page visually moves

from:

how much the animation scene progresses

That means I can design the time axis myself.

This was the main reason I used virtual scroll.

Not because it looks cool.

But because I wanted control over animation time.

For scroll-driven animation, scroll is not just movement.

Scroll is input.

And if scroll is input, it needs to be designed carefully.

🤖 Where AI was useful

At this point, it might sound like I do not trust AI.

That is not true.

AI was very useful for:

generating rough drafts
trying implementation patterns
splitting responsibilities
getting something working quickly
exploring ideas before committing to one direction

As a tool for the first step, AI is excellent.

But final animation tuning was different.

For example, walking, falling, and landing phases were separated like this:

export const lerp = (start: number, end: number, progress: number) =>
  start + (end - start) * progress;

if (progress > secondFallStart) {
  return {
    x: lerp(layout.secondFallX, layout.landingX, secondFallProgress),
    y: lerp(
      layout.secondRunY,
      layout.landingY,
      Math.pow(secondFallProgress, HERO_FALL_EASING_POWER),
    ),
    phase: "second-fall",
  };
}

if (progress > secondRunStart) {
  return {
    x: lerp(layout.firstFallX, layout.secondFallX, secondRunProgress),
    y: layout.secondRunY,
    phase: "second-run",
  };
}

This kind of adjustment required a repeated loop:

look at the animation
feel that something is slightly wrong
adjust a function or a number
check it again
repeat

AI helped me move fast.

But speed alone was not enough.

For this kind of site, the character walks, the scene changes, and the rhythm follows the scroll.

The final feeling had to be adjusted by hand.

I think this is one of the areas where frontend engineers will still matter in the AI era.

Not only writing code faster.

But deciding whether the result actually feels good.

💖 What I learned from this architecture

The main lessons from this project are:

separate HTML structure and animation behavior
separate UI state and animation state
treat scroll as input, not just movement
responsive animation requires motion redesign, not only layout changes
direct DOM measurement can be valid when the screen itself is part of the state
AI is useful for speed, but timing and rhythm still need human judgment

For scroll-driven animation, this kind of separation made the system much easier to reason about.

🎯 Summary

For the Necoz B.V. website, I used:

Astro for page structure and initial HTML
React for small interactive UI parts
TypeScript for the main animation control
direct DOM measurement where needed
responsive motion logic for desktop and mobile
virtual scroll to redesign scroll progression

The biggest benefit was that I could keep SEO and initial rendering stable while still keeping control over the motion system.

AI helped a lot.

But there is still a gap between:

animation that moves

and:

animation that feels alive

So I did not let AI handle everything.

I used it to move faster, organize ideas, and create rough versions.

But I kept the final timing and rhythm in my own hands.

In the end, I think what I was really building was not just a layout or an animation.

I was designing time along the scroll.

Thanks for reading!

If you found this interesting, the repository is public.

A star ⭐ would make me very happy 😸

https://github.com/nyaomaru/necoz

Handling `unknown` in TypeScript… isn't it painful?

nyaomaru — Tue, 28 Apr 2026 13:09:54 +0000

Hi there 👋

I'm a frontend engineer based in the Netherlands, currently suffering from hay fever 😿

API responses, form inputs, external data…

In TypeScript, we often end up dealing with unknown,
and handling it properly can become a real pain in day-to-day work.

Yes, unknown has a kind of gravitational pull like the universe.

But still…
we do want to handle types safely, right?

That’s where is-kit comes in a library for composing type guards.

nyaomaru / is-kit

Lightweight, zero-dependency toolkit for building `isFoo` style type guards in TypeScript. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨. npm -> https://www.npmjs.com/package/is-kit

is-kit

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

📚 Documentation Site

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter, and other TypeScript control flow
compose validation logic…

View on GitHub

Libraries like Zod take a schema-first approach.

In contrast, is-kit focuses on narrowing types within your existing code.

Instead of “writing validation”, you can think of it as extending your everyday if statements with type safety.

If Zod is for boundaries (API / input)
is-kit is for inside your application logic

A simple example

Imagine you need to check “strings with length ≤ 3” multiple times.

With is-kit, you can define it once and reuse it:

import { define, isString } from "is-kit";

const isShortString = define<string>(
  (value) => isString(value) && value.length <= 3,
);

Then use it like this:

import { isShortString } from "~/utils/is";

declare const input: unknown;

// before → repeating conditions every time
if (typeof input === "string" && input.length <= 3) {
  input.toUpperCase();
}

// after → reusable guard
if (isShortString(input)) {
  input.toUpperCase();
}

This style works seamlessly with
if, filter, map, and other existing logic.

🐾 How `is-kit` has evolved

It’s been about 6 months since the v1.0 release.

Back then, is-kit started as a lightweight type guard library
with primitives like:

define
and
or
struct
arrayOf

Since then, up to v1.6, it has gradually evolved into something more practical:

👉 a toolkit for handling unknown values in real-world applications

Let’s look at 5 major improvements.

🪄 1. Distinguishing “missing” vs “undefined” in `struct`

A common situation in API responses:

A key is missing entirely
A key exists but its value is undefined

These are not the same.

With v1.5.0, optionalKey(...) was introduced:

import { isString, optional, optionalKey, struct } from "is-kit";

const isUser = struct({
  id: isString,
  nickname: optionalKey(isString),
  displayName: optionalKey(optional(isString)),
});

This allows you to express both cases explicitly.

🔑 2. Key-based narrowing (`hasKey`, `hasKeys`, `narrowKeyTo`)

From v1.1.13 and v1.4.0, key-based utilities were added:

import {
  hasKeys,
  narrowKeyTo,
  oneOfValues,
  struct,
  isString,
  isNumber,
} from "is-kit";

const isUser = struct({
  id: isString,
  age: isNumber,
  role: oneOfValues("admin", "guest", "trial"),
});

const hasRoleAndId = hasKeys("role", "id");
const byRole = narrowKeyTo(isUser, "role");
const isGuest = byRole("guest");

This lets you build on top of existing guards instead of redefining everything.

🧪 3. `assert` for fail-fast validation

Added in v1.2.0:

import { assert, isString } from "is-kit";

declare const input: unknown;

assert(isString, input, "input must be a string");
input.toUpperCase();

You can now use guards in a fail-fast style when needed.

✨ 4. Support for `Set` and `Map`

With v1.6.0:

import { mapOf, setOf, isString, isNumber } from "is-kit";

const isTags = setOf(isString);
const isScores = mapOf(isString, isNumber);

Not everything is an array in real-world apps —
this expands coverage to common JS data structures.

🥏 5. Handling numeric edge cases

From v1.1.x:

isInteger
isSafeInteger
isPositive
isNegative
isNaN
isInfiniteNumber
isZero

These help you express “valid numbers” more precisely.

🌟 More features

There are more utilities available —
feel free to explore the docs:

is-kit-docs.vercel.app

🎯 Summary

is-kit started as a small, composable type guard library.

Over time, it has evolved into:

👉 a practical toolkit for handling unknown in application code

Key improvements:

More expressive object schemas (optionalKey)
Better key-based narrowing
Fail-fast assertions
Collection support (Set, Map)
Rich numeric guards

The goal of is-kit is simple:

👉 Make type-safe code feel natural to write

If you try it and have ideas or feedback, feel free to share!

See you in the next post 👋

https://github.com/nyaomaru/is-kit

is-kit vs Zod: A Practical Comparison from 3 Perspectives

nyaomaru — Wed, 22 Apr 2026 12:32:02 +0000

Hi everyone!

I’m a frontend engineer who sometimes wonders:

“Am I using AI… or is AI using me?”

When writing runtime validation in TypeScript,

Zod is usually the first choice.

There are other options like Valibot and ArkType,

but today I want to look at something a bit different:

nyaomaru / is-kit

Lightweight, zero-dependency toolkit for building `isFoo` style type guards in TypeScript. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨. npm -> https://www.npmjs.com/package/is-kit

is-kit

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

📚 Documentation Site

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter, and other TypeScript control flow
compose validation logic…

View on GitHub

At first glance, is-kit and Zod look similar.

But their design philosophy is very different.

is-kit → a toolkit to compose type guards
Zod → a library to define schemas and validate data

So instead of asking “which is better?”,

let’s compare them from a practical angle:

When is each one easier to write?

We’ll look at:

Code size
Readability
How they handle types

Same Example

Let’s validate a simple User.

🔧 is-kit

import {
  and,
  isInteger,
  isString,
  oneOfValues,
  optionalKey,
  predicateToRefine,
  safeParse,
  struct,
} from "is-kit";

const isPositiveInt = and(
  isInteger,
  predicateToRefine<number>((v) => v > 0),
);

const isUser = struct({
  id: isPositiveInt,
  name: isString,
  role: oneOfValues(["admin", "member"] as const),
  nickname: optionalKey(isString),
});

const result = safeParse(isUser, input);

if (result.valid) {
  result.value.role;
}

💎 Zod

import { z } from "zod";

const UserSchema = z.object({
  id: z.number().int().positive(),
  name: z.string(),
  role: z.enum(["admin", "member"]),
  nickname: z.string().optional(),
});

const result = UserSchema.safeParse(input);

if (result.success) {
  result.data.role;
}

You can already see the difference:

is-kit → compose small guards (function-based)
Zod → define a schema (declarative)

1. Code Size

Zod often looks shorter.

Why?

Because you can stack constraints in one place:

z.string().min(1).max(20).regex(...)
z.number().int().positive()

This works very well for:

Forms
API validation
Input boundaries

On the other hand, is-kit shines when you want to reuse guards.

if (isUser(value)) {
  // already narrowed
}

const users = values.filter(isUser);

You can directly pass guards into control flow.

With Zod, you usually go through safeParse,
so it feels more like “calling validation”.

👉 Summary:

Want centralized validation rules → Zod
Want reusable guards in logic → is-kit

2. Readability

This depends on what “readable” means to you.

💎 Zod

All rules are in one place:

const UserSchema = z.object({ ... });

You can instantly see:

👉 “What shape is valid?”

Great for boundaries.

🔧 is-kit

is-kit feels like normal TypeScript control flow.

It also lets you compose guards step by step:

import { hasKey, narrowKeyTo } from "is-kit";

const hasRole = hasKey("role");

if (hasRole(value)) {
  value.role;
}

const byRole = narrowKeyTo(isUser, "role");
const isAdmin = byRole("admin");

if (isAdmin(value)) {
  value.role;
  value.name;
}

You can:

Narrow the whole shape (isUser)
Focus on a specific key (role)
Narrow further (admin)

This fits naturally with:

“Receive unknown → narrow step by step”

👉 Summary:

Want a clear spec of valid data → Zod
Want natural control flow narrowing → is-kit

3. How Types Are Handled

This is where the biggest difference appears.

💎 Zod → Schema → Type

type User = z.infer<typeof UserSchema>;

Define schema
Generate type

Best when you want:

“Validation and types in one place”

🔧 is-kit → Guard → Narrowing

is-kit focuses on control flow:

if (isUser(input)) {
  input.role;
}

The type is narrowed automatically.

You can also extract the type:

import type { GuardedOf } from "is-kit";

type User = GuardedOf<typeof isUser>;

But the main strength is not type generation.

👉 It’s this:

TypeScript understands your logic as you narrow values

Core Difference

Zod → strong at schema → type
is-kit → strong at guard → control flow narrowing

Summary

Perspective	Zod 💎	is-kit 🔧
Code size	Great for schema	Great for reuse
Readability	Clear validation rules	Natural control flow
Type handling	Schema-driven types	Control flow narrowing

When to Use Each

My approach:

Use Zod for external inputs
- API
- forms
- environment variables
Use is-kit for internal logic
- condition branches
- filtering
- composing guards

They Are Not Competitors

These tools are not direct competitors.

They work well together.

👉 Clean separation:

Zod → validate at boundaries
is-kit → refine inside your app

Conclusion

is-kit is not a lightweight version of Zod.

It focuses on a different idea:

Making type guards feel natural in TypeScript

And Zod is still extremely strong:

Schema-first validation with type safety

The real question is not:

“Which one is better?”

But:

“Where do you enforce type safety in your design?”

Try it if you're interested:

👉 https://github.com/nyaomaru/is-kit

Building a Browser Game with React: What Doesn’t work well (Run Away From Work)

nyaomaru — Wed, 08 Apr 2026 14:30:28 +0000

Hi!

I'm @nyaomaru, a frontend engineer who finally managed to make it to the first zombie in Resident Evil 9. It was terrifying. 🧟🧑‍⚕️

A couple of articles ago, I introduced a browser game I built. Have you played it yet?

Game - Nyaomaru

Portfolio of Nyaomaru – A frontend engineer specializing in Vue, React, and TypeScript.

nyaomaru-portfolio.vercel.app

At first glance, it looks like a very simple game. But once I actually started building it, I ran into a surprising number of tricky problems.

In this article, I’ll share the main things that tripped me up and how I dealt with them.

Let’s get into it.

🍽️ Quick recap

I built a browser game with:

Remix × React × TypeScript × FSD

If you want the full background, check out my previous two articles:

nyaomaru

Mar 18

I Built a “Run Away From Work” Browser Game with React and TypeScript

#gamedev #webdev #react #typescript

5 min read

nyaomaru

Mar 25

Run Away From Work — Stopped Using React for the Game Loop

#showdev #gamedev #react #typescript

6 min read

⛳ What I struggled with

These were the biggest issues:

extra whitespace when animating SVG-based sprites
inconsistent frame behavior across different screen sizes and devices
AI not generating the CSS animation I actually wanted
collision detection that didn’t match the visuals

Let’s go through them one by one.

1. SVG sprite animation and the whitespace problem

At first, I thought:

“They’re SVGs. Animation should be easy if I just swap them nicely.”

It was not easy at all.

The biggest issue was this:

Even when two SVGs looked like they were the same size, their positions shifted during animation.

For example:

frame 1 and frame 2 of the running animation had slightly different visual centers
the boss’s idle state and attack state didn’t line up at the bottom
even with the same width and height, the actual rendered position didn’t match perfectly

So from React’s point of view, I was “just swapping images of the same size.”

But in reality, differences in the SVG viewBox and internal whitespace made them visibly jump.

In the end, instead of trying to force the SVG contents to align perfectly, I treated the outer container as fixed and only swapped the sprite inside it.

<img
  ref={playerSpriteRef}
  src={PLAYER_RUN_SPRITES[0]}
  alt="player"
  className={styles.playerSprite}
  draggable={false}
  aria-hidden
/>

.playerSprite {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: contain;
  object-position: center bottom;
}

The key was to align everything to the bottom.

That alone greatly reduced the weird “bouncing” feeling when frames switched.

🔑 The takeaway here was:

Treat SVGs not as visuals, but as boxes that include invisible padding. 📦

If you underestimate that, it will absolutely come back to bite you later.

2. DOM movement behaving differently depending on display size and device

This was the next problem.

At first, I used requestAnimationFrame and moved obstacles left a little bit on every frame.

That sounds reasonable, but it caused the game speed to vary depending on the device.

requestAnimationFrame does not guarantee perfectly consistent timing.

That led to problems like:

the game felt smooth on desktop
obstacles looked slower on mobile when FPS dropped
differences in screen size and rendering load changed the perceived difficulty

If I left that alone, the exact same code would create effectively different games on different devices.

So instead of moving things by a fixed amount per frame, I switched to time-based movement.

The important thing here was using deltaTime.

deltaTime represents how many milliseconds passed between the previous frame and the current one.

For example:

at 60fps, one frame is about 16.6ms
at 30fps, one frame is about 33.3ms

So when FPS drops, each frame covers more time.

If you move an obstacle by the same number of pixels every frame, then lower-FPS devices will make the obstacle move more slowly overall.

But with deltaTime, you can adjust movement based on elapsed time.

const frameDistancePx = (obstacleSpeedPxPerSec * deltaTimeMs) / 1000;
obs.style.left = `${Number.parseFloat(obs.style.left) - frameDistancePx}px`;

This made it much easier to keep movement consistent on a per-second basis, even when FPS fluctuated.

That said, deltaTime alone was not enough to fully close the gap.

So after switching to time-based movement, I also:

used different speed constants for mobile and desktop
applied an additional pace scale only on large desktop screens

That let me preserve the original feel on desktop without making mobile gameplay too slow or too heavy.

🔑 The takeaway here was:

Game logic should be designed around time, not frames. 🕛

Browser games may look simple, but if you ignore device differences, the overall quality drops fast.

3. AI couldn’t generate the CSS animation I actually wanted

This one was subtle, but painful.

For some effects, like the clear animation, I needed something with these characteristics:

the image changes midway
the starting position is only known at runtime
the duration also changes depending on the situation
but the overall animation shape should stay fixed

This kind of thing did not go well with codex.

It really struggled with animations that included dynamic values like runtime position and duration.

So I ended up handling this part myself.

At first, I tried doing everything inline.

But once I started pushing even @keyframes-related concerns into the component, the responsibilities between rendering and visual behavior got messy very quickly.

So I split it like this:

fixed animation definitions live in CSS Modules
only dynamic values like position and duration are passed via CSS variables

<div
  className={styles.flyoutMotion}
  style={
    {
      "--flyout-origin-x": `${specialFlyoutOrigin.x}px`,
      "--flyout-origin-y": `${specialFlyoutOrigin.y}px`,
      "--flyout-duration-ms": `${specialFlyoutDurationMs}ms`,
    } as CSSProperties
  }
/>

.flyoutMotion {
  left: var(--flyout-origin-x);
  top: var(--flyout-origin-y);
  animation: special-flyout-motion var(--flyout-duration-ms)
    cubic-bezier(0.24, 0.82, 0.22, 1) forwards;
}

From there, I fine-tuned the easing with cubic-bezier and adjusted the actual motion in the browser, kind of like shaping keyframes in After Effects.

🔑 The takeaway here was:

Keep fixed animation logic in CSS, and pass only dynamic values through CSS variables. 🫱

That separation made the animation code much easier to reason about and tweak later.

4. Collision detection didn’t match the visuals

And finally, collision detection.

This is always painful in browser games, and this project was no exception.

The main issue was this:

The visual shape and the actual collision area did not match.

When I naïvely used getBoundingClientRect() against everything, I ran into problems like:

collisions triggering even when it didn’t look like the player touched anything
obvious hits sometimes slipping through

The reasons were mainly these two:

the visible SVG shape didn’t match its rectangular bounds
the “visually correct” size and the “feels fair in gameplay” size were different for each obstacle

For example, desk-type obstacles had a large visual box, so using the raw rectangle made collisions feel unfair.

Here’s what the desk obstacle looked like:

So I separated visual size from hitbox size.

obstacleElement.dataset.hitboxScale = `${resolvedHitboxScale}`;

const hitboxScale = Number(obs.dataset.hitboxScale ?? "1");
const obstacleHitbox = getScaledHitboxFromRectLike(obstacleBox, hitboxScale);
const isCollision =
  !!playerRect && isPlayerOverlappingHitbox(playerRect, obstacleHitbox);

That way, the obstacle could stay visually large and impactful, while the collision box could be slightly reduced to feel fair.

This also made balancing much easier, because I could tweak hitbox scale per obstacle.

🔑 The takeaway here was:

Visuals and collision should be designed separately. 🛠️

This was probably the part that made me feel the most like, “Okay, now I’m actually building a game.”

Summary

The game looks simple, but the implementation involved a lot of careful decisions.

The biggest lessons were:

treat SVGs as boxes that include whitespace
design movement based on time, not frames
separate CSS and JS responsibilities clearly
separate visuals and hit detection

Getting these details right makes a huge difference in how polished the game feels.

So if you’re thinking about building a browser game, I’d really recommend paying attention to these parts from the beginning. 🚀

Also, the repository is public, so feel free to take a look:

nyaomaru / nyaomaru-portfolio

"Run Away From Work" Game is here → https://nyaomaru-portfolio.vercel.app/game

Nyaomaru Portfolio

"Run Away From Work"

You can play here: https://nyaomaru-portfolio.vercel.app/game

A Remix + React + TypeScript portfolio built with Feature-Sliced Design.

🚀 Highlights

Jump Game (Main Feature): Side-scrolling jump game with obstacles, boss phases, clear sequences, and restart flow.
Interactive Terminal: Ask profile-related questions in a terminal-style UI backed by the /api/ask endpoint.
Responsive UI: Works across desktop and mobile layouts.
FSD Architecture: Organized by features/widgets/pages/shared layers.

🎮 Main Feature: Game

The game is available at /game.

Can you watch true ending? 🚀

🕹️ Controls

Action	Description
Space / Click	Jump
Tap	Jump
Double Jump	Jump again while in the air

💻 Terminal

The terminal is available on the top page and is designed for profile Q&A.

✨ What It Does

Sends user input to /api/ask.
Returns an AI-generated answer based on profile context.
Shows typing/waiting states in terminal history.

⚠️ Important

/api/ask…

View on GitHub

Bonus: Sound effects matter too

One thing that turned out to be more important than I expected was sound. 🔊

Audio files need to be lightweight. Even a small delay can hurt the feel of the game.

I originally exported my sound effects from GarageBand as wav files, but the file sizes were too large and the game started to feel noticeably heavier.

So I used ffmpeg to convert them to ogg and reduce the size.

ffmpeg -i input.wav -ac 1 -ar 22050 -b:a 64k output.ogg

After converting them like this, things got much lighter.

And just to be safe, I also recommend preparing an mp3 fallback.

So the takeaway here was:

Small sound files matter. A lot. If you care about game feel, optimize audio too. 👍

Happy coding! 💻

Run Away From Work — Stopped Using React for the Game Loop

nyaomaru — Wed, 25 Mar 2026 13:11:16 +0000

Play the game here 👈

Hi there!

I’m @nyaomaru, a frontend engineer who got Resident Evil 9 from NVIDIA and is still too scared to make it to the first zombie. 🧟

In my previous article, I introduced my small browser game, Run Away From Work.

At first glance, it looks like a very simple game.

But while building it, I realized something important:

If you design the game around setState on every frame, it falls apart very quickly.

Every frame becomes:

setState → re-render → diff → DOM update

And if you try to do that at 60fps, it gets heavy fast.

That does not mean React is bad for games.

It means this is the wrong place to use React’s rendering model.

So in this article, I want to share how I changed the architecture:

I used React for the structure
and direct DOM manipulation for high-frequency game updates

🐾 Quick recap

This game was built with:

Remix
React
TypeScript
Feature-Sliced Design

If you want the overview of the project itself, here is the previous article:

nyaomaru

Mar 18

I Built a “Run Away From Work” Browser Game with React and TypeScript

#gamedev #webdev #react #typescript

5 min read

Even though this game is built in React, the most important part of the runtime behavior is not really handled by React.

Why?

Because the mental model of React and the mental model of a game loop are very different.

✏️ What this article focuses on

Last time, I wrote more about why I made the game.

This time, I want to focus more on the how.

There are 3 points I especially want to show:

I used plain DOM rendering, not Canvas
I split the game logic into small hooks with clear responsibilities
I added several small optimizations to make it feel smooth in the browser

All the visuals in the game are SVGs I made myself in Adobe Illustrator.

🥣 React as the shell, DOM as the runtime

This game looks like a React app, but I did not build it in a way that re-renders everything every frame.

On the React side, I only render the stable structure of the scene.

return (
  <section className={ROOT_CLASS_NAME}>
    <section ref={refs.gameRef} className={GAME_AREA_CLASS_NAME}>
      <FishCounterOverlay
        fishCount={fishCount}
        fishCounterIconSrc={fishCounterDisplayIconSrc}
      />

      <PlayerLayer
        playerRef={refs.playerRef}
        playerSpriteRef={refs.playerSpriteRef}
        playerStyle={playerStyle}
      />

      <BossLayer
        shouldRenderBoss={shouldRenderBoss}
        bossRef={refs.bossRef}
        bossSpriteRef={refs.bossSpriteRef}
        bossArmRef={refs.bossArmRef}
        bossStyle={bossStyle}
        bossArmStyle={bossArmStyle}
      />
    </section>
  </section>
);

Here, React owns the static layers of the game:

player
boss
UI overlay
base scene structure

But moving entities like obstacles and fish are not stored in React state.

Instead, I create DOM nodes directly when needed.

const spawnObstacle = () => {
  const obs = document.createElement("img");

  obs.src = OBSTACLE_ICON_SOURCES[iconIndex];
  obs.style.position = "absolute";
  obs.style.bottom = "0px";

  initializeMovingEntityMotion(obs, getSpawnLeft());

  gameRef.current?.appendChild(obs);
  obstaclesRef.current.push(obs);
};

The reason is simple:

If I store side-scrolling obstacles in a React array state and update them frame by frame, the update cost becomes unnecessarily high.

React is great at building and updating UI structure.

But for game-like behavior where positions change dozens of times per second, directly manipulating the DOM through refs felt much more natural.

It also made the behavior easier to trace and debug.

🍴 React and games optimize for different things

React is based on this model:

state changes
re-render
reconcile
apply DOM updates

Games are usually based on this model:

update positions every frame
move objects every frame
detect collisions every frame
advance the simulation continuously

Those are not the same thing.

So in this project, I separated the responsibilities like this:

React for layout and UI
imperative DOM updates for high-frequency motion

That separation made the architecture much easier to work with.

What I stopped doing

At first, I tried to manage everything with useState.

That quickly led to:

re-rendering on every frame
unnecessary diffing
worse performance
visibly choppy movement

So halfway through development, I changed the design.

I stopped trying to make the entire game fully declarative.

✂️ Splitting game logic into hooks

The hub of the whole game scene is useJumpGameScene.

const [gameOver, setGameOver] = useState(false);
const [showBoss, setShowBoss] = useState(false);
const [fishCount, setFishCount] = useState(0);

const { jump, isOnGroundRef, resetJumpState, updateJumpFrame } =
  useJump(playerRef);
const { obstaclesRef, spawnObstacle, spawnFish, clearObstacles } =
  useObstacles(gameRef);
const { resetPlayerSpriteState, updatePlayerSpriteFrame } =
  usePlayerSpriteAnimator({
    playerSpriteRef,
    gameOver,
    isOnGroundRef,
  });

useGameLoop({
  gameOver,
  bossRef,
  playerRef,
  obstaclesRef,
  gameRef,
  updateJumpFrame,
  updatePlayerSpriteFrame,
  setGameOver,
  setShowBoss,
  setGameOverIcon,
});

Here is the rough responsibility split:

Hook	Responsibility
`useJump`	Jump behavior
`useObstacles`	Spawn and remove obstacles / fish
`usePlayerSpriteAnimator`	Switch between running / jumping sprites
`useGameLoop`	Per-frame progression
`useJumpGameScene`	Compose everything and expose values to the UI

The key idea is this:

use useState only for values the UI actually needs to render
use useRef for fast-changing internal state

For example, the jump behavior looks like this:

const posRef = useRef(0);
const jumpMotionPhaseRef = useRef<JumpMotionPhase>("idle");

const updateJumpFrame = ({ nowMs, deltaTimeMs }) => {
  if (jumpMotionPhaseRef.current === "ascending") {
    posRef.current = Math.min(
      jumpMaxHeightRef.current,
      posRef.current + ASCENT_VELOCITY_PX_PER_MS * deltaTimeMs,
    );
    playerRef.current!.style.bottom = `${posRef.current}px`;
    return;
  }

  if (jumpMotionPhaseRef.current === "descending") {
    posRef.current = Math.max(
      0,
      posRef.current - descentVelocityPxPerMsRef.current * deltaTimeMs,
    );
    playerRef.current!.style.bottom = `${posRef.current}px`;
  }
};

This means the jump position is updated without going through React rendering.

Instead of storing the player’s vertical position in state and re-rendering on every frame, I keep it in a ref and write it directly to the DOM.

That tradeoff worked much better for this kind of game behavior.

🧵 One game loop controls the clock

The game progression runs on top of requestAnimationFrame.

const loop = () => {
  const nowMs = performance.now();
  const timing = getFrameTiming(nowMs, lastFrameAtMsRef.current);
  lastFrameAtMsRef.current = timing.nowMs;

  updateJumpFrame?.({ nowMs: timing.nowMs, deltaTimeMs: timing.deltaTimeMs });
  updatePlayerSpriteFrame?.({ nowMs: timing.nowMs });

  const fatalCollisionIcon = updateObstaclesFrame({
    deltaTimeMs: timing.deltaTimeMs,
    obstacleSpeedPxPerSec,
    obstaclesRef,
    playerRef,
    getGameWidth,
    getPlayerRect: () => playerRef.current?.getBoundingClientRect() ?? null,
    getGameRect: () => gameRef.current?.getBoundingClientRect() ?? null,
  });

  if (fatalCollisionIcon !== undefined) {
    triggerFault(fatalCollisionIcon);
    return;
  }

  animationId = requestAnimationFrame(loop);
};

This loop handles things like:

jump updates
sprite animation updates
obstacle movement
collision checks
boss appearance
clear / fail transitions

So useGameLoop acts as the central clock of the game, while the other hooks behave like specialized modules plugged into that clock.

That structure helped me keep the logic separated without scattering time-related behavior everywhere.

🕶 Small optimizations mattered a lot

A lot of the smoothness came from tiny DOM-side optimizations.

Moving elements with transform

For movement, I avoided updating left every frame.

Instead, I used transform: translate3d(...).

export const initializeMovingEntityMotion = (
  element: HTMLElement,
  spawnLeftPx: number,
) => {
  element.style.left = `${spawnLeftPx}px`;
  element.dataset.spawnLeftPx = `${spawnLeftPx}`;
  element.dataset.translateXPx = "0";
  element.style.transform = `translate3d(0px, 0px, 0px)`;
  element.style.willChange = "transform";
};

export const advanceMovingEntityMotion = (
  element: HTMLElement,
  frameDistancePx: number,
) => {
  const nextTranslateXPx = translateXPx - frameDistancePx;
  element.dataset.translateXPx = `${nextTranslateXPx}`;
  element.style.transform = `translate3d(${nextTranslateXPx}px, 0px, 0px)`;
};

This helps avoid unnecessary layout work and gives the browser a stronger hint that the element is going to move.

Avoiding unnecessary sprite swaps

I also avoided changing the player sprite image more than necessary.

For example:

preload sprite assets in advance
skip updates if the current sprite is already correct
briefly keep the same sprite after landing to make the animation feel better

if (
  currentPlayerSpriteRef.current === spritePath &&
  isSameSpriteSource(playerSpriteRef.current.src, spritePath)
) {
  return;
}

if (preloadedPlayerSprites.has(spritePath)) {
  applySprite();
  return;
}

This kind of thing is small, but it affects the feeling of responsiveness more than I expected.

Only calculating when needed

Collision handling also avoids doing full getBoundingClientRect() calls every single time.

I cache width, height, and bottom values in dataset when entities are created, then reconstruct their rectangle when possible.

const obstacleBox =
  resolvedGameRect === null
    ? obs.getBoundingClientRect()
    : (getObstacleRectFromCachedLayout(obs, currentLeftPx, resolvedGameRect) ??
      obs.getBoundingClientRect());

And I do not even start collision checks until the obstacle is close enough to the player.

if (currentLeftPx < gameWidth - OBSTACLE_PLAYER_PROXIMITY_CHECK_PX) {
  resolvedPlayerBox ??= getPlayerRect();
  resolvedGameRect ??= getGameRect();
  // collision logic starts here
}

That idea was very effective.

There is no reason to do precise collision work for an obstacle that is still far away on the right side of the screen.

That kind of selective work made the movement noticeably smoother.

🎯 Final thoughts

The main lessons from this implementation were:

Use React for layout and UI
Use refs and direct DOM manipulation for high-frequency updates
Split the logic into hooks with focused responsibilities
Stack small optimizations like transforms, cached rects, proximity-based collision checks, and sprite preloading

So the conclusion is not:

React is bad for browser games

It is closer to this:

React is not a great place to run your core game loop.

For this project, the best balance was:

declarative structure
imperative runtime behavior

If I build a different kind of game in the future, I might choose Canvas or WebGL.

But for a small game embedded naturally inside a portfolio site, I found that a DOM-based approach worked surprisingly well.

Bonus

If you liked the game, I would love it if you starred the repository ⭐:

nyaomaru / nyaomaru-portfolio

"Run Away From Work" Game is here → https://nyaomaru-portfolio.vercel.app/game

Nyaomaru Portfolio

"Run Away From Work"

You can play here: https://nyaomaru-portfolio.vercel.app/game

A Remix + React + TypeScript portfolio built with Feature-Sliced Design.

🚀 Highlights

Jump Game (Main Feature): Side-scrolling jump game with obstacles, boss phases, clear sequences, and restart flow.
Interactive Terminal: Ask profile-related questions in a terminal-style UI backed by the /api/ask endpoint.
Responsive UI: Works across desktop and mobile layouts.
FSD Architecture: Organized by features/widgets/pages/shared layers.

🎮 Main Feature: Game

The game is available at /game.

Can you watch true ending? 🚀

🕹️ Controls

Action	Description
Space / Click	Jump
Tap	Jump
Double Jump	Jump again while in the air

💻 Terminal

The terminal is available on the top page and is designed for profile Q&A.

✨ What It Does

Sends user input to /api/ask.
Returns an AI-generated answer based on profile context.
Shows typing/waiting states in terminal history.

⚠️ Important

/api/ask…

View on GitHub

You can also play it on Itch:

nyaomaru.itch.io

DEV Community: nyaomaru

How I Made JavaScript Execution Visual and Rewindable (DSA View View 👀👀)

How I Built the Editor and Compile Pipeline for a TypeScript DSA Visualizer (DSA View View 👀👀)

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

Why Try It?

📝 The Big Picture: Turning Execution into an Array of Steps

🔭 Runtime: Planting Observation Points in the Code

Injecting recordStep into the AST

Injecting the Code Is Easier Than Not Breaking It

🖍️ ExecutionStep: Making Execution Replayable

Saving References Would Rewrite the Past

The "Delta Snapshot" Is Really More Like a Patch

Why Can the Timeline Move Backward?

There Is a Generator, but It Does Not Suspend the User’s Code Line by Line

⚙️ Web Worker: Do Not Take the UI Down with You

A Worker Is Not a Security Sandbox

👀 Visualization: Variables Alone Are Not Enough

Visualization Is Built from ExecutionState

🧪 Tests: Reducing the Number of "It Happened to Work" Cases

🎯 Summary

How I Built the Editor and Compile Pipeline for a TypeScript DSA Visualizer (DSA View View 👀👀)

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

Why Try It?

📝 Designing DSA View View

🛡️ is-kit: Protecting the App from unknown Hell

✏️ Editor

Static TypeScript Analysis

Registering DSA Classes in the Editor

Formatting

📌 From the Compile Button to Verification

Transforming TypeScript with Babel

Extracting Function Signatures from the AST

Generating the Verification Form

🎯 Summary

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

Why Try It?

🖥️ What Is DSA View View?

🤔 What Can It Do?

🧑‍🏫 How to Use It

Editor

Verification

Runtime

Share 🐈

What Is That Thing in the Top-Right Corner? 👀👀

✏️ How Should We Study DSA?

Why TypeScript Instead of Python? 🐍

🎯 Conclusion

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

Why Try It?

Trying Declarative Partial Updates: A Future API for Replacing HTML Later

Declarative partial updates | Blog | Chrome for Developers

🧩 What are Declarative Partial Updates?

🤔 Why do we need Declarative Partial Updates?

🏠 This may expand what SPAs can do

🧪 APIs for streaming HTML from JavaScript are also coming

⚠️ “unsafe” does not mean “never use it”

➕ What happens when DPU and the streaming APIs are combined?

🚀 Trying it with Node.js DPU samples

nyaomaru / declarative-partial-updates-sample

Sample repository for DPU (Declarative Partial Updates)

Declarative Partial Updates sample

Run

🌓 Trying a hybrid shell style architecture

🎁 Trying Static / Streaming HTML APIs

🎯 Summary

References

The Difference Between satisfies, as, and Generics in TypeScript

🙏 as asks TypeScript to trust you

🔍 satisfies asks TypeScript to check the value

🎁 Generics encapsulate the check inside an API

Injecting `recordStep` into the AST

🖍️ `ExecutionStep`: Making Execution Replayable

Visualization Is Built from `ExecutionState`

🛡️ `is-kit`: Protecting the App from `unknown` Hell

Static `TypeScript` Analysis

Transforming `TypeScript` with Babel

🙏 `as` asks TypeScript to trust you

🔍 `satisfies` asks TypeScript to check the value

🤔 Thinking through `typedStruct`

🤔 Why use `is-kit`?

🤔 Why use `is-kit`?