DEV Community: Gaurav Kumar Singh

Sick of App Store Ads? So I Built My Daughter Her Own Drawing PWA

Gaurav Kumar Singh — Thu, 02 Jul 2026 14:14:45 +0000

Introduction

"Daddy, another ad?"

If you have young kids who use an iPad, you may know this problem.

Last week, my daughter was using a free drawing app. She was happy and busy making her art. But every few minutes, a loud ad came on the screen. She could not skip it. It stopped her drawing again and again.

After this happened many times, she looked at me and said:

"I just want to draw. Can we make our own app without ads?"

At first, I could have said that making an app takes too much time. But then I thought, why not try?

So we made it a small weekend project.

My daughter became the product boss. She asked for rainbow brushes, a big drawing space, fun sounds, and no pop-ups. I worked on the code.

Together, we built this:

unicorn-draw.vercel.app

The tool that helped us build it fast was Google AI Studio with Gemini.

The Tech Stack

I wanted the app to be easy to use on an iPad. I also did not want to deal with the App Store.

So I made it as a Progressive Web App, or PWA. This means it works like an app, but it runs in the browser.

Here is what I used:

HTML5 Canvas API for drawing
CSS for big buttons and bright colors
Service Worker so the app can work offline
Web App Manifest so it can be added to the home screen
Google AI Studio and Gemini to help write and improve the code

Because it is a PWA, my daughter can open it from the iPad home screen. It runs full screen. It has no ads, no tracking, and no hidden pop-ups.

Building with Google AI Studio

Google AI Studio made the work much faster.

First, I asked Gemini to make a simple drawing app using HTML5 canvas. I also asked it to support touch events, so it would work well on an iPad.

Then my daughter tested the first version. She quickly asked for a magic rainbow brush and a simple clear button.

I gave the code back to Gemini and asked it to add a rainbow brush. I also asked it to make the buttons look more fun for a drawing app.

After that, I used Gemini to help create the PWA files, like manifest.json and the service worker.

In a short time, the app started to feel like a real tablet app.

Source Code

The project is open source.

You can see the full code here:

GitHub Repository: gaurav101/unicorn-draw

How to Install It on an iPad or Phone

You can add the app to your home screen in a few seconds.

Open unicorn-draw.vercel.app in your browser.
On iPhone or iPad, tap the Share button. On Android, tap the three dots menu.
Tap "Add to Home Screen".
Open it from the home screen and start drawing.

Now your child has a simple drawing app with no ads.

What I Learned

1. AI Helps You Build Faster

Gemini did not just write code for me. It helped me move fast.

Instead of spending time on small setup work, I could focus on how the app should feel for my daughter.

The whole project took only a couple of hours.

2. Kids Can Learn That They Can Build Things

The best part was not the app.

The best part was seeing my daughter understand something important:

Technology is not something we only have to use. If something is annoying or broken, we can try to make a better version.

That was the real win.

Markdown to Styled HTML in Java

Gaurav Kumar Singh — Sun, 28 Jun 2026 08:22:14 +0000

If you have ever built a Java application that converts Markdown to HTML—whether for a blog engine, a documentation site, or user-generated comments—you have likely run into a frustrating roadblock.

You pull in a solid library like commonmark-java, pass your Markdown string, and get perfectly valid semantic HTML blocks. But then you render it on the frontend and realize it looks completely unstyled.

Modern CSS frameworks like Tailwind CSS, Bootstrap, or Bulma rely heavily on utility classes. They don't automatically style raw <h1>, <p>, or <blockquote> tags unless you wrap them in heavy global stylesheet overrides. To fix this in Java, you are usually forced to write verbose custom tag renderers, map complex attribute providers, or write messy string-replacement wrappers.

That is exactly the problem FluentMarkdown solves.

💡 What is FluentMarkdown?

FluentMarkdown is a lightweight, zero-boilerplate Java library built directly on top of commonmark-java. It introduces a clean, fluent API that automatically injects the proper CSS framework classes into your HTML elements during the parsing phase.

Instead of fighting your CSS framework, you can map your tags instantly using built-in presets or completely custom styles.

🛠️ Getting Started

1. Installation

The library is explicitly lightweight (only four core files) and requires Java 17 or later. You can add it via Maven:

<dependency>
    <groupId>io.github.gaurav101</groupId>
    <artifactId>fluentmarkdown</artifactId>
    <version>1.0.4</version>
</dependency>

2. Quick Start: Use a Framework Preset

If you use Tailwind, Bootstrap 5, or Bulma, FluentMarkdown has pre-mapped configurations ready to go.

Here is how easily you can render fully-styled Tailwind HTML:

import io.github.gaurav101.fluentmarkdown.Markdown;

public class App {
    public static void main(String[] args) {
        String markdown = "# Hello World\nThis is a paragraph.";

        // One fluent chain handles it all
        String tailwindHtml = Markdown.from(markdown)
                                      .withTailwind()
                                      .toHtml();

        System.out.println(tailwindHtml);
    }
}

Output:

<h1 class="text-4xl font-extrabold tracking-tight mb-4 mt-6">Hello World</h1>
<p class="mb-4 leading-relaxed text-base">This is a paragraph.</p>

Switching frameworks is as simple as swapping .withTailwind() for .withBootstrap() or .withBulma().

🧠 Advanced Usage

🔒 Step 3: XSS Protection (Safe Mode)

If you are processing untrusted user input (like blog comments), rendering raw HTML can expose your app to Cross-Site Scripting (XSS) attacks. FluentMarkdown includes a built-in .safe() modifier that strips out malicious inline scripts and raw HTML blocks seamlessly.

String unsafeInput = "<script>alert('hack')</script>\n\n# Safe Title";

String safeHtml = Markdown.from(unsafeInput)
                          .withTailwind()
                          .safe() // Strips dangerous HTML
                          .toHtml();

🎨 Step 4: Custom Style Configurations

Don't use a standard CSS framework? You can build an immutable StyleConfig to map your own internal design system classes to any HTML tag.

import io.github.gaurav101.fluentmarkdown.StyleConfig;

StyleConfig myCustomConfig = StyleConfig.builder()
        .tag("h1", "custom-main-title")
        .tag("p", "body-text text-muted")
        .tag("a", "global-link")
        .build();

String customHtml = Markdown.from(markdown)
                            .withStyle(myCustomConfig)
                            .toHtml();

🔄 Step 5: Extend Existing Presets

If you love the Tailwind preset but want to tweak just one or two elements (like changing the link color), you can merge and overwrite tags dynamically:

import io.github.gaurav101.fluentmarkdown.Presets;

StyleConfig modifiedTailwind = StyleConfig.builder()
        .mergeFrom(Presets.tailwind()) // Start with Tailwind defaults
        .tag("a", "text-indigo-600 underline") // Overwrite just the anchor tag
        .build();

🎯Conclusion

FluentMarkdown provides a highly practical solution to a common backend UI problem. It keeps your Java code clean, readable, and perfectly married to modern frontend utilities.

Give the project a look, try it out in your next Java project, and don't forget to drop a ⭐️ on the repository!

👉 GitHub Repository: gaurav101/FluentMarkdown

The Hidden Cost of the AI Hype

Gaurav Kumar Singh — Thu, 25 Jun 2026 15:55:00 +0000

We talk a lot about what AI can build.

Code generation. Faster prototypes. Automated debugging. One-shot apps. Entire products created in hours.

And yes, AI is powerful.

But there is a quieter cost we are not talking about enough:

AI hype is starting to weaken the motivation to learn core engineering deeply.

That should worry us.

1. The "Why Bother?" Mindset

When the dominant narrative says AI can generate code instantly, many engineers start asking:

Why should I spend months mastering frameworks, architecture, databases, networking, or system design?

At first, that sounds practical. If a tool can help, why not use it?

But there is a difference between using AI to move faster and using AI to avoid understanding.

Core engineering is not just about writing code. It is about knowing why something works, where it breaks, how it scales, and how to fix it when the generated answer is wrong.

If we skip that learning, we create engineers who can prompt systems but cannot reason deeply about systems.

That is a dangerous tradeoff.

2. The Funding and Praise Monopoly

Right now, AI gets most of the attention.

Budgets move toward AI. Leadership praises AI initiatives. Teams are pushed to add AI features even when the fundamentals are still weak.

Meanwhile, excellent core engineering often goes unnoticed.

The people improving reliability, performance, developer experience, infrastructure, security, and maintainability are still doing high-impact work. But in many places, that work is being treated as less exciting simply because it is not branded as AI.

This creates pressure.

Engineers feel they must pivot to AI, not always out of interest, but out of fear. Fear of being left behind. Fear of being replaced. Fear that their existing expertise is no longer valued.

That is not innovation. That is anxiety disguised as progress.

3. The "AI-First" Discount

There is another subtle problem.

When someone builds something impressive today, the reaction is often:

AI probably generated that.

That assumption discounts real skill.

It ignores the planning, debugging, tradeoffs, refactoring, architecture, and judgment behind the work. AI may assist, but it does not automatically create good software.

Great engineering still requires taste. Context. Discipline. Experience. The ability to make hard decisions when requirements are messy and systems are complex.

When we assume every good output came from AI, we quietly devalue human craftsmanship.

AI Is an Accelerator, Not a Substitute

AI can help us move faster.

It can explain concepts, generate drafts, find bugs, write boilerplate, and help us explore ideas quickly.

But AI is not a replacement for engineering fundamentals.

If we stop learning the building blocks, we weaken the entire ecosystem AI depends on. Someone still needs to understand distributed systems. Someone still needs to design reliable APIs. Someone still needs to debug production failures at 2 AM. Someone still needs to know when the AI-generated solution is wrong.

The future should not be "AI instead of engineers."

It should be AI with stronger engineers.

What We Should Value

We need to keep rewarding the work that keeps technology stable:

Strong system design
Clean architecture
Reliable infrastructure
Secure software
Maintainable codebases
Deep debugging skills
Thoughtful technical leadership

AI can support this work, but it cannot replace the need for people who understand it deeply.

The best engineers of the future will not be the ones who blindly rely on AI.

They will be the ones who use AI wisely while continuing to sharpen their fundamentals.

So the real question is:

How are you balancing the AI push while keeping your core engineering skills sharp?

Let's discuss.

Building a Safe, Local AI Coding Agent with Node.js

Gaurav Kumar Singh — Fri, 19 Jun 2026 03:57:12 +0000

Welcome to the 4th article of the MCP and RAG with JS series.

In this article, we will learn what AI agents are by building a practical, beginner-friendly coding agent in JavaScript. We will use a locally running LLM, Mistral on Ollama.

You do not need any paid subscription or API key. Everything runs locally on your machine, so this is accessible for learning, testing, and experimenting.

What We Are Building

We are building a local personal coding agent.

It runs in the terminal and helps us understand a JavaScript project. It can:

list project files
read project files
search text
explain code
find possible bugs
propose code changes

The important safety rule is this:

The agent can inspect files, but it does not directly edit them. If it wants to change something, it only returns a patch proposal for a human developer to review.

So in simple words, we are building a small local coding assistant.

Why This Helps Us Learn

AI agents can sound complicated, but most agent systems use a few common patterns.

In this project, we will learn those patterns with plain JavaScript:

Agent loop: repeat until the model gives a final answer.
Tool calling: let the model request specific JavaScript functions.
Tool allowlist: only allow approved tools to run.
System prompt: tell the model how it should behave.
JSON action protocol: make the model respond with structured JSON.
Model adapter: keep the Ollama HTTP code in one small file.
Safety boundary: keep file access inside the project root.
Human-in-the-loop changes: propose patches instead of applying them.
Tests for safety: verify path traversal, large file, and missing file behavior.

These same ideas appear in larger AI-agent frameworks. This project keeps them small enough to understand.

The Big Idea

A normal chatbot usually works like this:

User asks question -> Model answers

An agent works more like this:

User asks question
  -> Model decides what to do
  -> JavaScript runs a safe tool
  -> Model sees the tool result
  -> Model answers

The model does not directly read your files or run commands. It asks for a tool, and your JavaScript code decides whether that tool is allowed.

That is the main idea behind this project.

Project Structure

You can explore and clone the complete codebase in the coding-agents GitHub repository.
The important files are:

.
|-- package.json
|-- src
|   |-- cli.js
|   |-- agent.js
|   |-- ollama.js
|   `-- tools.js
`-- test
    `-- tools.test.js

Each file has a clear job:

src/cli.js: terminal entry point
src/agent.js: agent loop and tool dispatch
src/ollama.js: local Ollama API client
src/tools.js: safe filesystem tools
test/tools.test.js: safety and tool behavior tests

1: CLI Entry Point

The app starts in src/cli.js.

It imports the agent:

import { runAgent } from "./agent.js";

Then it chooses the project root and model:

const root = options.root || process.cwd();
const model = options.model || process.env.OLLAMA_MODEL || "mistral";

This means:

use --root if the user provides it
otherwise use the current folder
use --model if provided
otherwise use OLLAMA_MODEL
otherwise use mistral

The CLI supports two modes.

One-shot mode:

npm start -- "Explain src/tools.js"

Interactive mode:

npm start

In both cases, the CLI eventually calls:

const answer = await runAgent({ goal, root, model, verbose });

So the CLI is only responsible for input and output. The real agent behavior lives in runAgent.

2: Agent Loop

The main function is in src/agent.js:

export async function runAgent({ goal, root, model, verbose = false }) {

At the start, it creates the available tools:

const { createTools } = await import("./tools.js");
const tools = createTools({ root });

Passing root is important. It tells the tools which folder they are allowed to inspect.

Then the agent creates a message history:

const messages = [
  {
    role: "system",
    content: buildSystemPrompt(tools)
  },
  {
    role: "user",
    content: goal
  }
];

The system message contains rules for the model. The user message contains the developer's request.

Then the agent runs a loop:

for (let step = 1; step <= MAX_STEPS; step += 1) {
  const prompt = renderPrompt(messages);
  const raw = await generateWithOllama({ prompt, model });
  const action = parseAction(raw);

  // final answer or tool call
}

MAX_STEPS is set to 8, so the agent cannot loop forever.

This loop is the heart of the agent:

messages -> prompt -> model -> action -> tool or final answer

3: System Prompt

The system prompt tells the model how to behave.

In this project, the prompt says the model should:

inspect files before making project-specific claims
never claim a patch was applied
use propose_patch only for suggested changes
return exactly one JSON object

It also describes the available tools:

const toolDescriptions = Object.entries(tools)
  .map(([name, tool]) => `- ${name}: ${tool.description} Parameters: ${JSON.stringify(tool.parameters)}`)
  .join("\n");

This lets the model know what it can ask for.

The model must respond in one of two shapes.

To call a tool:

{"type":"tool","name":"read_file","arguments":{"path":"src/example.js"}}

To finish:

{"type":"final","answer":"Your answer here."}

This is a simple JSON action protocol. It is easy to understand because there is no hidden framework magic.

4: Local Model Adapter

The file src/ollama.js keeps the Ollama API call separate from the rest of the app.

The default local URL is:

const DEFAULT_OLLAMA_URL = "http://127.0.0.1:11434";

The function sends the prompt to Ollama:

const response = await fetch(`${baseUrl}/api/generate`, {
  method: "POST",
  headers: {
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model,
    prompt,
    stream: false,
    options: {
      temperature
    }
  })
});

Then it returns the model text:

const data = await response.json();
return data.response || "";

This file has one job:

prompt in -> Ollama HTTP request -> model response out

Keeping this in one file makes it easier to swap models later.

5: Tool Calling

After Ollama responds, the agent parses the response:

const action = parseAction(raw);

If the model gives a final answer, the agent returns it:

if (action.type === "final") {
  return action.answer;
}

If the model asks for a tool, the agent checks whether that tool exists:

const tool = tools[action.name];
if (!tool) {
  messages.push({
    role: "tool",
    content: JSON.stringify({
      error: `Unknown tool: ${action.name}`,
      allowedTools: Object.keys(tools)
    })
  });
  continue;
}

This is very important.

The model cannot invent tools. It can only use tools that exist in the local JavaScript object.

Then the agent runs the tool:

const result = await tool.run(action.arguments || {});

And sends the result back into the message history:

messages.push({
  role: "tool",
  content: JSON.stringify({
    tool: action.name,
    result
  })
});

Now the model can use real project information instead of guessing.

Example flow:

User: Explain src/tools.js
Model: calls read_file
JavaScript: reads the file safely
Model: sees the file content
Model: gives final explanation

6: Safe Tools

The tools live in src/tools.js.

The project has four tools:

list_files
read_file
search_text
propose_patch

Each tool has:

description: tells the model what it does
parameters: tells the model what arguments it accepts
run: the actual JavaScript function

Example shape:

read_file: {
  description: "Read a UTF-8 text file from inside the project root.",
  parameters: {
    path: "File path relative to project root."
  },
  run: async ({ path: filePath } = {}) => {
    // safe implementation
  }
}

The tools are intentionally narrow.

list_files lists files under the project root.

read_file reads one text file if it is safe and not too large.

search_text searches project files for a string or regex.

propose_patch returns a patch proposal, but does not apply it.

That last point matters. The model can suggest changes, but a human still reviews them.
** use a safe regex engine if you are planning to expose the agent to external user inputs. **

7: Path Safety With `safeResolve`

The most important safety function is:

export function safeResolve(root, requestedPath) {
  const absolute = path.resolve(root, requestedPath);
  const relative = path.relative(root, absolute);

  if (relative.startsWith("..") || path.isAbsolute(relative)) {
    throw new Error(`Path escapes project root: ${requestedPath}`);
  }

  return absolute;
}

This blocks path traversal.

For example, this should be allowed:

src/tools.js

But this should be blocked:

../outside.txt

Why?

Because the agent should only inspect the selected project folder. Model output is not trusted input, so every requested path goes through safeResolve.

This is one of the most important lessons in agent development:

Give the model useful tools, but put real safety checks in code.

8: Size Limits

The tool layer also avoids reading huge files:

const MAX_READ_BYTES = 80_000;
const MAX_SEARCH_FILE_BYTES = 250_000;

read_file throws an error if a file is too large.

search_text skips files that are too large.

This protects the model context and keeps the agent responsive.

9: Patch Proposals, Not Auto-Edits

The propose_patch tool returns:

{
  summary,
  patch,
  applied: false,
  note: "Patch proposal only. Review before applying."
}

This is a human-in-the-loop design.

The agent can help you think and propose changes, but it does not silently modify your files.

For a beginner agent, this is a good safety tradeoff.

10: Tests for Safety

The project uses Vitest.

From package.json:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

The tests cover the dangerous parts:

safeResolve allows normal paths
safeResolve blocks ../ traversal
list_files handles missing directories
read_file rejects missing paths and directories
read_file rejects large files
search_text skips large files
propose_patch returns applied: false

Example traversal test:

expect(() => safeResolve(fixtureProjectRoot, "../outside.txt")).toThrow(/escapes project root/);

Example large-file test:

await expect(tools.read_file.run({ path: "large-read.txt" })).rejects.toThrow(/too large to read safely/);

Tests are not just for correctness here. They protect the safety boundary of the agent.

Complete Request Flow

If you run:

npm start -- "Explain src/tools.js"

the flow is:

src/cli.js receives the request.
It calls runAgent.
src/agent.js creates safe tools.
The system prompt describes the rules and tools.
src/ollama.js sends the prompt to local Ollama.
The model returns a JSON action.
If it asks for a tool, the agent checks the allowlist.
The tool runs with safety checks.
The tool result goes back to the model.
The model returns a final answer.

That is an AI agent in practical terms.

It is an LLM connected to a controlled loop, safe tools, and clear rules.

How to Run It

Requirements:

Node.js 18 or newer
Ollama installed
Mistral pulled locally

Pull the model:

ollama pull mistral

Start Ollama:

ollama serve

Run the agent:

npm start

Ask one question:

npm start -- "Explain src/agent.js"

Inspect another project:

npm start -- --root /path/to/project "Find bugs in the main CLI file"

Run tests:

npm test

Run syntax checks:

npm run check

What to Remember

An AI agent is not just an LLM.

An AI agent is usually:

LLM + loop + tools + context + safety rules

In this project:

the CLI gets the user request
the agent loop manages steps
Ollama provides the local model
tools provide controlled abilities
safeResolve protects file access
tests protect the safety behavior

The model can request actions, but JavaScript decides what actually runs.

That is the key idea.

Final Thoughts

This project is intentionally small, but it teaches the foundation behind many larger agent systems.

Once you understand this version, you can explore more advanced ideas like:

memory across chat turns
streaming model output
richer tool schemas
patch validation
confirmation-based patch applying
MCP tools
RAG over larger codebases

But the core idea stays the same:

Mistral is a good simple default for learning, but when you are building stronger coding agents, coding-focused models usually give better results. Good options to try are qwen2.5-coder, deepseek-coder, and Gemma.

Build useful tools, keep them narrow, and let your application code enforce the safety boundaries.

SOLSTICE: Planetary Balance

Gaurav Kumar Singh — Tue, 16 Jun 2026 04:17:53 +0000

This is a submission for the June Solstice Game Jam

What I Built

Solstice Balance is an interactive 3D calibration simulator where the player stabilizes Earth's obliquity (target 23.44°) and rotational speed to prevent a simulated thermal collapse.
Players use thruster-style controls to correct tilt and spin while reacting to procedurally generated cosmic disturbances (solar flares, gravitational tides, meteors).
The goal was to make a tactile, physics-driven experience that ties to the June Solstice theme—balancing seasonal geometry with emergent hazards.

Game Demo

Play the live demo: https://solstice-game.vercel.app/
(Recommended: open in a desktop browser for best WebGL and audio support.)

solstice-game.vercel.app

Code

Full source code and development history: https://github.com/gaurav101/solstice-game

How I Built It

AI Assistance: Utilized Google Gemini to pair-program, debug complex WebGL contexts, and rapidly iterate on the core physics calculations and WebGL Sound generation.
Framework: React + TypeScript with Vite for fast iteration.
3D & Physics: Three.js for rendering and cannon-es for rigid-body physics to simulate tilt, spin, and meteor impacts.
Audio: WebAudio-based synth engine and sampled effects for real-time atmospheric feedback.
UI: Tailwind CSS for a clean, rapid HUD layout; React state syncs real-time telemetry (score, alignment, RPM) seamlessly with the WebGL loop.
Performance Optimization: Employed procedural textures, batched particle systems, and defensive resource disposal to prevent memory leaks across scene restarts. ## How to play the game Below is your official flight manual to successfully calibrate Earth's rotation and orientation, countering severe space weather, and maintaining life-supporting equilibrium.

Notable design choice: The game loop runs inside a single requestAnimationFrame driven effect that cleanly tears down Three/Cannon resources when switching game states to completely avoid leaking WebGL contexts.

How To Play the Game (https://solstice-game.vercel.app/)

🛰️ 1. The Core Objective

Your active task is to guide and maintain Earth's planetary parameters in specified target alignment zones:

Target Axial Obliquity: 23.0° to 23.9° (aiming precisely for the natural June Solstice angle of 23.44°).
Target Rotational Velocity (Spin): 1.0 to 2.5 RPM (Revolutions Per Minute).
Planetary Ecosystem Integrity: Must remain above 0%. Integrity decays rapidly any second Earth remains outside optimal thresholds.

🎮 2. Control Layout

Counter-act deep space gravitational pull and harsh solar winds by applying immediate corrective torque.

Keyboard Input	Control Board Thruster	Operational Action
`W` or `▲ Up`	Pitch Forward	Tilts Earth's axis forward pointing towards the Sun
`S` or `▼ Down`	Pitch Backward	Tilts Earth's axis backward away from the Sun
`A` or `◀ Left`	Spin Faster	Speeds up the Earth's west-to-east spin velocity
`D` or `▶ Right`	Spin Slower	Applies electromagnetic dragging to slow rotation down

☀️ 3. Key Calibration Rules

📍 The Solstice sweet spot (23.44°)

When Earth is tilted at 23.44°, the North Pole is angled perfectly toward the Sun. In this position, you will see a bright circular sunlit ring over the Arctic region (the Midnight Sun) while the Antarctic Circle remains in winter shadow. This is the June Solstice Threshold.

Maintaining the axis inside the green 23.0° - 23.9° band raises your Calibration Accuracy.
Every second spent inside optimal zones awards Equilibrium Points.

🌀 The Rotational Band (1.0 to 2.5 RPM)

Static Risk (Spin below 0.3 RPM): If the Earth stops spinning, one side of the planet is cooked under permanent radiation, and the other freezes in absolute darkness. Ecosystem integrity will drop exponentially!
Erosion Risk (Spin above 3.5 RPM): Rotating too fast generates cosmic atmospheric drag that will tear away the ozone layers. Ecosystem integrity drops rapidly.

🚨 4. Galactic Disturbance Hazards

The orbital field is subject to unexpected external solar interferences that will knock you out of alignment:

Coronal Mass Ejections (Solar Flares): Strong electromagnetic storms that apply extreme pitch forces, abruptly throwing off the planetary tilt obliquity.
Atmospheric Gravitational Tides: Tidal fluctuations that can speed up or slow down Earth's spin speed.
Meteor Incursions: Direct strikes that transfer kinetic momentum, rotating or tipping Earth suddenly.

Listen for the Audio Synth’s pitch and tempo: The onboard audio system uses warning buzzers and frantic tempo modulation to signal when parameters are entering danger thresholds.

🏆 5. Tips for Pro-Commanders

Pulsed Thrusters over Static Holding: Do not hold down thruster buttons endlessly. Tap controls in short bursts to counteract drift, letting the friction settle the planet in the optimal zone.
Balance First, Tilt Second: If you are knocked completely off-course, prioritize bringing the planetary spin back into the 1.0 - 2.5 RPM band first to stop thermal decay, then nudge the obliquity to the target solstice angle.
Observe the Shaders: Watch the gorgeous daytime sunlight and glittering nightly city light shaders. If you see city light configurations rotating either too fast or not at all, immediately act!

Initialize engine calibration, steady the core, and save the Solstice!

Prize Categories

Best Google AI Usage: Google Gemini was instrumental in prototyping the initial graphics setup, debugging tricky 3D coordinate transformations, and ensuring the physics-driven gameplay integrated perfectly with React's state management.

Build a Local RAG AI App with Ollama, Mistral, and Node.js

Gaurav Kumar Singh — Sun, 14 Jun 2026 15:19:13 +0000

Most people start using Large Language Models by asking questions directly:

Question -> LLM -> Answer

This works well for general questions.

But what happens when you ask about your own documents, company policy, product FAQ, or internal notes?

The model may not know the answer. Even worse, it may guess confidently. This is called a hallucination.

That is the problem RAG solves.

In this article, we will build a simple local RAG app using Ollama, Mistral, and Node.js.

Complete code is available here:

https://github.com/gaurav101/ai-experiment/tree/main/rag

What Is RAG?

RAG stands for Retrieval-Augmented Generation.

That sounds complex, but the idea is simple:

Before asking the LLM to answer, first search your own documents and give the most useful parts to the model.

So instead of this:

User question -> LLM -> Answer

we do this:

User question
   -> Search local documents
   -> Find relevant text
   -> Send that text to the LLM
   -> Generate an answer

Think of it like an open-book exam.

The LLM is still doing the writing, but now it has the right page open before it answers.

Why RAG Matters

RAG is important because most real AI apps need private or updated information.

For example:

A chatbot that answers questions from company documents
A support assistant that reads product FAQs
A legal assistant that searches contracts
A coding assistant that understands project docs
A personal assistant that uses your own notes

Without RAG, the model only uses what it already learned during training.

With RAG, we can give the model fresh information at runtime.

This means:

No need to retrain the model
Documents can stay private
Answers are based on your data
The system is easier to update

If your refund policy changes, you update the document and rebuild the index. You do not retrain the LLM.

What We Will Build

We will build a local RAG app that can answer questions from files stored on your machine.

The app uses:

Node.js for the code
Ollama to run models locally
Mistral to generate answers
nomic-embed-text to create embeddings
A local data/docs folder for documents
A local data/index.json file as a simple vector index

The project flow is:

Documents -> Chunks -> Embeddings -> Search -> Context -> Mistral -> Answer

Do not worry if words like "embeddings" or "vector index" feel new. We will walk through them step by step.

Step 1: Install Ollama

First, install Ollama:

https://ollama.com/download

On Linux or macOS, you can also install it with:

curl -fsSL https://ollama.com/install.sh | sh

Start Ollama:

ollama serve

Now pull the two models we need.

Mistral will generate the final answer:

ollama pull mistral

nomic-embed-text will convert text into embeddings:

ollama pull nomic-embed-text

You can test Mistral with:

ollama run mistral

Step 2: Create the Node.js Project

Create a new project:

mkdir local-rag
cd local-rag
npm init -y

Use ES modules by adding this to package.json:

{
  "type": "module"
}

Install dotenv:

npm install dotenv

In this project, we use these scripts:

{
  "scripts": {
    "index": "node src/index-docs.js",
    "ask:ollama": "node src/ask-ollama.js"
  }
}

npm run index builds the searchable document index.

npm run ask:ollama asks a question using Ollama and Mistral.

Step 3: Add Local Documents

Create a folder for your documents:

mkdir -p data/docs

Add a file:

data/docs/company-faq.txt

Example content:

Refunds are allowed within 14 days of purchase.
Enterprise customers get priority email support.
The product supports SSO on the Business and Enterprise plans.

These documents are the knowledge base for our RAG app.

Later, when the user asks a question, the app will search these files first.

Step 4: Add Configuration

Create src/config.js.

This file keeps all important settings in one place:

export const DOCS_DIR = process.env.DOCS_DIR || "data/docs";
export const INDEX_FILE = process.env.INDEX_FILE || "data/index.json";

export const OLLAMA_BASE =
  process.env.OLLAMA_BASE_URL || "http://localhost:11434";

export const OLLAMA_EMBED_ENDPOINT = "/api/embeddings";
export const OLLAMA_EMBED_MODEL = "nomic-embed-text";

export const OLLAMA_GEN_ENDPOINT = "/api/generate";
export const OLLAMA_GEN_MODEL = process.env.OLLAMA_MODEL || "mistral";

This tells the app:

Where to read documents from
Where to save the index
Which model to use for embeddings
Which model to use for answers

Step 5: Read and Split Documents

LLMs work better when we give them small, focused pieces of text.

So we split long documents into smaller parts called chunks.

export function chunkText(text, size = 900, overlap = 150) {
  const chunks = [];
  let start = 0;

  while (start < text.length) {
    const end = start + size;
    chunks.push(text.slice(start, end));
    start += size - overlap;
  }

  return chunks.map((chunk) => chunk.trim()).filter(Boolean);
}

Here:

size = 900 means each chunk is around 900 characters
overlap = 150 means the next chunk repeats 150 characters from the previous one

The overlap is useful because important meaning can sit between two chunks.

Example:

Chunk 1: characters 0 to 900
Chunk 2: characters 750 to 1650
Chunk 3: characters 1500 to 2400

Step 6: Create Embeddings

An embedding is a list of numbers that represents the meaning of text.

For example, this sentence:

The product supports SSO on Business and Enterprise plans.

is converted into a vector:

[0.12, -0.04, 0.89, ...]

The exact numbers are not important for us.

What matters is this:

Similar text gets similar embeddings.

Why Do We Need `nomic-embed-text`?

Mistral is good at generating answers, but we also need a way to search our documents by meaning.

That is what nomic-embed-text does.

It converts text into embeddings so our app can compare:

The user's question
The chunks from our documents

Without embeddings, our app would only do simple keyword matching.

For example, if the document says:

The product supports SSO on the Business and Enterprise plans.

and the user asks:

Which subscription includes single sign-on?

keyword search may miss the connection because the words are different.

But embeddings can understand that SSO and single sign-on are related.

So in this project:

nomic-embed-text is used for search
mistral is used for answering

That means a question like:

Which plans have SSO?

should be close to the document sentence:

The product supports SSO on the Business and Enterprise plans.

Here is the embedding function:

export async function embed(text) {
  const response = await fetch("http://localhost:11434/api/embeddings", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "nomic-embed-text",
      prompt: text
    })
  });

  const data = await response.json();
  return data.embedding;
}

We use this same function for both:

Document chunks
User questions

That is how we compare a question with our documents.

Step 7: Build the Index

Now we create the index.

The index is a JSON file that stores:

The document name
The chunk text
The embedding for that chunk

export async function buildIndex() {
  const docs = await readDocuments();
  const records = [];

  for (const doc of docs) {
    const chunks = chunkText(doc.text);

    for (const [i, chunk] of chunks.entries()) {
      records.push({
        id: `${doc.source}#${i}`,
        source: doc.source,
        text: chunk,
        embedding: await embed(chunk)
      });
    }
  }

  await fs.writeFile("data/index.json", JSON.stringify(records, null, 2));
  return records.length;
}

Run:

npm run index

This creates:

data/index.json

Now your documents are searchable by meaning, not just by exact words.

Step 8: Search the Best Chunks

When the user asks a question, we need to find the document chunks that are closest to that question.

To do that, we:

Convert the question into an embedding
Compare it with every saved document embedding
Sort the results
Keep the best matches

The comparison uses cosine similarity:

function cosineSimilarity(a, b) {
  let dot = 0;
  let normA = 0;
  let normB = 0;

  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }

  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

Then we search the index:

export async function search(query, limit = 4) {
  const raw = await fs.readFile("data/index.json", "utf8");
  const index = JSON.parse(raw);

  const queryEmbedding = await embed(query);

  return index
    .map((item) => ({
      ...item,
      score: cosineSimilarity(queryEmbedding, item.embedding)
    }))
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

The result is a small set of document chunks that are most likely to contain the answer.

Step 9: Give Context to Mistral

Now we have the useful document chunks.

Next, we send them to Mistral with the user's question.

The prompt looks like this:

const prompt = `
Answer using only the context below.
If the answer is missing, say you do not know.

Context:
${context}

Question:
${question}
`;

This line is very important:

Answer using only the context below.

It tells the model not to guess.

Then we call Ollama's generation API:

const resp = await fetch("http://localhost:11434/api/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "mistral",
    prompt,
    max_tokens: 512,
    temperature: 0.2
  })
});

temperature: 0.2 makes the answer more focused and less random.

Step 10: Ask a Question

Now run:

npm run ask:ollama -- "What plans support SSO?"

Example answer:

The product supports SSO on the Business and Enterprise plans.

This answer came from the local document.

Mistral did not need to already know your product FAQ. The RAG pipeline found the right context and gave it to the model.

The Full RAG Flow

Here is the complete flow again:

1. Put documents in data/docs
2. Split documents into chunks
3. Convert chunks into embeddings
4. Save embeddings in data/index.json
5. User asks a question
6. Convert the question into an embedding
7. Find the most similar chunks
8. Add those chunks to the prompt
9. Ask Mistral to answer using that context

That is RAG.

Search first. Generate second.

Why This Local Version Is Useful

This project is intentionally simple.

It uses a JSON file instead of a vector database. That makes it easier to understand what is happening.

For learning, this is perfect.

For production, you may later replace data/index.json with a vector database such as:

Chroma
Qdrant
Weaviate
pgvector

But the core idea stays the same:

Store embeddings -> Search similar chunks -> Send context to the LLM

Conclusion

RAG is one of the most useful patterns for building practical AI apps.

It helps LLMs answer using your data without retraining the model.

In this article, we built a local RAG app with:

Ollama
Mistral
Node.js
nomic-embed-text
Local documents
A JSON-based vector index

The main idea is simple:

Search your documents first, then let the LLM answer with that context.

Complete implementation:

https://github.com/gaurav101/ai-experiment/tree/main/rag

Setup references:

MCP Server and RAG: A Simple Introduction for Developers

Gaurav Kumar Singh — Fri, 12 Jun 2026 14:46:51 +0000

AI tools are becoming more useful for developers, but they still have one big problem: they do not automatically know your private files, your latest docs, your local database, or your project rules.

Two ideas help solve this:

RAG gives AI the right information before it answers.
MCP servers let AI tools safely use your local tools and data.

Together, they make AI feel less like a generic chatbot and more like a useful coding partner.

What Is RAG?

RAG means retrieval-augmented generation.

In simple words, RAG means:

A user asks a question.
Your app searches useful documents.
Your app sends the best matching text to the AI.
The AI answers using that text.

Example:

User: What is our refund policy?

RAG search finds:
"Refunds are allowed within 14 days of purchase."

AI answer:
"Your refund policy allows refunds within 14 days of purchase."

Without RAG, the AI may guess. With RAG, it can answer from your real data.

What Is an MCP Server?

MCP means Model Context Protocol.

Think of an MCP server as a small local app that gives AI tools extra abilities.

For example, an MCP server can let an AI tool:

Search your local documentation.
Read selected project files.
Query a database.
Call an internal API.
Look up company rules.

The AI does not need direct access to everything. It calls a specific tool, and you control what that tool can do.

Example MCP tool:

Tool name: search_docs
Input: "How do I reset my password?"
Output: The best matching paragraphs from your documentation.

How RAG and MCP Work Together

RAG is the search brain. MCP is the bridge.

Here is the simple flow:

Claude, Codex, or another AI tool
        |
        asks MCP tool: search_docs("refund policy")
        |
Local MCP server
        |
Searches your local RAG index
        |
Returns useful document chunks
        |
AI writes a better answer

This is powerful because the same local RAG system can work with many AI tools.

Why Developers Benefit

MCP and RAG help developers in practical ways:

Better answers: AI uses your real docs instead of guessing.
Less copy-paste: You do not need to paste long files into chat.
Private by design: Your search index can stay on your computer.
Reusable tools: Build one search_docs tool and use it in Claude, Codex, Cursor, or other MCP clients.
Project-aware AI: The assistant can understand your codebase rules, API docs, and team notes.

For example, instead of asking:

Read all these files and explain our auth flow...

You can ask:

Search the local docs and explain how login works.

The AI calls your MCP tool, gets the right context, and answers faster.

Why JavaScript Is a Great Choice

JavaScript is one of the easiest choices for building beginner-friendly MCP and RAG tools.

Here is why:

Most developers already know some JavaScript.
Node.js is simple to run locally.
AI SDKs support JavaScript well.
MCP has a JavaScript/TypeScript SDK.
You can reuse the same code in CLI tools, servers, and web apps.

A small JavaScript RAG function can look like this:

async function answerQuestion(question) {
  const chunks = await searchLocalDocs(question);
  const context = chunks.join("\n\n");

  return askAI(`
    Use this context to answer:
    ${context}

    Question:
    ${question}
  `);
}

And an MCP tool can expose that search function:

server.registerTool(
  "search_docs",
  {
    description: "Search local project documents"
  },
  async ({ question }) => {
    const results = await searchLocalDocs(question);
    return {
      content: [{ type: "text", text: results.join("\n\n") }]
    };
  }
);

You do not need to start with a complex database. Beginners can use:

Text files for documents.
JSON for a small search index.
Ollama for local embeddings.
Node.js for the MCP server.

Later, you can upgrade to SQLite, Postgres, Chroma, LanceDB, or another vector database.

A Simple Example

Imagine you have a folder like this:

docs/
  refund-policy.txt
  api-guide.md
  onboarding-notes.md

You build a JavaScript RAG app that searches those files. Then you expose it as an MCP server.

Now you can ask Codex or Claude:

Use my local docs to explain how refunds work.

The AI can call your local search tool and answer from your files.

Final Thought

RAG makes AI more accurate. MCP makes AI more connected. JavaScript makes both easier to build.

If you are a beginner, start small: search a few text files, return the best matches, and connect that search to one AI tool. Once that works, you already understand the core idea behind many real-world AI developer tools.

Build a tiny MCP server in JavaScript -Claude, Codex friendly

Gaurav Kumar Singh — Fri, 12 Jun 2026 11:07:19 +0000

TL;DR — Ship a tiny server that exposes tools to LLMs using the Model Context Protocol (MCP). This guide shows a minimal, runnable example, explains each part, and covers common pitfalls (ESM imports, transports, adapters).

Why this matters

MCP lets models call real tools (fetching data, running commands) instead of hallucinating.
It’s a great way to extend models with live data: notifications, GitHub lookups, database queries, etc.

What you'll get

A working server (index.js) exposing a single tool: get-repo-stats
Quick instructions to run locally (stdio) or remotely (HTTP)
Short adapter patterns for OpenAI (Codex/GPT), Google Gemini, and Anthropic Claude

Quick checklist

Node 18+
npm install (project already depends on @modelcontextprotocol/sdk and zod)
Add "type": "module" to package.json for ESM

Quick start (copy-paste)

1) Install deps or verify existing:

npm install

2) Run locally:

node index.js

If you see a MODULE_TYPELESS_PACKAGE_JSON warning, add "type": "module" to package.json (example below).

Minimal index.js (copy to your repo)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const BASE_URL = "https://api.github.com";

const server = new McpServer({ name: 'github-stats-server', version: '1.0.0' });

server.tool(
  'get-repo-stats',
  'Get star count, fork count, and open issues for a GitHub repo',
  {
    owner: z.string().describe("GitHub username or org"),
    repo: z.string().describe("Repository name"),
  },
  async ({ owner, repo }) => {
    const res = await fetch(`${BASE_URL}/repos/${owner}/${repo}`);
    if (!res.ok) {
      return { content: [{ type: 'text', text: `Could not find repo ${owner}/${repo}` }] };
    }
    const data = await res.json();
    return {
      content: [{ type: 'text', text: `${owner}/${repo} — ⭐ ${data.stargazers_count} · 🍴 ${data.forks_count} · 🐛 ${data.open_issues_count}` }]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Code walkthrough

McpServer: high-level API to register tools and handle protocol
server.tool(name, description, schema, handler): register callable tools. Use zod for input validation.
Handler returns a result shaped like

{ content: [ { type: 'text', text: '...' } ] }

StdioServerTransport: easiest local transport — reads/writes over stdin/stdout
Call server.connect(transport) after registering tools so the initialization advertises available tools

ESM / import gotchas

Add "type": "module" to package.json so Node treats your files as ESM and avoids MODULE_TYPELESS_PACKAGE_JSON warning.
Use package export entrypoints and include .js extension:
- Good: import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
- Bad: deep imports to dist/esm/… — Node may fail to resolve or duplicate path segments.

Example package.json snippet

{
  "name": "mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.29.0",
    "zod": "^3.25"
  }
}

Transports at a glance

stdio: local adapters (Claude Desktop, local testing). Simpler to run.
StreamableHTTP: model host calls an HTTP endpoint (preferred for cloud deployments).
WebSocket: long-lived bidirectional connections for advanced flows.

how to connect an LLM

OpenAI / Codex (function-calling flow)

Add a Local MCP Server to Codex

Codex can use local MCP servers through STDIO. MCP configuration is stored in
~/.codex/config.toml by default, or in a project-level .codex/config.toml
for trusted projects.

Option 1: Add with the Codex CLI

codex mcp add my-local-git-stat-server -- node /path/to/your/project/index.js

If the server needs environment variables:

codex mcp add my-local-server --env -- node /path/to/your/project/index.js

Option 2: Add Manually in `config.toml`

Open ~/.codex/config.toml and add:

[mcp_servers.my-local-server]
command = "node"
args = ["/path/to/your/project/index.js"]

Verify the Server

Restart Codex, then check active MCP servers from the Codex TUI:

/mcp

You can also inspect available MCP commands with:

codex mcp --help

Google Gemini

If the hosting environment supports HTTP callbacks, use StreamableHTTPClientTransport. Otherwise, run a bridge process that translates Gemini function calls into MCP client calls.

Anthropic Claude

For local Claude Desktop: the desktop app can spawn your server process and use stdio. Configure the desktop app to run node /path/index.js.
For hosted Claude integrations, prefer HTTP transport.

Small adapter sketch (pseudo)

// spawn server then connect client-facing logic
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({ command: 'node', args: ['index.js'] });
await transport.start();
const client = new Client({ name: 'bridge', version: '1.0.0' });
await client.connect(transport);

// When model asks for a tool: client.callTool({ method: 'get-repo-stats', params: { owner, repo } })

Using with OpenAI (Codex / GPT function-calling)

Recommended patterns

Local/testing: use stdio transport + StdioClientTransport (spawn the server as a child process from your adapter).
Hosted: expose your MCP server with StreamableHTTPTransport and let your adapter call it via StreamableHTTPClientTransport.

Minimal adapter sketch (pseudo)

// adapter-openai.js — high level sketch
import OpenAI from 'openai'; // or your HTTP wrapper
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; // or StreamableHTTPClientTransport


// spawn local server and connect client
const transport = new StdioClientTransport({ command: 'node', args: ['index.js'] });
await transport.start();
const client = new Client({ name: 'openai-bridge', version: '1.0.0' });
await client.connect(transport);

// When a model function call arrives (pseudo):
async function handleModelFunctionCall(name, params) {
  // Map function name to your tool method (e.g., 'get-repo-stats')
  const toolResult = await client.callTool({ method: `tools/${name}`, params });
  // Convert the MCP result into the expected function-response string or JSON and return it
  return toolResult;
}

// Use your OpenAI SDK to call model and route function-calls through handleModelFunctionCall

Notes

Keep the mapping from model function names to MCP tool names explicit and documented.
Don't commit API keys — use env vars, and sanitize when spawning processes.

Using with Anthropic Claude (Claude Desktop)

Local desktop (stdio) — easiest

1. Add your server to Claude Desktop configuration (absolute path to your index.js):

{
  "mcpServers": {
    "github-stats": {
      "command": "node",
      "args": ["/absolute/path/to/index.js"]
    }
  }
}

2. Ensure your project has "type": "module" in package.json and your imports use .js extensions.

3. Start / restart Claude Desktop. The desktop app will spawn your server and talk over stdin/stdout. Ask Claude: "What are the stats for facebook/react?" and it should call the get-repo-stats tool.

Hosted Claude / remote

If your Claude hosting supports HTTP callbacks, host the MCP server behind an HTTP wrapper and use StreamableHTTPClientTransport on the model side.

Testing tips

Run the server with node --trace-warnings index.js when debugging import/ESM issues.
Use a small script that calls client.listTools() after connecting to verify the advertised tools.

Debugging checklist

ERR_MODULE_NOT_FOUND for deep path? Switch to @modelcontextprotocol/sdk/server/mcp.js imports.
MODULE_TYPELESS_PACKAGE_JSON? Add "type": "module" to package.json.
Run node --trace-warnings index.js for resolution traces.

Security & deployment (brief)

If exposing HTTP, require auth (API key, OAuth) and use TLS.
When spawning child processes, sanitize environment and avoid leaking secrets.
Limit resource usage (timeouts, concurrency) on tools that call external services.

Make it yours (next steps)

Add more tools (issues, releases, search)
Add authentication for private GitHub repos
Wrap as an npm CLI and add a config file for easy local installs

References & where to look

SDK examples: node_modules/@modelcontextprotocol/sdk/dist/esm/examples
Official docs: https://modelcontextprotocol.io
example code : https://github.com/gaurav101/ai-experiment

[Boost]

Gaurav Kumar Singh — Tue, 02 Jun 2026 14:46:00 +0000

Gaurav Kumar Singh

Jun 2

Architectural Mastery in Node.js: Designing a Robust, Multi-Platform NPM Package

#node #typescript #designpatterns #architecture

8 min read

Architectural Mastery in Node.js: Designing a Robust, Multi-Platform NPM Package

Gaurav Kumar Singh — Tue, 02 Jun 2026 14:44:37 +0000

When building cross-platform Node.js applications, developer tools, or CLI utilities, managing environmental variance is a common challenge. Operating systems rely on different binaries, network utilities vary, and error-handling mechanisms change depending on the runtime context.

Handling these variations with deeply nested conditional logic (if/else or switch statements) makes your application state brittle, difficult to test, and painful to scale.

This engineering guide demonstrates how to architect a clean, testable, and robust cross-platform Node.js utility using the Strategy Pattern and the Factory Pattern.

Production Resources & Quick Start

The finished project discussed in this guide is fully implemented, open-source, and available for use in your production pipelines:

GitHub Repository: gaurav101/port-kill
Live Interactive Documentation: port-kill.vercel.app
NPM Package: Install the package directly via npm:

npm i @gks101/port-kill

1. The Real-World Engineering Problem: `EADDRINUSE`

Every developer has encountered the notorious local server collision:

Error: listen EADDRINUSE: address already in use :::3000

To resolve this programmatically across platforms, an application must execute two distinct steps:

Discovery: Identify the Process IDs (PIDs) listening on a target port.
Termination: Safely and effectively kill those processes.

However, the native tools available to execute these actions vary radically across operating systems:

Operating System	Process Discovery Mechanism	Process Termination Mechanism
macOS / Linux	`lsof -t -i :[port]` or `fuser`	`kill -[SIGNAL] [pids]`
Windows	`netstat -ano`	`taskkill /F /T /PID [pid]`

The Naive Anti-Pattern

Placing all of this conditional logic inside a single orchestrator function creates a fragile codebase:

// ❌ ANTI-PATTERN: Brittle cross-platform orchestration
export function killPortNaive(port: number) {
  if (process.platform === 'win32') {
    // Windows netstat execution
    // Complex regex string parsing for netstat table rows
    // Individual taskkill subprocess spawning
  } else {
    // Unix lsof execution with fallback to fuser
    // Parsing space-separated or newline-separated PID strings
    // POSIX signal mapping and kill execution
  }
}

This structural anti-pattern couples your core business logic to low-level OS command strings, breaks the Single Responsibility Principle, makes unit testing impossible without complex environment mocking, and introduces significant maintenance risks.

2. Structural Blueprints: Strategy & Factory

To decouple orchestration from platform mechanics, we introduce a clear division of labor using two complementary design patterns:

The Strategy Pattern (Behavioral)

Core Philosophy: Defines a family of interchangeable algorithms, encapsulating each one inside a dedicated class that implements a uniform contract.
Application Goal: Standardize how the application communicates with the OS layer, regardless of whether it targets a Windows kernel or a POSIX terminal.

The Factory Pattern (Creational)

Core Philosophy: Centralizes instantiation logic, abstracting away the concrete classes and configurations required to construct an operational object.
Application Goal: Evaluate runtime constraints (such as process.platform) and supply the correct strategy configuration seamlessly to the application layer.

System Architecture Topology

The following diagram illustrates how these patterns isolate responsibilities across the application lifecycle:

   [ Client Layer: CLI / Programmatic API ]
                      │
                      ▼
       [ Core Service Orchestrator ]
                      │
                      ├─► [ PlatformStrategyFactory.create() ]
                      │                │
                      │                ├─► returns WindowsPortStrategy
                      │                └─► returns UnixPortStrategy
                      │
                      ▼
        [ Execution via Abstract Contract ]
          (findPids / terminatePids)
                      │
                      ▼
         [ Platform Command Factory ]
                      │
                      ├─► UnixCommandFactory   ──► [{ binary: 'lsof', args: [...] }]
                      └─► WindowsCommandFactory ──► [{ binary: 'netstat', args: [...] }]
                      │
                      ▼
         [ Decoupled Command Runner ] (spawnSync)

3. Designing Core Domain Contracts and Typings

Before writing structural code, establish clear execution boundaries. Define the input parameters, telemetry outputs, and execution schemas using TypeScript interfaces.

// Domain Types: options and results contracts
export interface PortKillOptions {
  port?: number | number[];
  force?: boolean;
  signal?: 'SIGKILL' | 'SIGTERM' | 'SIGINT' | string;
  verbose?: boolean;
  logger?: (message: string, level?: 'info' | 'warn' | 'error' | 'debug') => void;
  dryRun?: boolean;
}

export interface PortKillResult {
  port: number;
  success: boolean;
  pids: number[];
  message: string;
  error?: string;
  timestamp: string;
}

export interface PlatformCommand {
  binary: string;
  args: string[];
}

export interface CommandRunResult {
  stdout: string;
  success: boolean;
  error?: string;
}

export type PortKillLog = (msg: string, lvl?: 'info' | 'warn' | 'error' | 'debug') => void;

4. Decoupling Execution: The Command Layer

To insulate the system from shell injection vulnerabilities and shell interpolation bugs, avoid raw string executions. Instead, treat shell processes as structured objects executed via a dedicated runner.

Step 1: The Command Factory Interface

This creational boundary ensures that structural variations in CLI syntax remain completely invisible to the operational strategy layer.

export interface PlatformCommandFactory {
  createFindCommands(port: number): PlatformCommand[];
  createKillCommands(pids: number[], signalOrForce: string | boolean): PlatformCommand[];
}

Step 2: Implementing the Unix Command Factory

export class UnixCommandFactory implements PlatformCommandFactory {
  createFindCommands(port: number): PlatformCommand[] {
    return [
      { binary: 'lsof', args: ['-t', '-n', '-i', `:${port}`] },
      { binary: 'fuser', args: [`${port}/tcp`] }
    ];
  }

  createKillCommands(pids: number[], signalOrForce: string | boolean): PlatformCommand[] {
    const signal = typeof signalOrForce === 'string' ? signalOrForce : 'SIGKILL';
    return [
      { binary: 'kill', args: [`-${signal}`, ...pids.map(String)] }
    ];
  }
}

Step 3: Implementing the Windows Command Factory

export class WindowsCommandFactory implements PlatformCommandFactory {
  createFindCommands(port: number): PlatformCommand[] {
    // netstat provides a full connection matrix table
    return [{ binary: 'netstat', args: ['-ano'] }];
  }

  createKillCommands(pids: number[], signalOrForce: string | boolean): PlatformCommand[] {
    const useForce = !!signalOrForce;
    const baseArgs = useForce ? ['/F', '/T'] : ['/T'];

    // Windows taskkill handles targeted process compilation atomically per PID
    return pids.map(pid => ({
      binary: 'taskkill',
      args: [...baseArgs, '/PID', String(pid)]
    }));
  }
}

Step 4: The Stateless Command Runner

The runner handles the underlying mechanics of subprocess creation. It accepts a structured PlatformCommand object and returns a standardized result.

import { spawnSync } from 'child_process';

export function runCommand(command: PlatformCommand, log: PortKillLog): CommandRunResult {
  log(`Executing: ${command.binary} ${command.args.join(' ')}`, 'debug');

  const result = spawnSync(command.binary, command.args, {
    shell: false, // Prevents shell command injection vulnerabilities
    encoding: 'utf8',
    stdio: ['pipe', 'pipe', 'pipe']
  });

  if (!result.error && result.status === 0) {
    return { stdout: result.stdout || '', success: true };
  }

  return {
    stdout: result.stdout || '',
    success: false,
    error: result.error?.message || result.stderr || 'Execution failure'
  };
}

5. Implementing Behavioral Architecture: The Strategy Pattern

With commands decoupled, we establish the algorithmic contract for platform strategy execution.

export interface TerminationResult {
  success: boolean;
  error?: string;
}

export interface PlatformStrategy {
  readonly name: 'unix' | 'windows';
  findPids(port: number, log: PortKillLog): number[];
  terminatePids(pids: number[], options: PortKillOptions, log: PortKillLog): TerminationResult;
}

The Unix Strategy Implementation

This strategy manages Unix-specific workflows, including falling back from lsof to fuser and sanitizing protected system processes.

export class UnixPortStrategy implements PlatformStrategy {
  readonly name = 'unix' as const;

  constructor(private readonly commandFactory: PlatformCommandFactory) {}

  findPids(port: number, log: PortKillLog): number[] {
    const [lsofCmd, fuserCmd] = this.commandFactory.createFindCommands(port);

    // Fallback Sequence Implementation
    const lsofResult = runCommand(lsofCmd, log);
    if (lsofResult.success && lsofResult.stdout.trim()) {
      return this.parsePids(lsofResult.stdout);
    }

    log('lsof failed or returned empty; executing fuser fallback optimization...', 'info');
    const fuserResult = runCommand(fuserCmd, log);
    return this.parsePids(fuserResult.stdout);
  }

  terminatePids(pids: number[], options: PortKillOptions, log: PortKillLog): TerminationResult {
    const targetSignal = options.signal || (options.force ? 'SIGKILL' : 'SIGTERM');
    const filteredPids = this.filterProtectedPids(pids, log);

    if (filteredPids.length === 0) return { success: true };

    const [killCmd] = this.commandFactory.createKillCommands(filteredPids, targetSignal);
    const result = runCommand(killCmd, log);

    return { success: result.success, error: result.error };
  }

  private parsePids(stdout: string): number[] {
    return stdout
      .split(/[\s\n]+/)
      .map(token => parseInt(token.trim(), 10))
      .filter(pid => !isNaN(pid));
  }

  private filterProtectedPids(pids: number[], log: PortKillLog): number[] {
    const currentPid = process.pid;
    const parentPid = process.ppid;
    return pids.filter(pid => {
      if (pid === currentPid || pid === parentPid) {
        log(`Process protection triggered for protected PID: ${pid}`, 'warn');
        return false;
      }
      return true;
    });
  }
}

The Windows Strategy Implementation

This strategy manages Windows-specific flows, handling tabular netstat text parsing and executing targeted taskkill loops.

export class WindowsPortStrategy implements PlatformStrategy {
  readonly name = 'windows' as const;

  constructor(private readonly commandFactory: PlatformCommandFactory) {}

  findPids(port: number, log: PortKillLog): number[] {
    const [netstatCmd] = this.commandFactory.createFindCommands(port);
    const result = runCommand(netstatCmd, log);

    if (!result.success || !result.stdout) return [];

    return this.parseNetstat(result.stdout, port);
  }

  terminatePids(pids: number[], options: PortKillOptions, log: PortKillLog): TerminationResult {
    const forceFlag = options.force ?? true;
    const commands = this.commandFactory.createKillCommands(pids, forceFlag);
    const errors: string[] = [];

    for (const cmd of commands) {
      const res = runCommand(cmd, log);
      if (!res.success) errors.push(res.error || `Failed to terminate PID`);
    }

    return {
      success: errors.length === 0,
      error: errors.length > 0 ? errors.join('; ') : undefined
    };
  }

  private parseNetstat(stdout: string, targetPort: number): number[] {
    const pids = new Set<number>();
    const lines = stdout.split(/[\r\n]+/);

    // Look for matching tokens: Local Address matching :[port]
    const portMatchRegex = new RegExp(`[:\\]]${targetPort}$`);

    for (const line of lines) {
      const parts = line.trim().split(/\s+/);
      if (parts.length < 5) continue;

      const localAddress = parts[1]; 
      const pidToken = parts[parts.length - 1];
      const pid = parseInt(pidToken, 10);

      if (portMatchRegex.test(localAddress) && !isNaN(pid) && pid > 0) {
        pids.add(pid);
      }
    }

    return Array.from(pids);
  }
}

6. Centralizing Instantiation: The Strategy Factory

The factory completely abstracts setup details away from the application workflow. By exposing an optional parameter with a sensible default, we keep production use clean while allowing effortless platform mocking during testing.

export class PlatformStrategyFactory {
  /**
   * Instantiates the correct platform strategy configuration matrix.
   * @param platform Target node environment runtime key override.
   */
  static create(platform: NodeJS.Platform = process.platform): PlatformStrategy {
    if (platform === 'win32') {
      return new WindowsPortStrategy(new WindowsCommandFactory());
    }

    // Default runtime routing maps seamlessly to POSIX environments (Linux/macOS)
    return new UnixPortStrategy(new UnixCommandFactory());
  }
}

7. Orchestration Layer Implementation

The orchestrator manages the high-level business workflow. It coordinates logging, queries the factory for the proper strategy, handles dryRun evaluation, and builds the final telemetry output.

export function killSinglePort(port: number, options: PortKillOptions = {}): PortKillResult {
  const timestamp = new Date().toISOString();
  const log: PortKillLog = options.logger || ((msg, lvl = 'info') => {
    if (options.verbose) console.log(`[${lvl.toUpperCase()}] ${msg}`);
  });

  // The Orchestrator interacts solely with abstract operational models
  const strategy = PlatformStrategyFactory.create();
  log(`Detected platform strategy context: ${strategy.name}`, 'info');

  const pids = strategy.findPids(port, log);

  if (pids.length === 0) {
    return { port, success: true, pids: [], message: `Port ${port} is clear.`, timestamp };
  }

  if (options.dryRun) {
    return { 
      port, 
      success: true, 
      pids, 
      message: `Dry-run execution mode. Identified target processes: ${pids.join(', ')}`, 
      timestamp 
    };
  }

  const termination = strategy.terminatePids(pids, options, log);

  return {
    port,
    success: termination.success,
    pids,
    message: termination.success 
      ? `Successfully cleared port ${port} by terminating PIDs: ${pids.join(', ')}`
      : `Partial or total failure clearing port ${port}. Error encountered: ${termination.error}`,
    error: termination.error,
    timestamp
  };
}

8. Exposing Clean Programmatic and CLI Interfaces

Because the factory and strategy mechanics absorb all cross-platform complexities internally, your external interfaces remain clean and user-friendly.

The Programmatic Module API

Downstream developers can consume your module cleanly using modern async/await patterns:

export function portKillSync(ports: number | number[], options: PortKillOptions = {}): PortKillResult[] {
  const targets = Array.isArray(ports) ? ports : [ports];
  return targets.map(port => {
    try {
      return killSinglePort(port, options);
    } catch (err: any) {
      return {
        port,
        success: false,
        pids: [],
        message: `Unhandled runtime error targeting port ${port}`,
        error: err?.message || String(err),
        timestamp: new Date().toISOString()
      };
    }
  });
}

export async function portKill(ports: number | number[], options: PortKillOptions = {}): Promise<PortKillResult[]> {
  return new Promise((resolve) => {
    process.nextTick(() => resolve(portKillSync(ports, options)));
  });
}

The Thin CLI Wrapper

#!/usr/bin/env node
import { portKillSync } from './index';

export function parseAndRunCli(args: string[]): void {
  const rawPorts = args.filter(arg => !arg.startsWith('--'));
  const flags = args.filter(arg => arg.startsWith('--'));

  if (rawPorts.length === 0 || flags.includes('--help')) {
    console.log(`
      Usage: port-kill <port1> <port2> [options]
      Options:
        --force    Force process termination
        --verbose  Enable extended telemetry logs
        --dry-run  Discover target processes without terminating them
    `);
    process.exit(0);
  }

  const targetPorts = rawPorts.map(Number);
  const options = {
    force: flags.includes('--force'),
    verbose: flags.includes('--verbose'),
    dryRun: flags.includes('--dry-run'),
  };

  const operationalReports = portKillSync(targetPorts, options);
  const exitCode = operationalReports.every(r => r.success) ? 0 : 1;

  console.table(operationalReports);
  process.exit(exitCode);
}

parseAndRunCli(process.argv.slice(2));

9. Deterministic Unit Testing Strategy

By isolating implementation details behind clean interfaces, you can thoroughly unit test each strategy and factory without needing multiple physical environments.

import { PlatformStrategyFactory } from './platform/factory';
import { WindowsPortStrategy } from './platform/strategies';
import { UnixPortStrategy } from './platform/strategies';

describe('Design Pattern Strategy & Factory Verification Suite', () => {

  it('should instantiate the correct platform strategy based on environment signatures', () => {
    const winStrategy = PlatformStrategyFactory.create('win32');
    expect(winStrategy).toBeInstanceOf(WindowsPortStrategy);
    expect(winStrategy.name).toBe('windows');

    const darwinStrategy = PlatformStrategyFactory.create('darwin');
    expect(darwinStrategy).toBeInstanceOf(UnixPortStrategy);
    expect(darwinStrategy.name).toBe('unix');
  });

  it('should execute isolated tests on Unix PID parsing logic without environmental side effects', () => {
    const mockStrategy = PlatformStrategyFactory.create('linux') as UnixPortStrategy;
    // You can now inject custom mock runners or sample standard output structures 
    // to verify parsing behavior deterministically without affecting the host runtime.
  });
});

Summary Mental Model

To effectively apply these structural patterns to your future Node.js projects, keep this clear separation of concerns in mind:

The Factory decides: It assesses runtime context to construct the proper operational dependencies.
The Strategy behaves: It encapsulates environment-specific rules, syntax, and data parsing logic behind a unified contract.
The Service coordinates: It manages core business logic, handles option states (like dryRun), and acts as the workflow engine.
The Runner executes: It isolates low-level subprocess spawning safely and uniformly across the codebase.

Explore the Live Implementation

To review the complete production codebase, run validation suites, or check integration examples, explore the following resources:

Source Code: GitHub Repository
Package Distribution: Official npm Package Registry
Comprehensive Documentation Portal: port-kill.vercel.app

Internals of useLocalStorageState Hook

Gaurav Kumar Singh — Sun, 24 May 2026 14:59:48 +0000

How My React useLocalStorageState/localStorage Hook Works Internally

I built @gks101/localyx to make localStorage easier to use in React.

The main hook is called useLocalStorageState.

It lets you write code that feels like useState, but the value is also saved in the browser.

Package:

npm install @gks101/localyx

GitHub repo:

https://github.com/gaurav101/localyx

Working demo:

https://localyx.vercel.app/

In this article, I will explain how the hook works internally in simple steps.

This article is for React beginners who already know basic useState and useEffect.

The Basic Idea

Normal React state looks like this:

const [theme, setTheme] = useState("light");

But this value is lost when the page refreshes.

localStorage can save data after refresh, but using it directly can become messy.

So the hook gives us this:

const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

It returns:

theme: the current value
setTheme: a function to update the value
clearTheme: a function to remove the value

Internally, the hook connects React state with localStorage.

The Stored Data Shape

The hook does not save only the value.

It saves an object like this:

{
  v: value,
  t: timestamp
}

In the source code, this is called StorageEntry.

interface StorageEntry<T> {
  v: T;
  t?: number;
}

Here:

v means the real value
t means the time when the value was saved

The timestamp is optional.

It is only needed when TTL expiry is used.

TTL means "Time To Live". It tells the hook when a value should expire.

The Options Object

The hook accepts an optional third argument.

useLocalStorageState("theme", "light", options);

The options include:

{
  ttl?: number;
  ttlStrategy?: "absolute" | "sliding";
  namespace?: string;
  onExpire?: (ctx) => void;
  encrypt?: ((raw: string) => string) | null;
  decrypt?: ((raw: string) => string) | null;
  serializer?: {
    stringify: (value) => string;
    parse: (value) => value;
  };
}

These options let the hook support expiry, namespaces, custom encoding, and custom parsing.

Browser Safety

localStorage only exists in the browser.

It does not exist during server-side rendering.

That is why the hook has a helper called isBrowser.

const isBrowser = (): boolean =>
  typeof window !== "undefined" && typeof localStorage !== "undefined";

This protects the code from crashing in tools like Next.js.

Before reading or writing localStorage, the hook checks if it is running in the browser.

Safe Read, Write, and Delete Helpers

The hook uses small wrapper functions around localStorage.

function lsRead(key: string): string | null {
  try {
    return isBrowser() ? localStorage.getItem(key) : null;
  } catch {
    return null;
  }
}

There are also helpers for writing and deleting.

Why use wrappers?

Because localStorage can fail in some cases.

For example:

browser storage is disabled
storage is full
the app is running outside the browser
the saved data is not valid

The wrapper functions make the hook safer.

Instead of crashing the app, the hook falls back to the initial value.

Creating the Final Storage Key

The hook supports namespaces.

This means the user can write:

useLocalStorageState("profile", null, {
  namespace: "my-app",
});

Internally, the key becomes:

my-app:profile

The helper looks like this:

function resolveStorageKey(key: string, namespace?: string): string {
  return namespace ? `${namespace}:${key}` : key;
}

This is useful when a project has many localStorage values.

It helps avoid key conflicts.

Encoding and Decoding the Value

Before the hook saves data, it turns the data into a string.

By default, it uses JSON:

JSON.stringify(entry)

Then it can encode the string.

By default, the hook uses Base64 encoding.

Base64 is not real encryption. It only makes the saved value less readable.

If someone needs real security, they should pass custom encrypt and decrypt functions.

The hook also allows plain JSON:

useLocalStorageState("theme", "light", {
  encrypt: null,
  decrypt: null,
});

When encrypt and decrypt are null, the hook skips encoding and decoding.

Reading the Value on First Render

This is one of the most important parts.

When the component first renders, the hook tries to read from localStorage.

const [state, setInternalState] = useState<T>(() => readStorage());

Notice that readStorage is passed as a function.

This is called lazy initialization.

It means React only calls readStorage during the first render.

This is better than reading from localStorage on every render.

Inside readStorage, the hook does these steps:

Read the raw value from localStorage.
If there is no value, return the initial value.
Decode the value if needed.
Parse the JSON.
If parsing fails, delete the broken value.
If the value is expired, delete it.
If the value is valid, return entry.v.

So the component receives the real saved value.

Handling Broken Data

Sometimes localStorage may contain broken data.

For example, maybe the value was edited manually in browser devtools.

The hook uses parseStorageEntry for this.

function parseStorageEntry(raw, decode, parse) {
  try {
    const decoded = decode ? decode(raw) : raw;
    return parse(decoded);
  } catch {
    return null;
  }
}

If parsing fails, it returns null.

Then the hook removes the invalid value and returns the initial value.

This keeps the app stable.

Updating the Value

The hook gives us a setter function.

setTheme("dark");

Internally, the setter does more work than normal useState.

It:

Gets the next value.
Wraps it in a storage entry.
Adds a timestamp if TTL is enabled.
Converts it to a string.
Encodes it if needed.
Saves it to localStorage.
Updates React state.
Sends a sync event.

The hook also supports updater functions:

setTheme((oldTheme) => oldTheme === "light" ? "dark" : "light");

This works like normal React state.

That makes the hook easier to learn because it follows a familiar pattern.

Removing the Value

The hook returns a third function called removeValue.

Example:

const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

When we call:

clearTheme();

The hook:

Deletes the value from localStorage.
Sends a sync event.
Sets React state back to the initial value.

This is useful for reset buttons, logout buttons, and clearing old settings.

Same Tab Sync

This hook supports Same Tab Sync.

This means if two components on the same page use the same key, they can stay updated.

Example:

function Header() {
  const [theme] = useLocalStorageState("theme", "light");
  return <p>{theme}</p>;
}

function Settings() {
  const [theme, setTheme] = useLocalStorageState("theme", "light");
  return <button onClick={() => setTheme("dark")}>Dark</button>;
}

If Settings updates the theme, Header should also get the new value.

The browser storage event does not fire in the same tab that made the change.

So the hook creates its own custom event:

const LOCAL_SYNC_EVENT = "__localyx_sync__";

When the value changes, the hook dispatches this event.

Other hook instances in the same tab listen for it and update their state.

Cross Tab Sync

The hook also supports Cross Tab Sync.

This means if the app is open in two browser tabs, changes can move from one tab to another.

The browser already gives us a storage event for this.

The hook listens to it:

window.addEventListener("storage", onStorage);

When another tab changes the same localStorage key, this tab receives the new value.

Then the hook:

Checks if the key is the same.
Parses the new value.
Checks if it is expired.
Updates React state.

This makes the UI feel consistent across tabs.

TTL Expiry

TTL means a value should expire after some time.

Example:

const [token, setToken] = useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
});

This means the value expires after 10 minutes.

When TTL is enabled, the hook saves a timestamp:

{
  v: token,
  t: Date.now()
}

Later, it checks:

now >= savedTime + ttl

If this is true, the value has expired.

Then the hook deletes it and returns the initial value.

Absolute TTL

The default TTL strategy is absolute.

Example:

useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  ttlStrategy: "absolute",
});

If the value is saved at 10:00, it expires at 10:10.

It does not matter if the user keeps reading the value.

This is good for strict expiry.

Good examples:

auth-like temporary values
one-time data
fixed cache expiry

Sliding TTL

The second TTL strategy is sliding.

Example:

useLocalStorageState("search_cache", "", {
  ttl: 5 * 60 * 1000,
  ttlStrategy: "sliding",
});

Sliding TTL refreshes the timestamp when the value is used.

In the code, this happens in touchSlidingTtl.

If the value is still active, the hook updates t to the current time.

This keeps active data alive for longer.

Good examples:

active UI cache
recent filters
data that should expire only after inactivity

Auto Cleanup with setTimeout

The hook does not only check expiry when reading.

It also sets a timer.

window.setTimeout(...)

The timer waits until the saved value should expire.

When the timer runs, the hook reads the latest value again.

This is important because the value may have changed before the timer ended.

Then it checks if the latest value is expired.

If yes, it removes it and updates state.

This keeps the current tab clean without waiting for a page refresh.

The onExpire Callback

The hook lets users pass onExpire.

useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  onExpire: ({ key, value }) => {
    console.log("Expired:", key, value);
  },
});

When the value expires, the hook calls this function.

This can be used to:

show a message
log out a user
clear other related values
track expiry behavior

The Internal expiryTick State

There is a small internal state called expiryTick.

const [expiryTick, setExpiryTick] = useState(0);

This value is not shown to the user.

It only helps the hook re-run the expiry timer effect.

When a TTL value changes or is removed, the hook updates expiryTick.

That tells React:

Please run the expiry effect again.

This keeps the timer in sync with the latest saved value.

Why useCallback Is Used

The hook uses useCallback for internal functions like:

readStorage
setState
removeValue
expireEntry
touchSlidingTtl

useCallback helps keep function references stable between renders.

This is useful because some of these functions are used inside useEffect.

It helps React know when an effect should run again.

For beginners, the simple explanation is:

useCallback helps the hook avoid recreating important functions unless their inputs change.

The getRemainingTtl Helper

The package also exports getRemainingTtl.

Example:

import { getRemainingTtl } from "@gks101/localyx";

const remainingMs = getRemainingTtl("token", 10 * 60 * 1000);

Internally, it:

Builds the final storage key.
Reads the saved value.
Decodes and parses it.
Checks the saved timestamp.
Returns the remaining time.

It can return:

a number when time is left
0 when the value has expired
null when there is no valid TTL data

This is useful when you want to show a timer or debug expiry behavior.

Full Flow in Simple Words

Here is the full flow of the hook:

Build the final key.
Choose JSON or custom serializer.
Choose Base64 or custom encode/decode.
Read old data from localStorage.
Validate and parse the old data.
Check if the old data is expired.
Put the value into React state.
When the setter is called, update state and localStorage.
Notify other hook instances in the same tab.
Listen for updates from other browser tabs.
If TTL is enabled, schedule cleanup.
If the value expires, remove it and reset state.

Small Example of the Final API

import { useLocalStorageState } from "@gks101/localyx";

function App() {
  const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light", {
    namespace: "demo-app",
    ttl: 24 * 60 * 60 * 1000,
  });

  return (
    <div>
      <p>Theme: {theme}</p>

      <button onClick={() => setTheme("dark")}>
        Dark
      </button>

      <button onClick={() => setTheme("light")}>
        Light
      </button>

      <button onClick={clearTheme}>
        Reset
      </button>
    </div>
  );
}

Why This Hook Is Useful

This hook is useful because it handles many small details in one place.

Without a hook, every component may need to repeat the same logic.

With this hook, the component only focuses on the UI.

The hook handles:

saving
loading
parsing
deleting
expiry
Same Tab Sync
Cross Tab Sync
custom serialization
custom encoding

Final Thoughts

The main goal of useLocalStorageState is to make browser storage feel simple in React.

It behaves like useState, but it also remembers the value after refresh.

It also adds useful features like TTL expiry, same tab sync, cross tab sync, namespaces, and custom serialization.

If you are a beginner, you can first use the basic API.

Then, when your app needs more control, you can start using the options one by one.

Install:

npm install @gks101/localyx

GitHub:

https://github.com/gaurav101/localyx

Demo:

https://localyx.vercel.app/

A Simple React Hook for localStorage State, Expiry, and Sync

Gaurav Kumar Singh — Thu, 21 May 2026 13:21:38 +0000

Hi everyone! I'm Gaurav, and I am incredibly excited to share my very first article with the DEV Community! As a developer, I love building open-source tools that solve everyday workflow headaches and make life a bit easier for the community. I wrote this article to share what I learned while building my latest package, and I hope it helps you level up your React storage management.

When we build React apps, we often need to save small values in the browser.

For example:

selected theme
user settings
form draft
search filters
temporary session value
cached API response

The browser already gives us localStorage, but using it directly in React can become repetitive.

We usually need to:

read the value from localStorage
parse the saved JSON
handle missing or broken data
update React state
write the new value back to localStorage
remove the value when needed
sync the value between tabs
expire old values after some time

This is why I built @gks101/localyx.

It is a small React hook that helps you use localStorage like normal React state.

Main Features

simple useState-like API
saves state in localStorage
Same Tab and Cross Tab Sync
TTL expiry support
absolute and sliding expiry strategies
namespace support
custom serializer support
custom encrypt and decrypt support
helper function to check remaining TTL

Working demo:

https://localyx.vercel.app/

GitHub repo:

https://github.com/gaurav101/localyx

NPM package:

npm install @gks101/localyx

What Problem Does It Solve?

React state is simple:

const [value, setValue] = useState("hello");

But normal React state is lost when the page is refreshed.

localStorage can keep data after refresh, but it does not work like React state by default.

So I wanted a hook that feels like useState, but also saves the value in localStorage.

That is the main idea of useLocalStorageState.

Basic Usage

First install the package:

npm install @gks101/localyx

Then import the hook:

import { useLocalStorageState } from "@gks101/localyx";

Now use it inside a component:

import { useLocalStorageState } from "@gks101/localyx";

function ThemeToggle() {
  const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

  return (
    <div>
      <p>Current theme: {theme}</p>

      <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
        Toggle Theme
      </button>

      <button onClick={clearTheme}>
        Reset Theme
      </button>
    </div>
  );
}

This looks very close to useState.

The hook returns three values:

const [state, setState, removeValue] = useLocalStorageState(key, initialValue);

Step 1: The Key

The first value is the localStorage key.

useLocalStorageState("theme", "light");

Here, "theme" is the key.

The hook will save the value in localStorage using this key.

Step 2: The Initial Value

The second value is the default value.

useLocalStorageState("theme", "light");

Here, "light" is the initial value.

The hook will use this value when:

nothing is saved in localStorage
the saved data is invalid
the saved data has expired
you remove the value

Step 3: Reading the State

The first returned value is the current state.

const [theme] = useLocalStorageState("theme", "light");

You can show it in your UI:

<p>Current theme: {theme}</p>

When the page refreshes, the hook reads the saved value from localStorage.

Step 4: Updating the State

The second returned value is the setter function.

const [theme, setTheme] = useLocalStorageState("theme", "light");

You can use it like setState:

setTheme("dark");

You can also use the previous value:

setTheme((oldTheme) => oldTheme === "light" ? "dark" : "light");

When you call setTheme, the hook updates React state and also saves the new value in localStorage.

Step 5: Removing the Value

The third returned value removes the saved data.

const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

Use it like this:

clearTheme();

This removes the value from localStorage and sets the state back to the initial value.

TTL: Expire Data After Some Time

Sometimes we do not want to keep data forever.

For example, a session value or cache value should expire after some time.

TTL means "Time To Live".

You can pass ttl in milliseconds.

import { useLocalStorageState } from "@gks101/localyx";

function SessionExample() {
  const [session, setSession, clearSession] = useLocalStorageState<string | null>(
    "session",
    null,
    {
      ttl: 30 * 60 * 1000,
    }
  );

  return (
    <div>
      <p>{session ?? "No active session"}</p>

      <button onClick={() => setSession("my-session-token")}>
        Login
      </button>

      <button onClick={clearSession}>
        Logout
      </button>
    </div>
  );
}

In this example, the session expires after 30 minutes.

After expiry, the hook removes the old value and returns the initial value.

Absolute TTL

By default, TTL uses the absolute strategy.

This means the timer starts when the value is saved.

Example:

const [token, setToken] = useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  ttlStrategy: "absolute",
});

If the value is saved at 10:00, it will expire at 10:10.

Even if the user keeps using the app, the value still expires at that time.

This is useful for things like:

login session expiry
one-time temporary values
short-lived cache

Sliding TTL

The hook also supports sliding TTL.

const [searchCache, setSearchCache] = useLocalStorageState("search_cache", "", {
  ttl: 5 * 60 * 1000,
  ttlStrategy: "sliding",
});

Sliding TTL refreshes the timer when the value is read or synced.

This means active data can stay alive while the user is still using it.

This is useful for:

active session-like data
recently used filters
temporary UI cache

Run Code When a Value Expires

You can pass onExpire.

This function runs when the hook finds that the value has expired.

const [token, setToken] = useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  onExpire: ({ key, value }) => {
    console.log("Expired key:", key);
    console.log("Expired value:", value);
  },
});

This is useful when you want to:

show a message
logout the user
clear related data
send an analytics event

Namespaces

Sometimes many features use localStorage.

To avoid key conflicts, you can use a namespace.

const [profile, setProfile] = useLocalStorageState("profile", null, {
  namespace: "my-app",
});

This stores the value using this key:

my-app:profile

Namespaces are useful when:

you have many stored values
you are building a large app
you want to separate app versions
you want cleaner localStorage keys

Same Tab and Cross Tab Sync

If you open the same app in two browser tabs, the hook can keep values in sync.

For example:

Open the app in Tab 1.
Open the app in Tab 2.
Change the theme in Tab 1.
Tab 2 gets the new value too.

The hook also handles same-tab sync.

This is useful when two components use the same storage key on the same page.

Get Remaining TTL

The package also exports getRemainingTtl.

This helper tells you how much time is left before a saved value expires.

import { getRemainingTtl } from "@gks101/localyx";

const remainingMs = getRemainingTtl("session", 30 * 60 * 1000);

console.log(remainingMs);

It returns:

a number if time is remaining
0 if the value is already expired but not cleaned yet
null if the key does not exist or the value has no TTL data

You can also use it with a namespace:

const remainingMs = getRemainingTtl("session", 30 * 60 * 1000, {
  namespace: "my-app",
});

Custom Serialization

By default, the hook uses JSON.

For most React apps, that is enough.

But you can provide your own serializer if you need custom behavior.

const [value, setValue] = useLocalStorageState("custom", "hello", {
  serializer: {
    stringify: (value) => JSON.stringify(value),
    parse: (value) => JSON.parse(value),
  },
});

This is useful when you want more control over how data is saved and loaded.

Encoding and Encryption

By default, the hook stores data with Base64 encoding.

Base64 is only obfuscation. It is not real security.

If you need real security, pass your own encrypt and decrypt functions.

const encrypt = (raw: string) => {
  return btoa(raw);
};

const decrypt = (raw: string) => {
  return atob(raw);
};

const [secret, setSecret] = useLocalStorageState("secret", "hello", {
  encrypt,
  decrypt,
});

If you want to store plain JSON without Base64 encoding, pass null:

const [value, setValue] = useLocalStorageState("plain", "hello", {
  encrypt: null,
  decrypt: null,
});

Important note: do not store highly sensitive data in localStorage unless you fully understand the security risks.

SSR Safe

The hook has guards for browser-only APIs.

This means it can be used in apps that render on the server, like Next.js.

It will not directly access window or localStorage when they are not available.

Where Can You Use This Hook?

You can use this hook in many React projects.

Good use cases:

dark mode or theme setting
language preference
sidebar open or closed state
table filters
search filters
sort order
form draft
shopping cart for small projects
temporary session value
API cache with expiry
feature flag cache
onboarding step progress
recently viewed items

Avoid using it for:

passwords
private tokens without a security plan
very large data
data that must always be correct on the server

You Can Also Copy the Hook Into Your Project

You do not have to use the npm package if you do not want another dependency.

You can also copy the hook file from the GitHub repo and use it directly in your project.

Repo link:

https://github.com/gaurav101/localyx

This can be useful when:

you want full control over the code
you want to change the hook for your app
you are learning how the hook works
you want to avoid adding a package

Full API

Main hook:

useLocalStorageState<T>(key, initialValue, options?)

It returns:

[state, setState, removeValue]

Options:

{
  ttl?: number;
  ttlStrategy?: "absolute" | "sliding";
  namespace?: string;
  onExpire?: (ctx: { key: string; value: T }) => void;
  now?: () => number;
  encrypt?: ((raw: string) => string) | null;
  decrypt?: ((raw: string) => string) | null;
  serializer?: {
    stringify: (value: T) => string;
    parse: (value: string) => T;
  };
}

Helper:

getRemainingTtl(key, ttl, options?)

Final Thoughts

I built @gks101/localyx because I wanted a simple way to use localStorage in React without writing the same logic again and again.

It gives you a useState-like API, but also adds useful features like expiry, sync, namespaces, and custom serialization.

If you are a React beginner, you can start with the basic example first.

Later, when you need expiry or sync, the hook already supports it.

Package:

npm install @gks101/localyx

GitHub:

https://github.com/gaurav101/localyx

I would absolutely love to hear your thoughts, feedback, or any questions you have in the comments below—let's connect!

gaurav101 (Gaurav Kumar Singh) · GitHub

Full-stack developer passionate about building scalable applications and exploring new technologies. - gaurav101

github.com

DEV Community: Gaurav Kumar Singh

Sick of App Store Ads? So I Built My Daughter Her Own Drawing PWA

Introduction

The Tech Stack

Building with Google AI Studio

Source Code

How to Install It on an iPad or Phone

What I Learned

1. AI Helps You Build Faster

2. Kids Can Learn That They Can Build Things

Markdown to Styled HTML in Java

💡 What is FluentMarkdown?

🛠️ Getting Started

1. Installation

2. Quick Start: Use a Framework Preset

🧠 Advanced Usage

🔒 Step 3: XSS Protection (Safe Mode)

🎨 Step 4: Custom Style Configurations

🔄 Step 5: Extend Existing Presets

🎯Conclusion

The Hidden Cost of the AI Hype

1. The "Why Bother?" Mindset

2. The Funding and Praise Monopoly

3. The "AI-First" Discount

AI Is an Accelerator, Not a Substitute

What We Should Value

Building a Safe, Local AI Coding Agent with Node.js

What We Are Building

Why This Helps Us Learn

The Big Idea

Project Structure

1: CLI Entry Point

2: Agent Loop

3: System Prompt

4: Local Model Adapter

5: Tool Calling

6: Safe Tools

7: Path Safety With safeResolve

8: Size Limits

9: Patch Proposals, Not Auto-Edits

10: Tests for Safety

Complete Request Flow

How to Run It

What to Remember

Final Thoughts

SOLSTICE: Planetary Balance

What I Built

Game Demo

Code

How I Built It

How To Play the Game (https://solstice-game.vercel.app/)

🛰️ 1. The Core Objective

🎮 2. Control Layout

☀️ 3. Key Calibration Rules

📍 The Solstice sweet spot (23.44°)

🌀 The Rotational Band (1.0 to 2.5 RPM)

🚨 4. Galactic Disturbance Hazards

🏆 5. Tips for Pro-Commanders

Prize Categories

Build a Local RAG AI App with Ollama, Mistral, and Node.js

What Is RAG?

Why RAG Matters

What We Will Build

Step 1: Install Ollama

Step 2: Create the Node.js Project

Step 3: Add Local Documents

Step 4: Add Configuration

Step 5: Read and Split Documents

Step 6: Create Embeddings

Why Do We Need nomic-embed-text?

Step 7: Build the Index

Step 8: Search the Best Chunks

Step 9: Give Context to Mistral

Step 10: Ask a Question

The Full RAG Flow

Why This Local Version Is Useful

Conclusion

MCP Server and RAG: A Simple Introduction for Developers

What Is RAG?

What Is an MCP Server?

7: Path Safety With `safeResolve`

Why Do We Need `nomic-embed-text`?

Option 2: Add Manually in `config.toml`

1. The Real-World Engineering Problem: `EADDRINUSE`