DEV Community: nyaomaru

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

Escaping the Forest of if Statements🌲: Building Logical Type Guards with `is-kit`

nyaomaru — Sun, 09 Nov 2025 10:11:05 +0000

Hey everyone 👋
I’m @nyaomaru, a frontend engineer who stays warm every day by practicing sumo squats 🥶💪

Have you ever written complex TypeScript code where type guards get tangled up inside a forest of nested if statements?

Today, let’s explore how to escape that forest by composing type guards logically with the open-source library is-kit.

Let’s dive in together!

🧠 The Philosophy of and, or, and not

is-kit provides composable logical operators for type guards:

and: all conditions must be true (intersection)
or: at least one condition must be true (union)
not: negates a condition (negation)

These operators keep both runtime checks and TypeScript narrowing intact.
In other words, they turn type guards into a mini-DSL (domain-specific language) for expressing logic in plain English.

🌲 The Forest of if Statements

When type guards pile up, your if statements tend to nest endlessly:

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

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')
  );
}

if (isUser(x)) {
  if (x.age >= 20 && x.role === 'admin') {
    // Admin, age 20+
  } else if (x.role === 'guest' || x.role === 'trial') {
    // Guest or trial user
  }
}

We’ve all been there, a jungle of nested conditions 🌳🌳🌳

🏗️ Defining a Base Guard with `struct`

Let’s rewrite the User guard declaratively using struct.
Once you have this base guard, composing logic becomes a breeze.

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

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

// struct infers readonly properties; effectively Readonly<User>
// This preserves structural type safety and helps prevent breaking changes in practice.
const isUser = struct({
  id: isString,
  age: isNumber,
  role: oneOfValues('admin', 'guest', 'trial'),
});

⚙️ Combining Guards with `and`

and takes guards in order. First the base, then refinements.

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

// Readonly plus role fixed to the 'admin' literal
type AdminUser = Readonly<User> & { role: 'admin' };

// Reusable guard that narrows role to the 'admin' literal
const byRole = narrowKeyTo(isUser, 'role');
const isAdminUser = byRole('admin'); // AdminUser

// Add age >= 18 as an additional refinement
const isAdultAdmin = and(
  isAdminUser,
  predicateToRefine((u: AdminUser) => u.age >= 18)
);

declare const candidate: unknown;

if (isAdultAdmin(candidate)) {
  // candidate: AdminUser
  console.log(candidate.role); // 'admin'
}

and guarantees short-circuit evaluation — if the first guard fails, the rest won’t run.
Just like logical &&, but type-safe and composable.

🔁 Combining Guards with `or`

or accepts multiple guards and infers their union type automatically.

import { or, narrowKeyTo } from 'is-kit';

type GuestUser = Readonly<User> & { role: 'guest' };
type TrialUser = Readonly<User> & { role: 'trial' };

const byRole = narrowKeyTo(isUser, 'role');
const isGuest = byRole('guest'); // GuestUser
const isTrial = byRole('trial'); // TrialUser

const isGuestOrTrial = or(isGuest, isTrial);

declare const value: unknown;

if (isGuestOrTrial(value)) {
  // value is Readonly<User> & { role: 'guest' | 'trial' }
  console.log(value.role);
}

equalsBy safely compares a property based on a base guard.
or returns only the successful type — automatically narrowing role to 'guest' | 'trial'.
This type inference feels so satisfying 😻

🚫 Negating Guards with `not`

not lets you invert an existing guard or refinement.

import { and, not } from 'is-kit';

// Reuse definitions like isGuestOrTrial
const isGuestOnly = and(isGuestOrTrial, not(isTrial));

declare const x: unknown;
if (isGuestOnly(x)) {
  x.role; // 'guest'
}

Conceptually, not mirrors TypeScript’s Exclude type — letting you express “is not” logic naturally.

🧩 Real-World Example: A Readable Logic DSL

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

// Builder for role literals
const byRole = narrowKeyTo(isUser, 'role');

// admin and age 18 or older
const isAdultAdmin = and(
  byRole('admin'),
  predicateToRefine((u: AdminUser) => u.age >= 18)
);

// guest or trial
const isGuestOrTrial = or(byRole('guest'), byRole('trial'));

This turns messy conditionals into declarative, reusable logic.
Perfect for real-world readability and reuse.

🛡️ Validating Safely with `safeParse`

When you want to return a guard’s result, safeParse keeps things neat:

import { safeParse } from 'is-kit';

declare const input: unknown;

const adminCheck = safeParse(isAdultAdmin, input);
if (adminCheck.valid) {
  const admin = adminCheck.value;
  // admin is Readonly<User> & { role: 'admin' }
  return handleAdmin(admin);
}

const guestCheck = safeParse(isGuestOrTrial, input);
if (guestCheck.valid) {
  const member = guestCheck.value;
  // member is Readonly<User> & { role: 'guest' | 'trial' }
  return handleGuestLike(member);
}

safeParse lets you write flow logic like a DSL.
Clean, composable, and far from the if jungle 🌿

🧭 Summary

and / or / not are type-safe logical operators with short-circuiting
struct and oneOfValues boost reusability with declarative base guards
equalsBy and andAll turn logic into readable, sentence-like expressions
safeParse lets you safely return and reuse validated results

Time to graduate from if (a && b) and start speaking in and(a, b).

If you want to build snappy, composable type guards, try is-kit
today!

🌟 If you enjoyed this, drop a ⭐️ on the repo! It keeps me motivated! 😸

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

Please check tinyLaunch! 🚀

https://tinylaunch.com/launch/6704

Building Type Guards Like LEGO Blocks: Making Reusable Logic with is-kit

nyaomaru — Wed, 15 Oct 2025 11:26:35 +0000

Hey folks!

Even in October, I’m still rocking short sleeves and shorts 😎
I’m @nyaomaru, a frontend engineer!

When writing TypeScript, we often end up creating type guard functions (value is Foo) over and over again.

But you know the pain:

The same isXXX functions appearing everywhere
Copy → tweak → repeat = infinite boilerplate hell
Complex type gymnastics making maintenance painful

Sound familiar? 😅

So today, I’ll show a pattern for turning your type guards into reusable logic.
I’ll use my lightweight, zero-dependency library is-kit to illustrate the idea — but the mindset applies to vanilla TypeScript too.

Alright, let’s dive in! 🧩

What’s a Type Guard Anyway?

In short: a function that performs runtime validation while narrowing types at the same time.

// Checks if the argument is a string at runtime
// and narrows the type to string in the true branch
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

Simple, right?
Here’s a slightly more realistic version:

// A simple User type
type SimpleUser = {
  id: number;
  name: string;
};

// Checks if a value is a SimpleUser
function isUser(value: unknown): value is SimpleUser {
  return (
    typeof value === 'object' &&
    value !== null &&
    typeof (value as any).id === 'number' &&
    typeof (value as any).name === 'string'
  );
}

That’s the usual if (isUser(x)) pattern — inside that block, x.id is safely a number.

Handy, but writing it manually every time is inefficient.
It’s also hard to reuse or compose.

♻️ Build Type Guards Through “Definition” and “Composition”

If you split type guards into smaller, reusable pieces, you can mix and match them across your project.

Let’s make the earlier example more declarative.

Example: Declare the User Shape

The previous isUser was fine, but not very reusable.
Let’s define each isXXX individually:

function isObject(value: unknown): value is object {
  return typeof value === 'object';
}

function isNull(value: unknown): value is null {
  return value === null;
}

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function isNumber(value: unknown): value is number {
  return typeof value === 'number';
}

function isUser(value: unknown): value is SimpleUser {
  return (
    isObject(value) &&
    !isNull(value) &&
    isNumber((value as any).id) &&
    isString((value as any).name)
  );
}

Now each guard is modular — reusable, composable, and clean.

If you need a stricter version of the object guard (to exclude arrays, dates, etc.), you can write:

// Checks for a plain object (not Array, Date, etc.)
// Inference: Record<string, unknown>
function isPlainObject(value: unknown): value is Record<string, unknown> {
  if (typeof value !== 'object' || value === null) return false;
  const proto = Object.getPrototypeOf(value);
  return proto === null || Object.getPrototypeOf(proto) === null;
}

In is-kit, the same logic looks like this:

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

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

Clean, concise, and fully type-safe! ✨

Why?

struct infers InferSchema automatically → id: number and name: string are guaranteed
It only accepts plain objects, not Arrays or Dates
You can harden boundaries via struct(schema, { exact: true }) to reject extra keys

is-kit gives you small building blocks (primitive guards) and composition utilities to build logic like LEGO.

📘 So Far

Splitting guards into small isXXX pieces makes them reusable.
But in real-world code, we often need combinations:

“Add extra conditions” (AND)
“Pass if any condition matches” (OR)

If you chain those manually with if statements… welcome to conditional hell.
Let’s fix that.

🛡️ Express Complex Guards Smartly

Ever seen a snowballing if statement mess?
Like when a field must be even and start with SP\_ and have a specific property?

Let’s walk through a before → after refactor.

Before: a tangled monster

type SimpleUser = {
  id: number;
  name: string;
};

type SpecialUser = {
  id: number;
  name: string;
  specialSetting: string;
};

function isSpecialUser(value: SimpleUser | SpecialUser): value is SpecialUser {
  return (
    isObject(value) &&
    !isNull(value) &&
    isNumber((value as any).id) &&
    isString((value as any).name) &&
    (value as any).id % 2 === 0 &&
    (value as any).name.startsWith('SP_') &&
    isString((value as any).specialSetting)
  );
}

It works, but you’ll go mad maintaining it.

After: small reusable predicates

type UserBase = {
  id: number;
  name: string;
};

type SimpleUser = UserBase;

type SpecialUser = UserBase & {
  specialSetting: string;
};

function isEven(value: unknown): value is number {
  return isNumber(value) && value % 2 === 0;
}

function isSpecialName(value: unknown): value is string {
  return isString(value) && value.startsWith('SP_');
}

function isSpecialSetting(value: unknown): value is string {
  return isString(value);
}

function isSpecialUser(value: SimpleUser | SpecialUser): value is SpecialUser {
  return (
    isObject(value) &&
    !isNull(value) &&
    isEven((value as any).id) &&
    isSpecialName((value as any).name) &&
    isSpecialSetting((value as any).specialSetting)
  );
}

Now it’s modular and clear — easy to extend or reuse elsewhere.

With is-kit

We can express the same thing more elegantly:

import {
  and,
  guardIn,
  isNumber,
  isString,
  predicateToRefine,
  struct,
} from 'is-kit';

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

const isSpecialUser = struct({
  id: and(
    isNumber,
    predicateToRefine((id: number) => id % 2 === 0)
  ),
  name: and(
    isString,
    predicateToRefine((name: string) => name.startsWith('SP_'))
  ),
  specialSetting: isString,
});

const isSpecialUserInUnion = guardIn<SimpleUser | SpecialUser>()(isSpecialUser);

And then:

declare const candidate: SimpleUser | SpecialUser;

if (isSpecialUserInUnion(candidate)) {
  candidate.specialSetting.toUpperCase(); // candidate: SpecialUser
}

That’s all.

struct handles the shape,
and adds conditions,
guardIn safely narrows within unions.

Type-safe, declarative, and beautifully reusable 😸

Note:
guardIn helps safely narrow within unions,
but even plain if (isSpecialUser(x)) often works fine —
TypeScript is smart enough to infer it in many cases.

🎯 Summary

Type guards don’t have to be one-off defense lines.
They can be reusable logic blocks.

With struct to define shape,
predicateToRefine to add constraints,
and and / or to compose conditions —

you can declare isXXX functions that are short, safe, and shareable.

Try converting just one of your existing isXXX into an is-kit version.
You’ll instantly feel the difference 🚀

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

If you like it, drop a ⭐ — it really helps! 😻

My Favorite Frontend Setup Libraries (Project Foundation Edition)

nyaomaru — Wed, 08 Oct 2025 10:28:55 +0000

Hey folks!

I’m @nyaomaru, a frontend engineer who somehow always catches a cold when the seasons change 😿

This time, I’ll introduce three libraries that power the everyday foundation of my development setup:

mise — Tool version management & task runner
TypeDoc — API documentation generator
tsd — Type testing

Alright, let’s dive in together!

mise: Unified version and task management for your tools

https://github.com/jdx/mise

First off, the README looks great — clean logo, nice demos.
The docs are also well done:

👉 https://mise.jdx.dev/getting-started.html

Installation steps vary by OS, so just follow your platform’s guide.

By the way, it’s pronounced “meez”, as in “mise-en-place”:

mise (pronounced "meez") or "mise-en-place"
https://mise.jdx.dev/about.html

🎁 What it can do

Setting up project environments becomes super easy:

Pin and auto-switch versions of Node, pnpm, Bun, Deno, Python, etc.
Compatible with .tool-versions (easy migration from nvm-style workflows)
Built-in task runner (even replaces make)

Personally, I’d call it a mix of nvm + makefile + α — everything nicely bundled in one tool. Love it.

🔎 How to use it

Minimal setup (mise.toml):

[tools]
node = "22.6.0"
pnpm = "9"
bun = "1"

[env]
NODE_ENV = "development"

[tasks.setup]
description = "Install dependencies via pnpm"
run = "pnpm install"

[tasks.dev]
description = "Boot application via pnpm"
run = "pnpm dev"

[tasks.lint]
description = "Run lint via pnpm"
run = "pnpm lint"

Just place this file at the project root — that’s it!

🎯 Why I recommend it

ecause it makes environment setup effortless:

Sync Node and pnpm versions across the whole team instantly
Centralize tasks → same commands work locally and in CI
Save 2–3 seconds of context-switching every time you start work

Perfect for team-based projects.

The only mildly annoying part is that initial “Do you trust this repo?” prompt 😅

Just hit “Yes,” and from then on it’s smooth sailing.
Honestly, I can’t live without it now!

TypeDoc: Generate “truthful” API docs straight from your types

Check out the official site first:

https://typedoc.org/

That stylish auto-generated UI? Yep, all powered by TypeDoc.
So thankful this is open source 🙏

https://github.com/TypeStrong/typedoc

Easy to install and use!

🎁 What it can do

Like swagger-docs, it automatically generates documentation from your code,

Generated from actual exports → less chance of doc drift
Monorepo-friendly: combine multiple packages into one unified site

Since it’s built from code itself, refactoring stays painless — no more stale wiki pages rotting in peace.

🔎 How to use it

pnpm add -D typedoc

Minimal config (typedoc.json):

{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "tsconfig": "tsconfig.json",
  "excludePrivate": true,
  "excludeInternal": true
}

Add it to your scripts for CI integration:

{
  "scripts": {
    "docs": "typedoc"
  }
}

Comments are reflected automatically, too:

// is-lit/define.ts

/**
 * Wraps a user function as a typed predicate.
 *
 * Note: The correctness of the predicate is the caller's responsibility.
 * Its result is coerced to a boolean using `!!` for consistent guard behavior.
 *
 * @param fn Function that returns truthy when the value matches the target shape.
 * @returns Predicate narrowing to the intended type when it returns true.
 */
export function define<T>(fn: (value: unknown) => value is T): Predicate<T>;
export function define<T>(fn: (value: unknown) => boolean): Predicate<T>;
export function define<T>(
  fn: ((value: unknown) => value is T) | ((value: unknown) => boolean)
): Predicate<T> {
  return (value: unknown): value is T => !!fn(value);
}

✨ When you generate docs with typedoc, this JSDoc comment automatically appears as part of the API documentation,
showing both the overload signatures and description in a clean, “truth-from-types” way.

🎯 Why I recommend it

Because it’s automatic and low-maintenance:

Super easy to set up — works out of the box if your types are clean
Publish on GitHub Pages → instantly shareable public docs
Configurable via typedoc.json, package.json, or tsconfig.json

Perfect for sharing specs and APIs across teams.

Note: it requires Node.js, so pairing it with mise lets you run it as mise run docs — easy peasy.

tsd: Test your types with `.test-d.ts`

https://github.com/tsdjs/tsd

This one’s a type-level testing tool.
It’s especially useful for libraries or OSS — maybe overkill for regular apps,
but really fun to try!

🎁 What it can do

Run type tests instead of runtime ones:

Execute .test-d.ts files
Use expectType, expectError, expectAssignable, etc.
Guarantees type behavior at compile time

It also doubles as usage documentation — your tests show how types are intended to be used.

🔎 How to use it

pnpm add -D tsd

Add config to your package.json:

"tsd": {
  "directory": "tests-d",
  "compilerOptions": {
    "baseUrl": "."
  }
}

Create a tests-d directory with a tsconfig.json inside:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "baseUrl": "..",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["./**/*.ts"],
  "exclude": ["../node_modules", "../dist"]
}

Example test:

import { expectType } from 'tsd';
import { define } from '../../src/core/define';
import type { Predicate } from '../../src/types';

// =============================================
// describe: define (types)
// =============================================
// it: returns a Predicate<T> regardless of input predicate flavor
expectType<Predicate<string>>(define<string>(() => true));
expectType<Predicate<number>>(define<number>((x) => typeof x === 'number'));

This example comes from my own library: is-kit

It's a lightweight, dependency-free way to build safe isXXX type guards 🚀

🎯 Why I recommend it

Because testing types is surprisingly fun:

Ensures type-level safety that often gets overlooked
Verifies that your intended usage matches your design

Wrap-up

So that’s my shortlist of must-have project setup libraries for modern frontend development:

mise
typedoc
tsd

How about you? What are your favorite tools?

Honestly, I didn’t write this just to say,

“Look how cool these are 😎”

It’s more like,

“I genuinely want to hear your recommendations!” 🙏

So please drop your favorite libraries, articles, books, or even unrelated obsessions in the comments — I’d love to check them out!

Bonus

I also made a tiny utility for building type-safe isXXX guards — give it a look if you’re curious!

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

Build isXXX the Easy Way? Meet is-kit

nyaomaru — Sun, 05 Oct 2025 12:03:10 +0000

Hey folks! The leaves are about to turn 🍁

I keep telling myself “just one more coffee”… but my hands are starting to shake ☕️😂
Anyway, I’m @nyaomaru, a frontend engineer.

Why I built this

If you write TypeScript a lot, you’ve probably hand-written type guards like value is Foo more times than you can count.
And keeping runtime checks perfectly aligned with types… kinda exhausting.

Enter is-kit — a lightweight, zero-dependency “guard generator kit” that slices through boring boilerplate ✂️

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

Why is-kit?

🖋 Stop hand-writing value is Foo
- Centralize guard definitions with define and predicateToRefine.
⚙️ Compose logic with and / or / not
- Express domain-specific conditions declaratively.
🧩 Combinators like struct / array / tuple
- Validate nested objects in just a few lines.
✅ Runtime + type tests
- Confidence via Jest (runtime) and tsd (type assertions).

How do I use it?

A super common case: “non-empty string” without hand-rolling the predicate signature.

import { define, isString } from 'is-kit';

const isNonEmptyString = define<string>(
  (value) => isString(value) && value.length > 0
);

isNonEmptyString('foo'); // true
isNonEmptyString(''); // false

By passing the generic <string>, you don’t need to write the value is string predicate signature yourself — clean and tidy.

Another practical one: identifying a User shape.

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

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

isUser({ id: 1, name: 'A' }); // true

const parseUser = safeParseWith(isUser);

const result = parseUser({ id: 'abc', age: 42 });
// result.valid === false

if (result.valid) {
  // on success
} else {
  // on failure
}

You can check whether API responses or form inputs satisfy your expected types safely.

For more complex conditions, compose:

import { and, or, not, predicateToRefine, isString, isNumber } from 'is-kit';

const isLongLiteral = predicateToRefine<string>((value) => value.length > 3);

const isLongString = and(isString, isLongLiteral);
isLongString('abcd'); // true
isLongString('ab'); // false
isLongString(123 as unknown); // false

or(isString, isNumber)('foo'); // true
not(isString)(123); // true

With the combinators + primitives/object guards, you can express a wide range of isXXX guards cleanly.

Install & Ecosystem

Install from npm:

pnpm add is-kit
# or
bun add is-kit
# or
npm i is-kit
# or
yarn add is-kit

Prefer JSR with Deno/Bun? Import TypeScript directly:

import { struct } from 'jsr:@nyaomaru/is-kit';

Wrap-up

is-kit is a small kit for writing safe TypeScript guards:

Keep it tiny with define
Model bigger shapes with struct
Combine complicated logic with and / or / not
Make ergonomics nice with safeParse / safeParseWith

If you’re tired of drift between types and runtime checks, drop is-kit into your project and give it a spin. 🚀

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

And if you like it, a ⭐ would make my day! 😻

DEV Community: nyaomaru

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

Game - Nyaomaru

🍽️ Quick recap

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

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

⛳ What I struggled with

1. SVG sprite animation and the whitespace problem

2. DOM movement behaving differently depending on display size and device

3. AI couldn’t generate the CSS animation I actually wanted

4. Collision detection didn’t match the visuals

Summary

nyaomaru / nyaomaru-portfolio

"Run Away From Work" Game is here → https://nyaomaru-portfolio.vercel.app/game

Nyaomaru Portfolio

🚀 Highlights

🎮 Main Feature: Game

🕹️ Controls

💻 Terminal

✨ What It Does

⚠️ Important

Bonus: Sound effects matter too

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

🐾 Quick recap

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

✏️ What this article focuses on

🥣 React as the shell, DOM as the runtime

🍴 React and games optimize for different things

What I stopped doing

✂️ Splitting game logic into hooks

🧵 One game loop controls the clock

🕶 Small optimizations mattered a lot

Moving elements with transform

Avoiding unnecessary sprite swaps

Only calculating when needed

🎯 Final thoughts

Bonus

nyaomaru / nyaomaru-portfolio

"Run Away From Work" Game is here → https://nyaomaru-portfolio.vercel.app/game

Nyaomaru Portfolio

🚀 Highlights

🎮 Main Feature: Game

🕹️ Controls

💻 Terminal

✨ What It Does

⚠️ Important

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

🎮 How to play

🤔 Why I made this

⚙️ How I built it

🤖 What it was like building a game with AI

What was difficult 😅

What worked well 🙌

🎯 Conclusion

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

What are MCP Apps?

Publishing a UI using ext-apps

Setup

Build config

Deploy

Building the MCP Server

Exposing the server with ngrok

Configuring ChatGPT

Final thoughts

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

🎯 OSS Projects I Released in 2025

🤔 Why Did I Build Them?

is-kit

What Worked Well with is-kit

changelog-bot

What Worked Well with changelog-bot

divider

What I Learned from divider

✨ Goals for 2026

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

But then… Flow happened 😇

🌊 What is Flow?

🧩 Why should we learn Flow?

⚔️ Flow vs TypeScript (quick comparison)

🌀 Flow Types We’ll Focus On

Publishing a UI using `ext-apps`

🌪️ Understanding `mixed`

`mixed` is the safest “anything”

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

🕶️ Understanding `opaque` types

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

What about `strictFunctionTypes`?

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

🏗️ Defining a Base Guard with `struct`

⚙️ Combining Guards with `and`

🔁 Combining Guards with `or`

🚫 Negating Guards with `not`

🛡️ Validating Safely with `safeParse`