DEV Community: nyaomaru

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:

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

Comments 3

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.

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:

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

Comments 7

5 min read

nyaomaru

Mar 25

Run Away From Work — Stopped Using React for the Game Loop

#showdev #gamedev #react #typescript

Comments 6

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 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

Comments 7

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 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

I Built a “Run Away From Work” Browser Game with React and TypeScript

nyaomaru — Wed, 18 Mar 2026 12:14:00 +0000

Click Game Button 👇

Hi there!

I’m @nyaomaru, a frontend engineer who got a cold after getting way too excited about spring and spending too much time in the sun. ☀️

Thanks to AI, we can get work done faster than ever and handle a huge number of tasks in parallel.

But at the same time… dealing with more and more work can get exhausting, right? 😿

So I made a small browser game about running away from work as a little break.

Here’s what it looks like 👇

👉 Play here

It runs in the browser, so you can play it on both desktop and mobile.

It takes about 1 minute to play.

Hope it gives you a small break 🙏

🎮 How to play

The controls are simple.

On desktop, press Space or Click to jump.

On mobile, just Tap.

You can even double jump, so try to dodge everything nicely.

Action	Description
Space / Click	Jump
Tap	Jump
Double Jump	Jump once more in the air

🐟 If you collect fish, something good might happen... maybe!!!???

🤔 Why I made this

There were two main reasons:

I wanted to study UI/UX
I wanted to see how far I could go using the technologies I’m already good at

I’m planning to get more serious about game development with Unity in the future, but before that, I wanted to try making a browser game with my current stack: React × TypeScript.

Also, do you know Google’s 404 Dinosaur T-Rex Game?

I’ve always liked how simple and fun it is.

That made me want to build my own fun little runner game.

That’s basically it.

⚙️ How I built it

I had previously built my portfolio with Remix × FSD, so this game was made as an extension of that idea.

https://dev.to/nyaomaru/building-a-portfolio-site-with-fsd-langchain-remix-ai-c9h

So the stack is basically:

Remix
React
TypeScript
FSD

Why this structure?

Games tend to have a lot of state, so I wanted to test how far I could manage things with hooks
I wanted the codebase to stay type-safe and maintainable
I wanted to test the scalability of FSD
I wanted to include it in my portfolio

I’ll probably write another article later about the detailed implementation, but these were my main impressions after building it:

FSD helped me clearly separate UI and model responsibilities
- That made it easier to add new features without affecting existing ones too much
I used is-kit to build user-defined type guards in a type-safe way
- Adding tests made the code more robust
Extracting magic numbers into constants made debugging much easier
- Separating config and constants helped me tune game-related values much more comfortably

By the way, is-kit is a small utility library for building type guards more easily. Feel free to check it out 😸

https://github.com/nyaomaru/is-kit

https://dev.to/nyaomaru/building-type-guards-like-lego-blocks-making-reusable-logic-with-is-kit-48e4

🤖 What it was like building a game with AI

In my daily work I usually use Claude Code, but for this experiment I decided to try building the game with codex.

While working on a browser game, I got the impression that this kind of UI is still pretty tricky for AI.

What was difficult 😅

For example:

When I asked it to create CSS animations, the result was often completely off
It couldn’t really think through things like hit detection
Sometimes the visual motion created through DOM manipulation did not match what I actually wanted

So I had to move forward while debugging and adjusting things manually.

In many cases, I could fix things by giving more specific instructions.

But for CSS animation and collision-related behavior, I often had to tweak things myself while watching how the game actually moved.

Because of that, my impression was:

it’s still difficult to leave UI/UX entirely to generative AI, especially when the interface is unusual.

Of course, for something like a standard CRUD UI, AI can already do a decent job because there are many common patterns. In real-world work, I usually don’t struggle that much. And if there’s already a mockup in Figma, the output can be quite accurate.

But for games or unfamiliar UI/UX, human adjustment is still very necessary.

That said, AI is evolving at absurd speed — faster than bamboo shoots grow.

So who knows what it’ll look like soon.

What worked well 🙌

Because this was a more unusual implementation, I tried to help codex learn from previous mistakes ahead of time.

To do that, I prepared a learn skill, along with AGENTS.md and LEARNED_INDEX.md so it could keep referring back to what had already gone wrong and how it had been fixed.

During development, whenever an instruction didn’t work well, I extracted the lesson and saved it into files. Then I made AGENTS.md load those references.

LEARNED_INDEX.md worked as a summary of those learned notes.

.codex/
  skills/
    learn/
      learned/
        xxx.md       # learned notes are stored here
        yyy.md
        zzz.md
    LEARNED_INDEX.md # index for referencing files under learned
    SKILL.md         # a skill for summarizing what went wrong in the session

This structure turned out to be really helpful for preserving instructions that normally wouldn’t appear in everyday development.

For example, things like:

“Use the boss idle bob phase relative to its spawn timing”
“Make the ground charge duration explicit so the attack timing becomes stable”
“Control the clear animation in phases to avoid timing conflicts”

These are small details, but they matter a lot, and I wanted them to stay consistent.

By repeating this process, I was able to reduce unnecessary correction instructions over time.

With this kind of setup, AI becomes much easier to work with even for personal projects with very specific requirements, which felt pretty nice.

Also, the learn skill was inspired by the learn commands from the everything-claude-code repository. Thx! 🙏

https://github.com/affaan-m/everything-claude-code/blob/main/commands/learn.md

🎯 Conclusion

This is a game where nyaomaru runs away from work on your behalf.

What happens in the end?
You’ll have to play it and find out.

There are two endings.

So go try it and see what kind of ending you get 😹

Repository

Game

https://github.com/nyaomaru/nyaomaru-portfolio

is-kit

https://github.com/nyaomaru/is-kit

Running a SPA inside ChatGPT using MCP Apps (Step-by-Step Guide)

nyaomaru — Mon, 02 Feb 2026 17:32:58 +0000

Hi there!

I’m @nyaomaru, a frontend engineer who still uses a hot water bottle in 2026.

A new era has arrived — you can now display and interact with your own web app directly inside the ChatGPT chat interface.

https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/

If you watch the video in the announcement, you’ll see what this looks like. A new common standard called MCP Apps has been released, allowing interactive UIs to run inside ChatGPT and Claude 🎉

In simple terms:
You can now run your own web app inside a chat, using an iframe.

As a developer, that’s something I definitely wanted to try myself.

In this article, I’ll walk through how to display your app inside ChatGPT step by step.

Let’s dive in.

What are MCP Apps?

MCP Apps provide a standardized way to deliver interactive UIs from MCP servers. Your UI renders inline in the conversation, in context, in any compliant host.

MCP Apps are a standard that allows AI hosts to display and interact with external web UIs.

Here’s the overall architecture:

In MCP Apps, your UI does not talk directly to your MCP server.
Instead, ChatGPT (the host) sits in the middle, fetching the UI and mediating all communication.

Docs:
https://modelcontextprotocol.github.io/ext-apps/api/documents/Overview.html

So what does this enable?

It allows ChatGPT or Claude to display a UI built with ext-apps, via an MCP Server.

⚠️ Important note:

Right now, the AI host must explicitly enable your app.
This is not something users can trigger just by typing a prompt. The host needs to have your MCP server configured.

Now, let’s go through how to build and publish this.

Publishing a UI using `ext-apps`

First, we need a web app to display.

If you don’t have one, the official examples are a great starting point:

https://github.com/modelcontextprotocol/ext-apps/tree/main/examples

https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/quickstart

I added MCP support to my experimental project nyaomaru 3D. Here’s the PR diff:

https://github.com/nyaomaru/nyaomaru-3D/pull/11/changes

This works fine in a monorepo too, but here I’ll assume the frontend and MCP server live in separate repositories.

Setup

Here’s the SPA we’ll use:

https://github.com/nyaomaru/nyaomaru-3D

Install ext-apps:

https://www.npmjs.com/package/@modelcontextprotocol/ext-apps

pnpm add @modelcontextprotocol/ext-apps

Since my app uses Vue + Vite, I also added:

pnpm add -D vite-plugin-singlefile

Next, create an HTML entry file for MCP (I called mine mcp-app.html):

https://github.com/nyaomaru/nyaomaru-3D/blob/main/mcp-app.html

Then create a bundle entry:

https://github.com/nyaomaru/nyaomaru-3D/blob/main/src/mcp-app.ts

My UI component looks like this:

import { App } from '@modelcontextprotocol/ext-apps';

// ...
const app = new App(
  {
    name: 'Nyaomaru MCP App',
    version: '0.1.0',
  },
  {},
  { autoResize: true },
);

onMounted(async () => {
  try {
    await app.connect();
    // ...
  } catch (error) {
    // ...
  }
});

onBeforeUnmount(() => {
  app.close();
});

The key part is app.connect() — this starts communication with the host (ChatGPT).
If you forget this, your UI won’t work inside ChatGPT.

Build config

I separated the MCP build output using a custom Vite mode:

export default defineConfig(({ mode }) => {
  const isMcpBuild = mode === 'mcp';

  return {
    plugins: [vue(), ...(isMcpBuild ? [viteSingleFile()] : [])],
    build: isMcpBuild
      ? {
          outDir: 'dist-mcp',
          emptyOutDir: true,
          rollupOptions: {
            input: fileURLToPath(new URL('mcp-app.html', import.meta.url)),
          },
        }
      : undefined,
  };
});

Add a script:

{
  "scripts": {
    "build:mcp": "vue-tsc -b && vite build --mode mcp"
  }
}

Deploy

Deploy the MCP build separately (I used Vercel):

Build Command: pnpm build:mcp
Output Directory: dist-mcp

https://{project-name}.vercel.app/mcp-app.html

If this page loads, your UI is ready.

Building the MCP Server

Now we create the MCP server that tells ChatGPT how to load our UI.

Here’s my example repo:

https://github.com/nyaomaru/nyaomaru-3D-mcp-ui

Install:

pnpm add @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk

Key parts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps/server';

// ...

const server = new McpServer({
  name: 'nyaomaru-3d-ui',
  version: '1.0.0',
});

registerAppTool(
  server,
  'open-nyaomaru-3d-ui',
  {
    title: 'Open Nyaomaru 3D UI',
    description: 'Render the Nyaomaru 3D MCP UI.',
    inputSchema: {},
    _meta: {
      ui: {
        resourceUri: RESOURCE_URI,
      },
    },
  },
  async () => {
    return {
      content: [
        {
          type: 'text',
          text: 'Opening Nyaomaru 3D UI...',
        },
      ],
    };
  },
);

registerAppResource(
  server,
  RESOURCE_URI,
  RESOURCE_URI,
  {
    mimeType: RESOURCE_MIME_TYPE,
  },
  async () => {
    const html = await fetchUiHtml();
    return {
      contents: [
        {
          uri: RESOURCE_URI,
          mimeType: RESOURCE_MIME_TYPE,
          text: html,
        },
      ],
    };
  },
);

Then expose via HTTP:

import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const app = express();
app.use(cors());
// ...

app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });
  res.on('close', () => {
    transport.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const port = Number(process.env.PORT ?? 3001);
app.listen(port, () => {
  console.log(`MCP UI server listening on http://localhost:${port}/mcp`);
});

Exposing the server with ngrok

ngrok http 3001

Copy the HTTPS URL.

Configuring ChatGPT

Open ChatGPT
Settings → Apps → Advanced → Enable Developer Mode
Create a new app
Enter your ngrok URL (e.g. https://xxx.ngrok-free.dev/mcp)
No auth
Save

Then enable the app in chat and ask ChatGPT to open it.

If everything worked — congrats! Your SPA is now running inside ChatGPT 🎉

Final thoughts

Seeing your own app running inside an AI chat interface feels like the future.

We’re moving from “AI responds with text” to “AI hosts applications.”

Right now, AI control over the iframe is limited, but this space is evolving fast.

If you build products, this could soon become a new way users interact with your services.

Definitely worth experimenting with now.

If you’re experimenting with MCP Apps too, I’d love to see what you build 👀

2025: I Shipped 3 OSS Projects — “This Was Actually Fine”

nyaomaru — Wed, 31 Dec 2025 06:08:20 +0000

Hi everyone!

I’m a frontend engineer, @nyaomaru.

Recently, for dieting purposes, I’ve been taking walks while carrying a backpack weighing over 10kg, kind of like Master Roshi’s (Kame-Sennin) training from Dragon Ball 🐢.

Another year flew by before I noticed it.

It’s already the end of the year.

At the end of the year, we have cleaning, shopping, and reflection.

In Japanese, December is called “Shiwasu(師走)”, meaning “even teachers run because they’re so busy.”

As for me, I’ve been running around so much that I feel like a completely worn-out rag.

Anyway, clean up this year’s mess within this year.

Let’s also organize our thoughts while we’re at it 🧹

So, I’d like to look back on 2025 from the perspective of OSS projects I released.

Just to be clear: there are no viral success stories here.

🎯 OSS Projects I Released in 2025

This year, I released the following three OSS projects:

is-kit

https://github.com/nyaomaru/is-kit

changelog-bot

https://github.com/nyaomaru/changelog-bot

divider

https://github.com/nyaomaru/divider

I continue maintaining and releasing updates for all of them.

🤔 Why Did I Build Them?

Simply put: because I wanted them myself.

is-kit: “There must be a cleaner way to write user-defined type guards…”
changelog-bot: “Writing CHANGELOG.md every time is honestly annoying…”
divider: “I just want to split strings more cleanly…”

Each project started from a small frustration.

I asked myself, “How can I remove this discomfort?” and started building.

Of course, it’s great when others use your OSS.
But my main focus was always: can this solve my own problem properly?

Let’s briefly look back at each project.

is-kit

If you use TypeScript, you probably write user-defined type guards fairly often.

For example:

type User = {
  id: string;
  age: number;
  role: 'admin' | 'guest' | 'trial';
};

A typical type guard might look like this:

function isUser(value: unknown): value is User {
  if (typeof value !== 'object' || value === null) return false;

  const record = value as Record<string, unknown>;
  return (
    typeof record.id === 'string' &&
    typeof record.age === 'number' &&
    (record.role === 'admin' ||
      record.role === 'guest' ||
      record.role === 'trial')
  );
}

I kept thinking: “Can’t this be simpler?”

That’s when the idea of LEGO blocks came to mind.
If we could compose small logical pieces, building complex type guards would be much easier.

So I designed is-kit around composable logic like and, or, and not.

With is-kit, the same example becomes:

import { struct, isString, isNumber, oneOfValues } from 'is-kit';

const isUser = struct<User>({
  id: isString,
  age: isNumber,
  role: oneOfValues('admin', 'guest', 'trial'),
});

More declarative, more readable, and still type-safe — sounds nice, right?

You can also compose guards further:

import { and, narrowKeyTo, predicateToRefine } from 'is-kit';

type AdminUser = Readonly<User> & { role: 'admin' };

const byRole = narrowKeyTo(isUser, 'role');
const isAdminUser = byRole('admin');

const isAdultAdmin = and(
  isAdminUser,
  predicateToRefine((user: AdminUser) => user.age >= 18)
);

What Worked Well with is-kit

A lot of people checked it out and gave it stars. Thank you so so so much 🙏🙏🙏

I also discovered tsd, a library for testing TypeScript type definitions, which was genuinely fun to work with.

The API stayed fairly simple, and overall, I’m happy with how it turned out.
There’s still room for improvement, so I’ll keep enhancing it.

Planned improvements include:

More primitive presets
More combinators
Improvements around struct

If you like it, feel free to give it a ⭐️!

https://github.com/nyaomaru/is-kit

The goal was never magic — just composability and readability.

changelog-bot

When you release an OSS project, you usually write release notes and update CHANGELOG.md.

But… it’s kind of a hassle, right?

At least, it was for me 🤮

There are tools that generate changelogs from conventional commits, but I wondered:

“Could AI classify changes based on content instead?”

That question led to changelog-bot.

You can use it via CLI with OpenAI or Anthropic API keys (AI is optional):

It’s mainly designed to run in CI.
Once a release is published, your CHANGELOG.md can be updated automatically.

name: Update Changelog

on:
  release:
    types: [published]

jobs:
  changelog:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: nyaomaru/changelog-bot@v0
        with:
          changelog-path: CHANGELOG.md
          base-branch: main
          provider: openai
          release-tag: ${{ github.event.release.tag_name }}
          release-name: ${{ github.event.release.tag_name }}
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You can also run it locally via CLI if you want. Details are in the README.

What Worked Well with changelog-bot

It completely removed the manual effort of maintaining CHANGELOG.md for my projects.
Releasing became much easier 🚀

I personally enjoyed designing the preprocessing logic that extracts and scores features before passing data to the AI.

That said, there’s still room for improvement, and contributions are welcome!

One note though:

Writing changelogs became easier. But... life itself didn’t magically become easier.

That part is still under observation.

https://github.com/nyaomaru/changelog-bot

divider

Sometimes you end up slicing strings over and over with substring, and it gets messy.

I wanted a cleaner way.

So I built divider, which lets you split strings in one shot using indices.

import { divider } from '@nyaomaru/divider';

const [a, b, c] = divider(text, 3, 6);

What I Learned from divider

A great engineer contributed, I’m truly grateful 🙏

More importantly, I learned the basics of OSS hygiene:
CODE_OF_CONDUCT.md, CONTRIBUTING.md, CHANGELOG.md, DEVELOPER.md, etc.

However, there was a clear downside.

I couldn’t demonstrate a strong advantage over string.split().

That’s reflected in the number of stars, and honestly, it was a design mistake.

In short, this project was a “useful failure.”

Still, it was a valuable learning experience, and I’m glad I built it.

https://github.com/nyaomaru/divider

✨ Goals for 2026

In 2025, I:

Released OSS projects
Started writing technical articles
Moved to the Netherlands 🇳🇱

It was a year full of new challenges.

For 2026, I’m thinking about:

Releasing OSS applications related to DSA
Publishing a small game project

But above all, my main goal is simple:

Don’t burn out. Keep going. 🏃‍♂️

That applies to OSS, systems, and life itself.

Thank you for reading, and I hope you have a great year ahead.

See you in 2026 🐈

I Tried Reading React's Source Code and Flow Beat Me Up. So Let's Learn 🚀

nyaomaru — Sun, 14 Dec 2025 06:09:03 +0000

Hi everyone!

I'm @nyaomaru, a frontend engineer who eats too much cheese 🧀 and is slowly gaining weight.

Quick detour: this article says that to become a good engineer, you need a deep understanding of code, and that reading existing code is essential:

https://dev.to/thebitforge/10-developer-habits-that-separate-good-programmers-from-great-ones-293n

I totally agree.

So I started doing a deep reading of React's source code.

And honestly?

It’s been surprisingly fun.

Every day I discover something new, like:

“Oh, memo bails out when there’s no Fiber + props/state update!”
“Wait, <Activity> in v19.2 is wrapped with Offscreen and switches behavior by mode?”
“They use bit flags instead of booleans… no wonder it’s fast even with complex state!”

If you have some free time during the holidays, I highly recommend trying it.
How about “React deep reading without giving up” for New Year’s Eve?

…just a thought.

But then… Flow happened 😇

As I kept reading, I hit a wall.

I’m used to reading TypeScript, but React’s core is written in Flow, and there are many places where Flow’s type system behaves differently.

Honestly, I almost gave up.

“Wait… is this syntax? a type? a comment?
…a spell?”

My brain felt like it was being beaten up physically.

So I decided to write this article with one goal:

Understand Flow’s quirks quickly, and lower the barrier to reading React’s source code.

This article is for:

People who want to read React’s source code more deeply
People who’ve heard of Flow, but never really understood it

Alright, let’s dive in!

🌊 What is Flow?

First, let’s clarify what Flow actually is.

https://flow.org/

Flow is a static type checker for JavaScript.

At first glance it feels similar to TypeScript, but the philosophy is different:
Flow is much closer to a pure type system.

Flow has been developed by Meta (formerly Facebook) alongside React itself, so React’s core type definitions are deeply written in Flow.

The key point is this:

Flow adds type safety on top of JavaScript.

It does not extend JavaScript with new language features like TypeScript does.

That difference matters a lot when you read React’s internals.

🧩 Why should we learn Flow?

If you read React’s source code, you’ll constantly encounter Flow types in core concepts like:

Suspense
Fiber
Lanes
Offscreen

Especially tricky concepts include:

variance (covariant / contravariant / invariant)
maybe (?T)
mixed / empty
exact objects

Many of these aren't the same meanings in TypeScript.

Without Flow knowledge, you’ll often stop and wonder:

“Is this a type? syntax? or some utility?”

That friction adds up and makes reading slower — and easier to give up.

Once you understand Flow, React’s source code suddenly becomes much more readable.

⚔️ Flow vs TypeScript (quick comparison)

Aspect	Flow	TypeScript
Primary goal	Static type checking	Static types + language extensions
Strictness	Stricter / theory-oriented	Practical / sometimes permissive
Notable features	`Exact Object`, `variance`, `opaque types`	Rich unions, enums
React core	Written in Flow	Apps mostly written in TypeScript
Learning benefit	Understand React internals	Best for app development

👉 Flow is NOT “the origin of TypeScript.”

They evolved on different paths, with different goals.

🌀 Flow Types We’ll Focus On

We’ll skip the basics that feel similar to TypeScript, like:

Primitive types
Literal types
Functions
Utilities

Instead, we’ll focus on Flow types that often confuse people when reading React:

mixed
empty
maybe
opaque
exact / inexact objects

(There are many more — check the official docs if you’re curious!)

For variance, see this article:
https://dev.to/nyaomaru/understanding-variance-in-typescript-flow-covariant-contravariant-invariant-bivariant-4fbi

🌪️ Understanding `mixed`

Let’s start with mixed.

In Flow, mixed is very similar to TypeScript’s unknown.

You’ll see it in React when:

handling errors
dealing with callbacks
accepting “anything, but safely”

`mixed` is the safest “anything”

From a type theory perspective, mixed is a top type.

It means:

“Any value can be here, but you’re not allowed to use it until you prove what it is.”

Unlike TypeScript’s any, which says “do whatever you want,”

mixed says: “Show me the type first.”

function numberOrString(x: mixed) {
  // x + 1;   // ❌ error
  // x.name; // ❌ error

  if (typeof x === 'number') {
    return x + 1; // ✅ OK
  }
}

You must narrow before using it.

This prevents bugs caused by casually handling unknown values.

If you know unknown in TypeScript, this should feel very familiar.

🕳️ Understanding empty

Next up: empty.
(Don’t worry — not talking about my bank account.)

empty represents the bottom type in Flow.

empty means “this value can never exist”

Literally:

“There is no possible value of this type.”

Not number, not string, not null — nothing.

This is very close to TypeScript’s never.

function foo(x: empty): empty {
  return x; // type-checks, but can never be called
}

This function is logically unreachable.

Flow often uses empty to represent impossible states.

Why is this useful?

Example: unreachable branches.

function bar(x: string) {
  if (typeof x === 'number') {
    return x; // ❌ unreachable → inferred as empty
  }
}

Or functions that never return:

function throwError(message: string): empty {
  throw new Error(message);
}

Or exhaustive checks:

function voice(value: 'cat' | 'dog'): string {
  switch (value) {
    case 'cat':
      return 'meow';
    case 'dog':
      return 'bow';
    default:
      return (value: empty);
  }
}

If you forget a case, Flow will complain — at compile time.

🌫️ Understanding `maybe` (`?T`)

Flow’s maybe type is written as ?T.

It means:

T | null | undefined;

Much shorter, right?

function greet(name: ?string) {
  if (name != null) {
    return 'Hello, ' + name.toUpperCase();
  }
  return 'Hello!';
}

Using != null is intentional here — it safely removes both null and undefined.

🕶️ Understanding `opaque` types

Now for one of Flow’s most stylish features: opaque types.

Normally, if two types share the same structure, they’re interchangeable.

Flow lets you say:

“They look the same — but they are NOT the same.”

TypeScript alias example

type UserId = string;
type PostId = string;

const user: UserId = 'aaa';
const post: PostId = user; // allowed

Aliases are just aliases.

Flow opaque types

opaque type UserId = string;
opaque type PostId = string;

Locally they look similar — but export them, and things change.

export opaque type UserId = string;

Outside the module, UserId becomes truly opaque.

You cannot forge it.

This gives Flow true nominal typing.

TypeScript’s branded types are similar — but can be bypassed with casts.
Flow’s opaque types cannot be forged outside the module.

That’s why they’re so powerful.

🧩 Exact vs Inexact Objects

This is not a personality test.

Flow objects come in two flavors:

Exact (default) — strict
Inexact (...) — permissive

Inexact

type User = {
  name: string,
  ...
};

const user: User = {
  name: 'nyaomaru',
  age: 123, // OK
};

Extra properties are allowed.

Exact (default)

type User = {
  name: string,
};

const user: User = {
  name: 'nyaomaru',
  age: 123, // ❌ error
};

Even passing through variables won’t bypass this.

This strictness prevents accidental object pollution — something TypeScript allows in some cases.

🏁 Final Thoughts

Once you understand:

mixed
empty
maybe
opaque
exact / inexact

React’s source code stops looking like magic spells.

You start thinking:

“Ah — that’s why they typed it this way.”

So grab some noodles (or pasta 🍝), and try reading React’s source code again.

Happy holidays, and happy hacking!

Bonus

You can try to use flow in below playground 🚀

https://github.com/nyaomaru/flow-playground

Please check my OSS for building type guards easily: is-kit 😸

https://github.com/nyaomaru/is-kit

Generate CHANGELOG.md Automatically 🤖

nyaomaru — Sun, 30 Nov 2025 13:15:01 +0000

Hey everyone! Happy winter is upcoming! ⛄️

I’m @nyaomaru, a frontend engineer.

Today I’d like to introduce changelog-bot, a tool that automatically generates a polished CHANGELOG.md from your release notes! 🚀

🧪 Background

If you’re maintaining a project, you’ve probably used CHANGELOG.md to keep track of release details.
But let’s be honest—updating it manually with every version bump is tedious.

Sure, you can automate parts of it, but most generators produce unstructured or messy output.
That’s exactly the pain point that inspired changelog-bot!

https://github.com/nyaomaru/changelog-bot

🎁 Why changelog-bot?

🖋 Automates the boring part — generating CHANGELOG.md
- Uses AI to structure and format the changelog with high accuracy
- Analyzes commit messages and PR titles to automatically categorize “fix”, “feat”, etc.
Works directly from release notes
- No need for strict Conventional Commit rules
Works even without AI
- Fallback logic builds changelogs accurately even without an API key

🔎 How to Use It

Try it instantly (npx / pnpx)

The easiest way to try it out is from the CLI using npx or pnpm dlx!

pnpm

pnpm dlx @nyaomaru/changelog-bot \
  --release-tag v0.0.1 \
  --provider openai \
  --dry-run

💡 Tip: Remove --dry-run to actually create a PR with your updated CHANGELOG.md!

If you want to enable AI-assisted formatting, set your API key beforehand:

For security reasons, .env files are not automatically loaded.
Please export your environment variables manually.

# For OpenAI users
export OPENAI_API_KEY=sk-xxxx   # Use OpenAI as the provider
export OPENAI_MODEL=gpt-4o-mini # Optional: specify a model

# For Anthropic users
export ANTHROPIC_API_KEY=sk-ant-xxxx
export ANTHROPIC_MODEL=claude-3-5-sonnet-20240620

Setting up a local dev environment with mise

If you’d like to explore the source or contribute, set up Node and pnpm with mise:

mise install     # Installs Node 22 / pnpm 10.12
mise dev_install # Installs dependencies
mise build       # Compiles TypeScript

Then, export your environment variables:

export REPO_FULL_NAME=your_name/your_repository_name # Target repository
export GITHUB_TOKEN=ghp_xxx                          # GitHub token
export OPENAI_API_KEY=sk-xxx                         # Optional: for AI formatting

Finally, just run the CLI — make sure to set your version properly!

mise start \
 --release-tag v0.0.1 \
 --provider openai \
 --dry-run

💡 Tip: Remove --dry-run to apply changes to your CHANGELOG.md via PR!

If no API key is provided, it falls back to commit log analysis
You can swap models by setting OPENAI_MODEL or ANTHROPIC_MODEL

Automate with GitHub Actions

Even easier—let GitHub Actions handle it.
Just drop a workflow like this under .github/workflows/ and your changelog will grow automatically whenever a release tag is pushed:

name: Auto Changelog

on:
  workflow_dispatch:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    uses: nyaomaru/changelog-bot/.github/workflows/changelog.yaml@v0
    with:
      changelog_path: CHANGELOG.md
      provider: openai
      release_tag: ${{ github.ref_name }}
      dry_run: 'false'
    secrets:
      REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

If you don’t want to expose AI keys, you can set dry_run: 'true' to post a draft changelog as a PR comment instead.

🌱 Distribution & Ecosystem

Available as an npm/pnpm CLI package (@nyaomaru/changelog-bot)
Also usable as a GitHub Action via the included action.yml
The fallback logic doesn’t require Conventional Commits — easy to drop into any repo
Issues and PRs are always welcome! Templates are ready, so feel free to leave feedback 😹

Future Plans

Support for local LLMs as changelog classifiers
Multi-language changelog output
Improved accuracy via preprocessing and better prompts

🎯 Summary

changelog-bot is both a CLI and a GitHub Action that automatically generates CHANGELOG.md whenever a release is triggered.

👉 https://github.com/nyaomaru/changelog-bot

If you like it, don’t forget to leave a 🌟 — it keeps me going! 😻

Bonus

I’ve also released another OSS project called is-kit — a utility for building powerful isXXX type guards in TypeScript.

https://github.com/nyaomaru/is-kit

Check out the related articles:

🧠 Understanding Variance in TypeScript & Flow: Covariant, Contravariant, Invariant, Bivariant

nyaomaru — Wed, 26 Nov 2025 05:46:26 +0000

Hi everyone!

I’m @nyaomaru, a frontend engineer who quietly moved to the Netherlands. 🇳🇱

If you write TypeScript, you’ve probably bumped into the term “variance” at some point:

covariant
contravariant
invariant
bivariant

You may have a vague feeling of “I sorta get it… but not really.”

Personally, I struggled especially with contravariance and bivariance — they’re really counter-intuitive.

And when I tried to deep-read React’s type definitions, I ran into Flow’s variance annotations +T / -T and completely froze:

export type Element<+C> = React$Element<C>;
export type RefSetter<-I> = React$RefSetter<I>;

“What are + and -!?”
“Why is React using this in Flow!?”

That was the entrance to understand variance for me.

In this article, I’ll use both TypeScript and Flow to build a practical, real-world understanding of variance:

You want to read React’s type definitions without crying 😿
You want to design safe callback types in TypeScript
You want to avoid the bivariant foot-guns

Let’s dive in 👇

Note
I won’t do a full Flow tutorial here. I’ll only touch Flow enough to explain how it expresses variance.

🧩 What is type variance?

“Type variance” is about generic types and function types, and:

how the subtype relationship between type parameters propagates to the outer type

For example, suppose Cat is a subtype of Animal (Cat <: Animal):

Then is List<Cat> also a subtype of List<Animal>?
Can we use Handler<Animal> where a Handler<Cat> is expected?
What about something mutable like Box<T>?

Variance is the set of rules that determines these “generic subtype” relationships.

There are four basic flavors:

Covariant
- Subtype relationship goes in the same direction
Contravariant
- Subtype relationship goes in the opposite direction
Invariant
- No subtype relationship either way
Bivariant
- Both directions are allowed (TypeScript foot-gun)

These are not specific to TypeScript — you’ll find them in Java, C#, Kotlin, Flow, and pretty much any typed language that has generics.

Let’s go through them one by one.

⬆️ Covariant: “If child is OK, using it as parent is also OK”

Given Cat <: Animal, covariance is:

Covariant: F<Cat> <: F<Animal>

Roughly: a “container of more specific things” can be used where a “container of more general things” is expected.

This is typically used for read-only types.

class Animal {
  name = 'animal';
}
class Cat extends Animal {
  meow() {}
}

type ReadonlyBox<T> = {
  readonly value: T;
};

const catBox: ReadonlyBox<Cat> = {
  value: new Cat(),
};

// Using "box of Cat" as "box of Animal" is fine
const animalBox: ReadonlyBox<Animal> = catBox;

// Reading as Animal is always safe
// animalBox.value.meow(); // Type error: Animal doesn't have meow()

Here we only read from the box, so it’s safe to treat a ReadonlyBox<Cat> as a ReadonlyBox<Animal>. That’s covariance.

Top: Cat → Animal (usual subtype relation)
Bottom: ReadonlyBox<Cat> → ReadonlyBox<Animal> (same direction → covariant)

⬇️ Contravariant: “If parent is OK, you can use it in a child-only slot”

Again with Cat <: Animal, contravariance is:

Contravariant: F<Animal> <: F<Cat>

The idea is:

A function that can handle a wider type can safely be used wherever a narrower type handler is required.

This comes up with function parameter types (i.e., “write-only” positions).

class Animal {
  name = 'animal';
}
class Cat extends Animal {
  meow() {}
}

type Handler<T> = (value: T) => void;

const handleAnimal: Handler<Animal> = (animal: Animal) => {
  console.log(animal.name);
};

const handleCat: Handler<Cat> = (cat: Cat) => {
  cat.meow();
};

// Safe with contravariance:
// A handler that accepts any Animal can be used as a Cat-specific handler
const catHandler: Handler<Cat> = handleAnimal; // OK (in theory)

// The opposite is unsafe: a Cat-only handler
// cannot safely handle all Animals (Dog, Bird, ...)
// const animalHandler: Handler<Animal> = handleCat; // Should be an error

Handler<Animal> can handle any animal (including Cat), so it’s safe to use where a “Cat handler” is expected.

The reverse is not safe → that’s contravariance.

Top: Cat → Animal
Bottom: Handler<Animal> → Handler<Cat> (reverse direction → contravariant)

⛔ Invariant: “No subtyping either way”

Even if Cat <: Animal , with invariance:

Invariant: F<Cat> and F<Animal> have no subtype relation

class Animal {
  name = 'animal';
}
class Cat extends Animal {
  meow() {}
}

type Box<T> = {
  value: T;
};

let animalBox: Box<Animal> = { value: new Animal() };
let catBox: Box<Cat> = { value: new Cat() };

// Both of these are theoretically unsafe:
//
// animalBox = catBox;
// catBox = animalBox;

Why?

If you treat Box<Cat> as Box<Animal>:
- You could write a plain Animal into it
- But someone else might assume it still only contains Cat
If you treat Box<Animal> as Box<Cat>:
- You might pull an Animal from it and assume it’s always a Cat

Since it’s mutable and used for both read and write, the safe option is:

Make it invariant (no subtyping).

In pure type theory we’d reject both assignments.

In practice, TypeScript treats most generics as approximately covariant, so Box<Cat> → Box<Animal> may compile — but conceptually, Box<T> should be invariant.

Top: Cat → Animal
Bottom: no arrow between Box<Cat> and Box<Animal> → invariant

🔁 Bivariant: “Both directions are OK (and that’s exactly the problem)” — TypeScript’s hole

Given Cat <: Animal, bivariance is:

Bivariant: F<Cat> and F<Animal> are mutually assignable

So it’s like “covariant + contravariant at the same time”.
From a soundness standpoint, this is pretty much always a bad idea.

But TypeScript allows it in some cases (esp. some callback parameter types) for JavaScript compatibility.

type EventHandler<T> = (event: T) => void;

declare let handleEvent: EventHandler<Event>;
declare let handleMouse: EventHandler<MouseEvent>;

// In sound type theory, only one of these would be allowed (depending on design).
// In TypeScript, *both* can be allowed in certain contexts (bivariant).
handleEvent = handleMouse; // OK in some cases (but can be unsafe)
handleMouse = handleEvent; // Also OK

MouseEvent is a subtype of Event
If both directions are allowed, you can pass the “wrong” handler
TypeScript chooses practicality over strict safety here

Top: MouseEvent → Event
Bottom: Handler<MouseEvent> ⇔ Handler<Event> → bivariant

🎯 Quick summary of the four

Kind	Direction	Safety	Typical example
Covariant	Child → Parent	Safe for reads	`readonly T[]`, `ReadonlyArray<T>`
Contravariant	Parent → Child	Safe for writes	`(arg: T) => void`, handlers
Invariant	No subtyping	Safe for mutable	`Box<T>`
Bivariant	Both directions	Unsound / risky	Some TS callback parameter positions

⚙️ `TypeScript`’s reality vs. “pure” type theory

So far we’ve been in the “beautiful, clean theory world”:

Read-only → covariant
Write-only (function parameters) → contravariant
Mutable read + write → invariant
Both directions → unsound (bivariant)

But TypeScript does not fully implement this ideal.

Because of:

Historical JavaScript APIs
Massive existing JavaScript codebases
Browser / DOM APIs design

TypeScript makes several pragmatic compromises:

T[] arrays are treated as covariant, even though they should be invariant
Function parameter positions are often bivariant, not strict contravariant

This mismatch between type theory intuition and TS behavior is where a lot of confusion comes from.

Let’s look at the two big ones.

Arrays: should be invariant, but TS treats them as “basically covariant”

Formally:

T[] should really be invariant
but TypeScript treats it as if it were covariant

Which means some unsafe code compiles.

class Animal {
  name = 'animal';
}
class Cat extends Animal {
  meow() {}
}
class Dog extends Animal {
  bark() {}
}

const cats: Cat[] = [new Cat()];

// TS treats Cat[] as a subtype of Animal[]
const animals: Animal[] = cats;

// Now this is allowed:
animals.push(new Dog());

// But the underlying array is still "cats"
const cat: Cat = cats[1]; // Type says Cat, but it's actually a Dog
cat.meow(); // Possible runtime error

Why does TS allow this?

From a type theory perspective, T[] is a mutable container → should be invariant
But JavaScript’s arrays are extremely flexible and historically treated loosely
Making T[] strictly invariant would break a lot of existing JavaScript code

So TypeScript chose to keep T[] almost covariant.

The recommended alternative is read-only arrays:

const cats: readonly Cat[] = [new Cat()];
const animals: readonly Animal[] = cats; // Safe

Because we only read from a readonly array, it can be safely covariant.

In practice: most generics in TS behave “mostly covariant”.
The real danger is specifically “mutable but treated as covariant”, like T[].

Function parameters: should be contravariant, but often behave bivariantly

The second big compromise: function parameter variance.

In theory:

Function parameter positions should be contravariant.

In practice, TypeScript often treats them as bivariant, especially in:

Methods in object types
Some callback positions
When strictFunctionTypes is disabled

Let’s see why that’s a problem.

Why should parameters be contravariant?

type Handler<T> = (value: T) => void;

Here, T is used in parameter position:

It’s on the “receiving data” side
Which means it should be contravariant

If Cat <: Animal, then (in theory):

Handler<Animal> <: Handler<Cat>

We’ve already seen this pattern.

But TS sometimes allows both directions (bivariant)

To maintain compatibility with existing JavaScript, TS allows both directions in many callback cases:

type Handler<T> = (value: T) => void;

declare let handleEvent: Handler<Event>;
declare let handleMouse: Handler<MouseEvent>;

// In some contexts, TS allows:
handleEvent = handleMouse; // OK
handleMouse = handleEvent; // OK

With a purely sound type system, one of these would be rejected.
TS chooses convenience over strict safety.

Consider this more dangerous version:

type Handler<T> = (value: T) => void;

const handleEvent: Handler<Event> = (event) => {
  console.log(event.type);
};

const handleMouse: Handler<MouseEvent> = (event) => {
  // MouseEvent-specific API
  console.log(event.clientX);
};

// Assign MouseEvent handler to a generic Event handler
const eventHandler: Handler<Event> = handleMouse;

// This is allowed by the type system:
eventHandler(new Event('click')); // Runtime error: no clientX

This should be a type error, but bivariant behavior lets it through.

Why did the TS team do this?

Because real-world JavaScript:

Doesn’t assume strict contravariance
Has tons of “loosely typed” callback APIs (DOM, Node.js, libraries, …)
Would break massively if TS suddenly enforced full contravariance

So the TS team made a pragmatic choice:

Prioritize developer experience and compatibility
over 100% soundness.

What about `strictFunctionTypes`?

There is a partial escape hatch:

{
  "compilerOptions": {
    "strict": true,
    "strictFunctionTypes": true
  }
}

With strictFunctionTypes: true:

Standalone function types are treated more contravariantly
Methods in object types are still treated more loosely (bivariantly) for compatibility

So even in strict mode, you don’t get “perfect” contravariance — but you get closer.

🎯 Takeaway: `TypeScript` is not a “pure variance lab”

To summarize:

Arrays T[] should be invariant → TS treats them as almost covariant
Function parameters should be contravariant → TS often treats them as bivariant
strictFunctionTypes helps, but doesn’t give you fully sound variance

So TypeScript is:

not a perfectly sound type theory playground,
but a pragmatic type system sitting on top of messy real-world JavaScript.

Variance in TS is “good enough” most of the time, but you should be aware of where it leaks.

🌊 How Flow expresses variance explicitly

Quick recap: Flow is a static type checker for JavaScript, originally developed at Facebook (now Meta).

Key characteristics:

More strict and soundness-oriented than TS
Variance is explicitly annotated
Strong type inference
Type annotations layered onto plain JS

In very rough terms:

TypeScript focuses on practicality
Flow focuses more on safety

One of Flow’s signature features is explicit variance annotations.

Variance annotations in Flow

In Flow, you write variance directly on type parameters:

Syntax	Meaning
`+T`	covariant
`-T`	contravariant
`T`	invariant(no sign)

So in Flow, the author of a type explicitly declares:

“This type parameter is used covariantly / contravariantly / invariantly.”

In TypeScript, the compiler mostly infers this.
In Flow, you annotate it, and Flow checks that your usage matches.

⚛️ How React uses variance in Flow types

React’s internal types were historically written in Flow, and you can still see traces of it:

export type Element<+C> = React$Element<C>;
export type RefSetter<-I> = React$RefSetter<I>;

+C is covariant
-I is contravariant

Why is Element<+C> covariant?

Because ReactElement is essentially immutable:

You construct it
You read from it
You don’t mutate its props in place

So it’s safe to say that if CatProps <: AnimalProps, then:

ReactElement<CatProps> <: ReactElement<AnimalProps>

Example:

type AnimalProps = { name: string };
type CatProps = { name: string; meow: () => void };

function Cat(props: CatProps) {
  return null as any;
}

const catElement: ReactElement<CatProps> = (
  <Cat name="nyaomaru" meow={() => {}} />
);

// Because of covariance, this is safe:
const parent: ReactElement<AnimalProps> = catElement;

A component that accepts “more specific props” can be used where “more general props” are expected
The element is read-only — we’re not mutating its props through this type

Why is RefSetter<-I> contravariant?

Because RefSetter receives values (instances) — it doesn’t produce them:

It’s on the “write side”
That’s a contravariant position

Example:

type HTMLDivRef = (el: HTMLDivElement | null) => void;
type HTMLElementRef = (el: HTMLElement | null) => void;

We have HTMLDivElement <: HTMLElement, and with contravariance:

RefSetter<HTMLElement> <: RefSetter<HTMLDivElement>

So:

A callback that can handle any HTMLElement can safely be used where a “div-only” ref setter is expected
But the opposite is unsafe: a HTMLDivElement-only ref setter cannot safely accept any HTMLElement

This matches exactly our earlier Handler<T> examples.

Why this matters for reading React’s types

Once you understand Flow’s variance annotations:

+C(covariant) on ReactElement<+C> → safe, immutable, read-only
-T (contravariant) on RefSetter<-T> → callback parameter, write-only
No sign → invariant types where mutation may happen

This makes React’s Flow types much easier to reason about.

🛠️ Where variance actually matters in real code

This may still feel theoretical, but it absolutely shows up in day-to-day work:

onClick, onChange, onSubmit → UI event handlers
onSuccess, onError → async/API callbacks
Exposed “handler” or “listener” APIs in your own libraries

All of these are basically:

type Handler<T> = (value: T) => void;

So:

Parameter types → contravariant
Return types → covariant
Mutable containers → invariant
TS callback parameters in methods → often bivariant

When designing public APIs:

Prefer wider types for parameters your consumers pass in
Avoid exposing raw mutable containers like Box<T> when a ReadonlyBox<T> will do
Consider using readonly arrays and properties when you can

In other words:

Variance is a mental checklist for API design, not something you only care about in textbooks.

📌 Wrap-up

We covered a lot, so let’s distill the main points:

Variance determines how subtyping of type parameters affects the outer type:
- Covariant → same direction (usually read-only)
- Contravariant → opposite direction (usually function parameters)
- Invariant → no subtyping either way (mutable containers)
- Bivariant → both directions (convenient but unsound)
TypeScript:
- Treats many generics as “mostly covariant”
- Makes T[] effectively covariant (even though it should be invariant)
- Often treats function parameters as bivariant
- Provides strictFunctionTypes to tighten some of this
Flow:
- Has explicit variance annotations (+T, -T, T)
Practically:
- readonly vs mutable is a variance decision
- Callback parameter types are a variance decision
- Whether you expose Box<T> or ReadonlyBox<T> is a variance decision

You don’t need to memorize all the formal rules,
but keeping “covariant / contravariant / invariant / bivariant” in your mental toolbox makes both reading library types and designing your own APIs much easier.

I also made a small repo where you can play with these variance patterns in TypeScript:

👉 https://github.com/nyaomaru/variance-check

Have a nice variance life 🐈‍⬛✨

References

https://en.wikipedia.org/wiki/Type_variance

https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations

https://www.totaltypescript.com/method-shorthand-syntax-considered-harmful

https://www.sandromaglione.com/articles/covariant-contravariant-and-invariant-in-typescript

https://zenn.dev/jay_es/articles/2024-02-13-typescript-variance

https://typescriptbook.jp/reference/generics/variance

https://effectivetypescript.com/2021/05/06/unsoundness/

🐾 Shameless plug

When you write TypeScript, you probably end up writing isXXX guards over and over.
It’s boring and error-prone, so I built a small OSS library to help:

👉 is-kit: a tiny toolkit for building composable, type-safe type guards

https://github.com/nyaomaru/is-kit

If you’re curious, I also wrote about it here:

https://dev.to/nyaomaru/build-isxxx-the-easy-way-meet-is-kit-2hpl

https://dev.to/nyaomaru/building-type-guards-like-lego-blocks-making-reusable-logic-with-is-kit-48e4

https://dev.to/nyaomaru/escaping-the-forest-of-if-statements-building-logical-type-guards-with-is-kit-2db3

DEV Community: nyaomaru

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

🎯 TL;DR

🌓 Two families of OpenAPI codegen tools

🏎️ Generation speed

Why openapi-typescript is so fast

Why Kubb is slower

Orval was faster than I expected

🗺️ Output size

openapi-typescript

hey-api

Orval

Kubb

🧪 Calling the same endpoint

openapi-typescript

hey-api

Orval

Kubb

🖇️ Path params and body arguments

GET by id

POST body

💭 Function signature philosophy

⚠️ Error model

Result union in openapi-typescript and hey-api

Orval's default fetch behavior needs attention

Kubb's throw model

✅ Authentication and interceptors

openapi-fetch

hey-api

Orval

Kubb

🪛 TanStack Query, Zod, MSW, and Faker

🤯 Enum issue: drf-spectacular BlankEnum

Generated BlankEnum

What happens after anyOf composition

🥗 Body type reusability

🚪 Lint behavior

openapi-typescript / hey-api / Orval lint errors

Kubb lint errors

📝 Configuration notes

openapi-typescript

hey-api

Orval

Kubb

🗨️ My impression of openapi-typescript

🗨️ My impression of hey-api

🗨️ My impression of Orval

🗨️ My impression of Kubb

📓 Summary table

🤔 How I would choose

1. Start with openapi-typescript

2. Move to hey-api when SDK functions become useful

3. Use Orval when OpenAPI becomes the source of frontend assets

4. Choose Kubb when you love the architecture

🚀 Final conclusion

Why I Didn’t Let AI Handle My Scroll Animation: Astro, React, and TypeScript Architecture

Necoz | Software Development Studio in Amsterdam

nyaomaru / necoz

Official Necoz B.V. website with custom scroll animations.

necoz

Project Structure

🤔 Why I did not use AI-generated animation as-is

🧑‍🚀 Why Astro?

⚖️ I used React, but not for everything

🌊 Animation is controlled by TypeScript, not React state

💎 Why I did not avoid direct DOM manipulation

Building a Browser Game with React: What Doesn’t work well (Run Away From Work)

😿 Responsive design was not only a CSS problem

📏 Why I used virtual scroll

🤖 Where AI was useful

💖 What I learned from this architecture

🎯 Summary

Handling `unknown` in TypeScript… isn't it painful?

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

🤔 Why use is-kit?

A simple example

🐾 How is-kit has evolved

🪄 1. Distinguishing “missing” vs “undefined” in struct

🤔 Why use `is-kit`?

🐾 How `is-kit` has evolved

🪄 1. Distinguishing “missing” vs “undefined” in `struct`

🔑 2. Key-based narrowing (`hasKey`, `hasKeys`, `narrowKeyTo`)

🧪 3. `assert` for fail-fast validation

✨ 4. Support for `Set` and `Map`

🤔 Why use `is-kit`?