This document contains comprehensive information about K I R A N's professional profile, portfolio, and blog content. It includes personal details, work experience, projects, achievements, and all published blog posts. This data is formatted for consumption by Large Language Models (LLMs) to provide accurate and up-to-date information about K I R A N's background, skills, and expertise as a Full Stack Developer.
# kiranism.dev
> A minimal, pixel-perfect dev portfolio and blog to showcase my work as a Full Stack Developer.
## About
- Full-stack developer focused on building scalable, maintainable web applications.
- Skilled in Next.js, React, and TypeScript, with experience building high-quality, user-centric web applications using modern front-end tools.
- AI-assisted workflows to speed up development, improve code quality, and optimize technical decisions.
- Prioritize maintainable codebases, solid architecture, and real-world performance stability.
- Collaborated with Clerk and Sentry growth teams on an OSS Next.js starter template.
- Maintaining an Next.js starter template used by many developers, with .
### Personal Information
- First Name: K I R A N
- Last Name: K I R A N
- Display Name: K I R A N
- Location: Remote, Kerala
- Website: https://dub.sh/kiranism
### Social Links
- [GitHub](https://github.com/Kiranism)
- [X](https://twitter.com/thedvlpr)
- [LinkedIn](https://www.linkedin.com/in/kiranism/)
### Tech Stack
- [TypeScript](https://www.typescriptlang.org/)
- [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
- [Node.js](https://nodejs.org/)
- [Bun](https://bun.sh/)
- [React](https://react.dev/)
- [Next.js](https://nextjs.org/)
- [Tailwind CSS](https://tailwindcss.com/)
- [shadcn/ui](https://ui.shadcn.com/)
- [Base UI](https://base-ui.com/)
- [Motion](https://motion.dev/)
- [TanStack](https://tanstack.com/)
- [Git](https://git-scm.com/)
- [Docker](https://www.docker.com/)
- [MongoDB](https://www.mongodb.com/)
- [Figma](https://www.figma.com/)
- [Claude](https://claude.ai/)
- [Cursor](https://cursor.com/)
- [ChatGPT](https://chatgpt.com/)
## Experience
### Fullstack Developer | Hutfin
Duration: 01.2025 - Present
Skills: Nextjs, React, TypeScript, Node, Express, MongoDB, Aws
Responsibilities:
- Working as a founding engineer for a commercial real estate platform.
Location:
- Remote · United States
### Contract Remote Developer | Upwork / Freelancer
Duration: 04.2023 - Present
Skills: Nextjs, React, TypeScript, TailwindCSS, Shadcn, Supabase, Clerk, Frontegg, Tanstack query, Tanstack tables
Responsibilities:
- Deliver contract projects for international clients across Switzerland, the US, and Belgium using a modern Next.js + TypeScript stack, with a focus on scalable SaaS delivery, frontend architecture, and reliable full-stack execution.
Location:
- Remote · Switzerland, United States, Belgium
### Contract Full Stack Engineer - Next.js (short-term) | ROQ.tech
Duration: 04.2024 - 05.2024
Skills: Nextjs, React, TypeScript, Prisma, Postgres, Zod, TailwindCSS, Shadcn
Responsibilities:
- Completed a short-term contract engagement on a full-stack project using Next.js, Server Actions, TypeScript, Prisma, Postgres, shadcn/ui, and Tailwind CSS.
Location:
- Remote · Germany
### Frontend Developer | Avaibe
Duration: 01.2024 - 01.2025
Skills: Nextjs, React, TypeScript, TailwindCSS, Payload CMS, AWS
Responsibilities:
- Teamed up with developers, designers, and stakeholders to build and launch SaaS products.
Location:
- United Arab Emirates
### Fullstack Developer - MERN | Stackroots
Duration: 01.2022 - 04.2023
Skills: Nextjs, React, Material UI, Nodejs, MongoDB, Express
Responsibilities:
- Collaborated with developers and designers to ship production web applications solving real business problems.
Location:
- Hybrid · India
## Projects
### Next Shadcn Dashboard
Project URL: https://dub.sh/shadcn-dashboard/
Skills: Next.js, TypeScript, shadcn/ui, TanStack Table, Clerk, Sentry, Zod, Nuqs, Husky, Eslint
Open source admin dashboard starter built with Next.js, shadcn/ui, Tailwind CSS, and TypeScript.
Sponsorships:
- Collaborated on Sentry and Clerk integration support for this dashboard starter.
### what the link
Project URL: undefined
Skills: TanStack Start, Hono, Drizzle ORM, SQLite, TypeScript, shadcn/ui, Baileys, OpenRouter, Gemini
A bookmark manager built for people who save links in WhatsApp. AI-powered semantic search, auto-tagging, and link extraction — all from a WhatsApp group.
### TanStack Dashboard
Project URL: https://dub.sh/tanstack-start-dashboard
Skills: TanStack Start, TypeScript, shadcn/ui, TanStack Query
Admin dashboard starter built with TanStack Start and shadcn/ui for scalable React app foundations.
### next-resume-ai
Project URL: https://github.com/Kiranism/next-resume-ai
Skills: Next.js, TypeScript, React PDF, Tailwind CSS, Shadcn-ui, Gemini, Drizzle, Neon Postgres
Resume generator built with Next.js and React PDF to create and export polished resumes quickly.
### ChatWithPDF
Project URL: https://chat-with-pdf7.vercel.app
Skills: Next.js, TypeScript, OpenAI, LangChain, Pinecone
AI-powered PDF workflow to upload documents, summarize content, and answer questions with LLM-backed retrieval.
### codeFlow
Project URL: https://github.com/Kiranism/codeFlow
Skills: TypeScript, React, Remotion
Developer tool to animate and present code snippets with clean visual storytelling.
### WallpaperNext
Project URL: https://wallpapernext.in
Skills: Next.js, Sanity, Tailwind CSS
Wallpaper platform optimized for SEO and content workflows with Sanity CMS and high-speed downloads.
### Draw-X
Project URL: https://draw-x-production.up.railway.app/
Skills: Next.js, Socket.io, Zustand, Tailwind CSS, Zod
Realtime collaborative drawing app with customizable strokes, undo/redo, and multiplayer socket synchronization.
### next-shadcn-dashboard-starter
Project URL: https://github.com/Kiranism/next-shadcn-dashboard-starter
Skills: admin-dashboard, dashboard-template, nextjs, nextjs-admin, nextjs-dashboard, nextjs-starter, shadcn-admin, shadcn-ui, tailwindcss
Open source admin dashboard starter built with Next.js 16, shadcn/ui, Tailwind CSS, and TypeScript.
### tanstack-start-dashboard
Project URL: https://github.com/Kiranism/tanstack-start-dashboard
Skills: react-admin-dashboard, react-dashboard, tanstack-react-query, tanstack-start, tanstack-start-dashboard, tanstack-table
Admin Dashboard Starter with Tanstack Start + Shadcn Ui
### voicenotes
Project URL: https://github.com/Kiranism/voicenotes
Skills: TypeScript
No description provided.
### Kiranism
Project URL: https://github.com/Kiranism/Kiranism
Skills: Code
No description provided.
### testing-env
Project URL: https://github.com/Kiranism/testing-env
Skills: HTML
No description provided.
### Thalaforareason
Project URL: https://github.com/Kiranism/Thalaforareason
Skills: ai, drizzle, neondb, nextjs, openai, postgres, typescript, vercel
This app is made with love, dedicated to India's legendary captain, Ms. Dhoni.
### Next-auth-custom-backend
Project URL: https://github.com/Kiranism/Next-auth-custom-backend
Skills: TypeScript
Next.js app setup when you've got a separate backend server and Next.js as your frontend!
### turbo-ecom
Project URL: https://github.com/Kiranism/turbo-ecom
Skills: ecommerce, nextjs, shadcn-ecommerce, turborepo, turborepo-shadcn, turborepo-starter
A Turbo monorepo e-commerce project with admin and user apps, sharing a common database, Prisma schema, and Shadcn UI components across apps.
### job-board
Project URL: https://github.com/Kiranism/job-board
Skills: TypeScript
Develop a CRUD application for a job listing board as a part of an assessment using React with TypeScript, incorporating a mock API and styling with Tailwind CSS.
### dashbow
Project URL: https://github.com/Kiranism/dashbow
Skills: TypeScript
Crud Assessment
### react-ecom
Project URL: https://github.com/Kiranism/react-ecom
Skills: JavaScript
No description provided.
### holymollyproblems
Project URL: https://github.com/Kiranism/holymollyproblems
Skills: JavaScript
No description provided.
### weather-app
Project URL: https://github.com/Kiranism/weather-app
Skills: JavaScript
Weather App Demo Link
### board
Project URL: https://github.com/Kiranism/board
Skills: JavaScript
This project is a dashboard application built using React, Next.js, Tailwind CSS, and NextAuth.js for authentication. It provides a pixel-perfect replica of the design provided, with responsive UI and working charts populated with dummy data from the Mocki fake API.
### Taiyo-ts
Project URL: https://github.com/Kiranism/Taiyo-ts
Skills: TypeScript
This is a contact management app built with ReactJS, TypeScript, TailwindCSS, React Router v6, and React Query. It includes features such as adding new contacts, displaying a list of contacts, editing and deleting contacts, and integrating charts and maps for COVID-19 data.
### mui-with-tailwindcss
Project URL: https://github.com/Kiranism/mui-with-tailwindcss
Skills: JavaScript
No description provided.
### thirdlens-tgbot
Project URL: https://github.com/Kiranism/thirdlens-tgbot
Skills: JavaScript
No description provided.
### night-watchers-vscode-theme
Project URL: https://github.com/Kiranism/night-watchers-vscode-theme
Skills: dark-teme, editors-theme, tutorial-theme, vscode, vscode-theme
🌌 NIGHT WATCHERS: A VS Code dark theme for contrast for night and daytime coding, 🎃
### vite-app-starter
Project URL: https://github.com/Kiranism/vite-app-starter
Skills: JavaScript
No description provided.
### React-Frontend-Task
Project URL: https://github.com/Kiranism/React-Frontend-Task
Skills: JavaScript
No description provided.
### React-challanges
Project URL: https://github.com/Kiranism/React-challanges
Skills: JavaScript
No description provided.
### task
Project URL: https://github.com/Kiranism/task
Skills: JavaScript
No description provided.
### olx-clone
Project URL: https://github.com/Kiranism/olx-clone
Skills: firebase, firebase-auth, react
Olx clone using React and Firebase
### movie-redux
Project URL: https://github.com/Kiranism/movie-redux
Skills: api, react, redux, scss
A movie app with redux, fetching data from omtb api
### chat-app
Project URL: https://github.com/Kiranism/chat-app
Skills: node, react, socketio
A real time chat application using react node and socket io
### Ecom
Project URL: https://github.com/Kiranism/Ecom
Skills: nodejs, react
A fully functional Ecommerce Website Using React and Nodejs
### TravelAdvisor
Project URL: https://github.com/Kiranism/TravelAdvisor
Skills: google-maps-api, reactjs
A Travel Companion Application using React and Google Map Api
### newsanddeals
Project URL: https://github.com/Kiranism/newsanddeals
Skills: css, django, html, python
NewsandDeals
### MovieApp
Project URL: https://github.com/Kiranism/MovieApp
Skills: JavaScript
React-Native Movie app
### emergency-portal
Project URL: https://github.com/Kiranism/emergency-portal
Skills: JavaScript
No description provided.
### mern-store-client
Project URL: https://github.com/Kiranism/mern-store-client
Skills: expressjs, mongodb, nodejs, reactjs
An Ecommerce store using Mern Stack
### crm-frontend
Project URL: https://github.com/Kiranism/crm-frontend
Skills: Code
No description provided.
### 50days50projects
Project URL: https://github.com/Kiranism/50days50projects
Skills: CSS
#50days50 javascript project
### React-ToDoApp
Project URL: https://github.com/Kiranism/React-ToDoApp
Skills: JavaScript
A simple ToDoApp using React
### responsive-photography-web
Project URL: https://github.com/Kiranism/responsive-photography-web
Skills: HTML
No description provided.
### single-page-webpage
Project URL: https://github.com/Kiranism/single-page-webpage
Skills: HTML
created a single page webpage about a mobile phone and its features
## Blog
---
title: "What The Link — How I AI-fied My WhatsApp"
description: "How I built a WhatsApp-powered bookmark manager with semantic search using Baileys, TanStack Start, Hono, Drizzle, SQLite, and Gemini embeddings."
last_updated: "April 14, 2026"
source: "https://kiranism.dev/blog/what-the-link"
---
# What The Link — How I AI-fied My WhatsApp
How I built a WhatsApp-powered bookmark manager with semantic search using Baileys, TanStack Start, Hono, Drizzle, SQLite, and Gemini embeddings.
Have you ever used WhatsApp as a bookmarking tool?
I did. I even have a group with just me where I dump thoughts and links. Blogs. Tweets. Tools. Products. Ideas.
The problem? Finding them again. So I built **What The Link**.
## The Problem
I'm someone who always sends links — products, blogs, brainstorming notes, ideas — everything gets dumped into my WhatsApp personal group for quick access.
But over time it gets flooded. Messy. Hard to search.
You need to remember *what* you're searching for. There's no semantic search in WhatsApp — and that's the real problem. You have to remember the exact words you used, not what the link was actually about.
So I thought — why not give WhatsApp that ability? AI-ify it. Make it actually smart.
## Finding the Right Approach
When the idea first clicked, I thought about piping chats from WhatsApp to Notion. But only paid bot integrations existed. Same story with the WhatsApp Business API — also paid. Not what I needed.
Then I got curious about how **OpenClaw** handles their WhatsApp integration. That's how I found **Baileys** — an unofficial WhatsApp socket package where you connect your WhatsApp via QR code and keep the session active. For free.
That was exactly what I wanted.
I didn't go through every file in their big monorepo to understand the codebase. What I did instead was prepend their GitHub link with **DeepWiki**, which had already indexed the whole repo. I just chatted with it and got the info I needed.
```text
deepwiki.com/[github-repo-url]
```
Around the same time I got the **Claude Max plan** for 6 months through Anthropic's open source program. What else do you want, right? I started building, planning, and figuring out the scope.
## The Stack
I picked the **T3 stack builder** to bootstrap the project. The full stack:
* **TanStack Start** — full-stack React framework, file-based routing, server functions built in
* **Hono** — lightweight backend API layer
* **Drizzle ORM** — type-safe, SQL-first. Pairs really well with SQLite
* **SQLite** — simple, file-based, no infra overhead for a v1
* **shadcn/ui** — for the UI components
The whole thing is type-safe end to end. Drizzle handles the schema and queries, Hono handles the API routes, TanStack Start ties the frontend and backend together. For a solo project it's a really clean setup — not over-engineered, but also not something you'll regret later.
## Building It — V1 First
I didn't try to build everything at once.
**V1 was just the CRUD and the backend.** Baileys listens for incoming WhatsApp messages, extracts any links, and saves them to SQLite via Drizzle. That's it. No AI yet. Just — capture the link, store it, show it in the web UI.
Get the plumbing right first. The smart stuff comes after.
```text
WhatsApp message
↓
Baileys socket picks it up
↓
Extract the link
↓
Save to SQLite via Drizzle
↓
Show in the web UI
```
Once that was working cleanly, I moved to the part I actually wanted to build.
## How the WhatsApp Part Actually Works
Baileys gives you a raw WebSocket connection to WhatsApp Web. You scan a QR code once, and the session gets persisted to disk — so on restart, it just reconnects. No QR again.
But it's not plug-and-play. WhatsApp rejects outdated client versions with a `405`. So the server fetches the latest WhatsApp Web version from a public repo on startup. If that fails, it falls back to a hardcoded version. Small detail, but without it — the whole thing breaks silently.
### Connection state machine
```text
connection === "open" → good, listening
connection === "close" → check why
└─ 405 → outdated version → refetch, retry in 10s
└─ 440 → another device took over → logout, clear auth, wait
└─ anything else → auto-reconnect after 5s
```
### Message pipeline
When a message comes in, it goes through a pipeline:
1. Ignore your own messages
2. Filter by allowed group (optional — you can lock it to one group)
3. Check if it's a command (`?help`, `?search query`)
4. If not — extract links and save
### Link extraction — three-layer fallback
```text
Layer 1: Regex — fast, free. Grabs any http/https URL from the text.
Layer 2: AI text extraction — if regex finds nothing, ask Gemini to parse the message.
Layer 3: AI vision — if the message has an image (screenshot, photo of a screen,
QR code), download it and run it through Gemini's vision model.
```
Most messages hit Layer 1 and move on. But the vision layer is surprisingly useful — people screenshot tweets and product pages all the time. That would've been lost without it.
URLs also get cleaned up before saving. Tracking parameters like `utm_source`, `fbclid`, `gclid` — 21 of them — get stripped. Trailing slashes removed. URLs normalized. No junk in the database.
### Reactions
When a link is saved, the bot reacts to the WhatsApp message:
| Reaction | Meaning |
| -------- | ----------------------------------------- |
| 🔖 | Saved |
| ⚠️ | Duplicate |
| 📝 | Saved as a note (no URL found, just text) |
| ❌ | Nothing useful in the message |
Small touch but it makes it feel alive.
## The Database — Keeping It Simple
The whole thing runs on one SQLite file. Bookmarks, tags, settings, embeddings — all in one place.
### Bookmarks table
```sql
CREATE TABLE bookmarks (
url TEXT UNIQUE,
title TEXT,
description TEXT,
image TEXT,
favicon TEXT,
domain TEXT,
tags TEXT, -- JSON array, denormalized
source TEXT, -- 'whatsapp' | 'manual' | 'import'
whatsapp_message_id TEXT,
summary TEXT, -- AI-generated
embedding BLOB, -- serialized Float32Array
metadata_status TEXT,
summary_status TEXT,
embedding_status TEXT,
is_archived INTEGER DEFAULT 0,
created_at TEXT,
updated_at TEXT
);
```
Each bookmark has three independent processing pipelines — metadata, summary, and embedding — each with their own status and retry count. They run independently so a failed summary doesn't block the embedding, and vice versa.
Tags are stored as a JSON array directly on the bookmark. No join table. For this scale it's the right call — simpler queries, simpler code, and SQLite's `json_each()` handles filtering just fine.
There's also a separate `tags` table that tracks tag names and usage counts — basically a tag cloud index. And an `app_settings` key-value table for things like which WhatsApp group to listen to and digest preferences.
No foreign keys. No complex relationships. One file, easy to back up, easy to move.
## Then I AI-fied It
After V1 was solid, I added **OpenRouter** using the OpenAI SDK — so I'm hitting any model I want through one unified API without being locked into one provider.
The AI layer is a singleton client — it only initializes if you set the `OPENROUTER_API_KEY`. No key? No AI. The app still works, you just get basic keyword search instead of semantic search. Graceful degradation.
When a bookmark is saved, three things happen asynchronously — fire-and-forget style. The user sees the bookmark immediately. The AI stuff runs in the background:
### 1. Metadata fetch
Cheerio crawls the page — grabs the title, description, OG image, favicon. If the crawl gets blocked (some sites do), it falls back to AI inference from just the URL structure. Like `instagram.com/p/XYZ` — even without crawling, you know it's an Instagram post.
### 2. Summary + Tags
The page content gets sent to Gemini via OpenRouter. Two parallel prompts:
* **Summary:** "Summarize in 4-5 concise lines." Capped at 2000 characters.
* **Tags:** "Suggest 2-4 short lowercase tags." Returns a JSON array.
Tags only auto-generate if the user didn't include hashtags in the original message. If you send `#design #tools https://some-link.com`, those hashtags become the tags and the AI doesn't override them.
### 3. Embedding
Once the summary exists, the app builds an embedding text by concatenating:
```text
Title | Tags: tag1, tag2 | Full summary | Description (truncated to 500 chars)
```
That combined text gets sent to `gemini-embedding-001` via OpenRouter. The embedding comes back as a `Float32Array`, gets serialized to a binary blob, and stored directly in the SQLite `embedding` column.
No separate vector database. No Pinecone. No Qdrant. Just a BLOB column in the same SQLite file.
## The Retry Machine
AI APIs fail. Rate limits hit. Pages block crawlers. So every pipeline has a retry system.
Three cron jobs run every 5 minutes:
| Job | What it does |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Summary Retry** | Picks up `pending` or `failed` summaries (batch of 50), generates summary + auto-tags, chains to embedding job on success |
| **Embedding Retry** | Picks up `pending` or `failed` embeddings (batch of 50), generates and caches embedding |
| **Metadata Retry** | Retries failed page crawls |
Each bookmark gets 3 retries max per pipeline. After that it's marked `failed` and left alone — you can manually retry from the UI.
Rate limits get special treatment. When the app hits a `429` from OpenRouter, it pauses the entire batch for 60 seconds, then resumes. No aggressive retries hammering the API.
On startup, it also runs an immediate pass — processes all pending items before the cron kicks in. So after a deploy or restart, everything catches up fast.
## How Semantic Search Actually Works
This is the part that makes the whole thing worth building.
The approach: **in-memory embedding cache**. On startup, the server loads every bookmark's embedding into memory as `Float32Array` objects. When you search, it:
1. Generates an embedding for your query (one API call)
2. Computes cosine similarity against every cached embedding
3. Filters results above a 0.55 threshold
4. Returns top 50, sorted by score
Cosine similarity is just dot product divided by the product of magnitudes. Three lines of math on `Float32Array`. For a few thousand bookmarks, it runs in about **2ms**. No need for a vector index.
If AI isn't configured or the cache is empty, search falls back to SQL `LIKE` queries across title, description, URL, summary, and even inside the JSON tags array using `json_each()`. Not as smart, but it works.
### Search from WhatsApp
You can search directly from WhatsApp too:
| Command | Action |
| ---------------- | ----------------- |
| `?indie hackers` | Semantic search |
| `?#design` | Tag filter |
| `?recent 10` | Last 10 bookmarks |
Results come back as WhatsApp messages with clickable links. So you don't even need to open the web UI.
## The Web UI
In January I came across **Zaid Alam's** bookmarking tool. He built it for his own use case. I loved the minimal UI so I took some inspiration — and a screenshot — and prompted it straight into Claude Code.
It's not open source so I couldn't clone it. So I just fired more tokens and built the web UI myself using **shadcn components**.
The frontend is a TanStack Start app — SSR on first load, then SPA navigation. Two routes:
* **Home** — the bookmark library. Search bar, tag filters, pagination (25 or 50 per page), data grid with title, domain, date, and actions. Keyboard shortcuts for everything: `Cmd+K` to focus search, arrow keys to navigate, `Delete` to remove.
* **Settings** — WhatsApp QR code display, group selection dropdown, daily digest toggle with hour picker. Connect, disconnect, reconnect — all from the browser.
Auth is simple. Single password. Cookie-based session that lasts 30 days. Rate limited to 10 failed attempts per IP per 15 minutes. No OAuth, no user management. It's a personal tool.
## Deployment
The whole thing ships as a Docker image. Multi-stage build — builder compiles everything, runner is Alpine with just the compiled output.
```bash
docker-compose up -d
```
One volume mount for `/data` — that's where the SQLite database and the WhatsApp auth session live. Survives restarts, easy to backup, easy to migrate.
There's also a one-liner install script for VPS setups. It checks for Docker, asks for your password, builds the image, and starts the container. I'm running mine on Oracle Cloud's Always Free ARM instance — 24GB RAM for a SQLite app is hilariously overkill but hey, it's free.
Health check pings `/health` every 30 seconds. Container auto-restarts unless you explicitly stop it.
## Architecture at a Glance
```text
┌──────────────────────────────────────────────────────────────────┐
│ WhatsApp │
│ (Baileys Socket) │
│ QR Auth ←→ Session Persistence ←→ Message Listener │
└──────────────┬───────────────────────────────────────────────────┘
│ messages.upsert
▼
┌──────────────────────────────────────────────────────────────────┐
│ Link Extraction Pipeline │
│ Regex → AI Text → AI Vision (3-layer fallback) │
└──────────────┬───────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ SQLite (via Drizzle) │
│ bookmarks │ tags │ app_settings │
│ Single .db file │
└──────────┬────────────────────────────────┬──────────────────────┘
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────────────┐
│ AI Processing (Async) │ │ Hono API Server │
│ ┌───────────────────┐ │ │ /api/bookmarks (CRUD+search) │
│ │ Metadata (Cheerio) │ │ │ /api/whatsapp (QR+status) │
│ │ Summary (Gemini) │ │ │ /api/settings (config) │
│ │ Tags (Gemini) │ │ │ /api/login (auth) │
│ │ Embedding (Gemini)│ │ └──────────┬──────────────────────┘
│ └───────────────────┘ │ │
│ Retry cron: */5 * * * │ ▼
└─────────────────────────┘ ┌─────────────────────────────────┐
│ TanStack Start (React) │
┌──────────────────│ SSR + SPA │ shadcn/ui │
│ │ Search │ Settings │ Auth │
▼ └─────────────────────────────────┘
┌─────────────────────────┐
│ In-Memory Embedding │
│ Cache (Float32Array) │
│ Cosine Similarity │
│ ~2ms search time │
└─────────────────────────┘
```
***
That's the story. Built out of frustration, unlocked by one good insight, and shipped with a lot of tokens.
Last updated on April 14, 2026
---
title: "Efficient Type-Safe Server Actions in Next.js with ZSA"
description: "TL;DR: Discover how to implement type-safe server actions in your Next.js application using zsa or next-safe-action. This guide focuses on zsa, offering a clear approach to integrating type safety, validation, and error handling.
Introduction to Type..."
last_updated: "July 23, 2024"
source: "https://kiranism.dev/blog/efficient-type-safe-server-actions-in-nextjs-with-zsa"
---
# Efficient Type-Safe Server Actions in Next.js with ZSA
TL;DR: Discover how to implement type-safe server actions in your Next.js application using zsa or next-safe-action. This guide focuses on zsa, offering a clear approach to integrating type safety, validation, and error handling.
Introduction to Type...
> Imported from [Hashnode](https://kir4n.hashnode.dev/efficient-type-safe-server-actions-in-nextjs-with-zsa).
**TL;DR:** Discover how to implement type-safe server actions in your Next.js application using `zsa` or `next-safe-action`. This guide focuses on `zsa`, offering a clear approach to integrating type safety, validation, and error handling.
## Introduction to Type-Safe Server Actions in Next.js
In modern web development with Next.js, server actions are essential for handling form submissions and data mutations. While implementing these actions with robust type safety and validation can be challenging, utilizing libraries like [zsa](https://zsa.vercel.app/docs/introduction) or [next-safe-action](https://next-safe-action.dev/) can significantly simplify this process, enhancing both security and developer experience.
### What is ZSA and Why Use It?
**ZSA** is a library that integrates with Zod for schema validation in Next.js. It simplifies the creation of type-safe server actions and provides built-in support for handling input validation and error management.
By using `zsa`, you can avoid the complexity of manually setting up validation and error-handling utilities, streamlining your development process and improving code quality.
Enough theory! Now, I’ll walk you through how I used this with my Next.js blog application.
**Set Up Your Service Logic**
Normally, we create an `actions.ts` file inside a `lib` folder. However, to keep things cleaner, I’ll create a `service` folder as well, where we’ll create a `service.ts` file to handle the core logic for server-side operations. In this example, we’ll use Prisma ORM with PostgreSQL.
```typescript
// services/postService.ts
import { prisma } from '@/lib/prisma';
export async function savePostToDb(input: PostInput) {
await prisma.post.create({
data: {
title: input.title,
images: input.images,
},
});
}
```
**Define Server Actions and Middleware**
**Authentication Procedure**
In the action file where the action and ZSA logic take place, since our app has different roles such as admin and user, we need middleware to allow only admins to perform certain server actions. This can be achieved by creating procedures using ZSA.
First, we can create a procedure for authenticated users.
```typescript
//admin/action.ts
"use server"
import { createServerAction, createServerActionProcedure } from 'zsa';
import { getUser } from '@/lib/lucia';
const authedProcedure = createServerActionProcedure().handler(async () => {
try {
const user = await getUser();
if (!user) {
throw new Error('User not authenticated');
}
return {
user: {
email: user.email,
id: user.id,
role: user.role
}
};
} catch {
throw new Error('User not authenticated');
}
});
```
**Admin Check Procedure**
Extend the authentication procedure to include admin role verification:
```typescript
//admin/action.ts
"use server"
import { createServerAction, createServerActionProcedure } from 'zsa';
const isAdminProcedure = createServerActionProcedure(authedProcedure).handler(
async ({ ctx }) => {
const role = ctx.user.role;
if (role !== 'ADMIN') {
throw new Error('User is not an admin');
}
return {
user: {
id: ctx.user.id,
email: ctx.user.email,
role: role
}
};
}
);
```
Perfect, we have created a **middleware** that performs the `isAdmin` check, which we can chain with **admin-only server actions**.
```typescript
//admin/action.ts
"use server"
import { createServerAction, createServerActionProcedure } from 'zsa';
import {
POST_SCHEMA
} from '@/lib/validations';
// Only admins are allowed to create a post.
export const createPost = isAdminProcedure
.createServerAction()
.input(POST_SCHEMA, {
type: 'formData'
})
.handler(async ({ input, ctx }) => {
await savePostToDb(input);
revalidatePath('/', 'layout');
redirect('/admin/dashboard/posts');
});
```
Now, we have successfully created a type-safe server action with the Zod schema for input validation, both on the server and the client.
On to the client section. To use the server action, there are several approaches outlined in the ZSA documentation. For now, I’m using my favorite approach.
```typescript
//form.tsx
"use client"
import { useServerAction } from 'zsa-react';
// you can use this hook inside the form function component just like how you do mutation with the react query.
const { execute: createPostExe, isPending: loadingCreate } = useServerAction(
createPost,
{
onSuccess: () => {
toast.success('Post created successfully');
form.reset();
},
onError: ({ err }) => {
toast.error(err.message);
}
}
);
const onSubmit = async (values: POST_SCHEMA_VALUES) => {
//! Files need to be sent as formData.
const formData = new FormData();
formData.append('title', values.title);
for (let i = 0; i < values.images.length; i++) {
formData.append('images', values.images[i], values.images[i].name);
}
const { images, ...rest } = values;
await createPostExe(formData, rest);
};
// rest of code...