Forem: pipipi-dev

2025 Year in Review: Lessons from Solo SaaS Development

pipipi-dev — Thu, 25 Dec 2025 03:26:48 +0000

This is Day 25, the final article of the Solo SaaS Development - Design, Implementation & Operations Advent Calendar 2025.

I'll reflect on the technical knowledge shared over the past 25 days and summarize what I learned from 6 months of development.

🤖 2025: The Year Development Changed

2025 was the year AI-powered development went mainstream.

Claude Code was released in February, followed by GitHub Copilot Agent, OpenAI Codex, and other AI coding tools. "Having AI write your code" became a realistic option for many developers.

I started developing Memoreru in June—right when these tools were maturing.

As I wrote on Day 23, collaborating with Claude Code significantly changed my development style. Humans handle design, AI assists with implementation, and humans take responsibility for reviews. This division of labor enabled solo development that feels like team development.

The PDD (Progress-Driven Development) introduced on Day 24 is also a methodology built around AI collaboration. By maintaining design documents and visualizing progress, you can develop efficiently with AI agents.

Starting indie development in 2025 was good timing. It was a year when AI tools greatly expanded the possibilities for solo developers.

📖 The 25-Day Journey

The 25 articles were structured to follow the flow of indie development. The structure allows those starting indie development to experience the development journey vicariously.

Prologue (12/1-3) covered the flow from idea to first commit, AI-friendly tech selection, and Next.js + Supabase project structure.

Foundation (12/4-9) covered documentation strategy, Git workflow, DB design, and authentication implementation. Day 9's NextAuth.js → Better Auth migration may be helpful for those struggling with auth library choices.

Frontend, API & Infrastructure (12/10-13) started with App Router directory design, followed by MPA → SPA migration, Route Handler → Hono migration, and Vercel optimization. The SPA migration on Day 11 was a major refactoring with over 150 commits.

UX & Features (12/14-17) introduced mobile-first design, infinite scroll implementation, Excel-like table UI, and semantic search with pgvector. Day 15's React 19 + Zustand pitfall documents an unexpected bug encounter.

Practical Challenges (12/18-22) covered bugs discovered through TypeScript strict mode, the React vulnerability disclosed in December, Stripe billing, GA4 + Clarity, and multi-tenant design—all operational topics.

Retrospective (12/23-25) covers Claude Code collaboration, Progress-Driven Development (PDD), and concludes with this article.

🚀 Tech Stack

Here's the final technology stack after 6 months of development.

Frontend

Technology	Purpose	Related Articles
Next.js 15 (App Router)	Framework	Days 3, 10, 11
React 19	UI Library	Day 15
TypeScript 5	Type Safety	Day 18
Zustand	Client State Management	Days 11, 15

Backend & Infrastructure

Technology	Purpose	Related Articles
Supabase	BaaS	Days 3, 6
PostgreSQL	Database	Days 6, 17
pgvector	Vector Search	Day 17
Drizzle ORM	ORM	Days 3, 6
Better Auth	Authentication & 2FA	Day 9
Hono	API Framework	Day 12
Zod	Schema Definition & Validation	Days 12, 18
Vercel	Hosting	Days 3, 5, 13
Stripe	Payments	Day 20
OpenAI API	AI Features	Day 17

UI & Editor

Technology	Purpose	Related Articles
@dnd-kit	Drag & Drop	Day 16
React Spreadsheet	Spreadsheet UI	Day 16

Development Tools

Technology	Purpose	Related Articles
Claude Code	AI Pair Programming	Days 5, 23, 24
Git Worktree	Parallel Development	Day 5
Biome	Linter / Formatter	Day 18
GA4	Analytics	Day 21
Microsoft Clarity	Heatmap Analysis	Day 21

For more details on the tech stack, see:

https://memoreru.com/about

💡 Lessons Learned

Technology Selection and Migration

On Day 2, I wrote about "Tech Selection for AI-Driven Development." Choose technologies with rich documentation, type safety, and simple APIs. This was my selection philosophy.

However, the first choice isn't always right. Over 6 months, I made 4 major technology migrations.

Migration	Reason	Related Article
Prisma → Drizzle ORM	Better type inference, smaller bundle	Day 6
NextAuth.js → Better Auth	Simpler API, Drizzle compatibility	Day 9
Route Handler → Hono	OpenAPI integration, middleware design	Day 12
MPA → SPA	Better UX, centralized state management	Day 11

I sometimes think I should have gone with SPA from the start, but starting with MPA helped me understand SPA's benefits.

What's important is maintaining a state where you can make changes when you notice problems. Tests and design documents helped with this.

Documentation and Testing

On Day 4, I wrote about "Documentation-First Approach."

Feature specs, API specs, DB specs, UI specs, and thought logs recording design decisions. I've been maintaining all of these.

Time spent on documentation paid off as development efficiency. In the Claude Code collaboration introduced on Day 23, having design documents lets you say "implement according to this design." The PDD (Progress-Driven Development) from Day 24 also only works when design documents exist.

Tests proved their value during major changes. SPA migration, Better Auth migration, Drizzle migration. I could make these changes confidently because tests existed. As I wrote on Day 18, TypeScript strict mode prevents type errors but not logic bugs. Having tests meant I could make changes without fear.

Development Efficiency

Here's a summary of the practices introduced across the 25 articles.

Challenge	Solution	Article
Parallel Development	Git Worktree	Day 5
Type Safety	TypeScript Strict Mode	Day 18
API Type Definitions	Hono + Zod OpenAPI	Day 12
Progress Management	PDD (Progress-Driven Development)	Day 24
AI Collaboration	Design Documents + Claude Code	Day 23

These practices are effective individually, but combining them produces even greater results.

🌱 Looking Ahead to 2026

2025 was a year when the evolution of AI tools significantly changed how we develop.

I'll continue development in 2026. I hope these 25 articles serve as a reference for those pursuing indie development.

The thinking behind the development is documented in the note Advent Calendar. If interested, please check it out:

https://adventar.org/calendars/12464

I share development updates on X, so please follow if interested:

https://x.com/pipipi_dev

Thank you for reading to the end.

📝 Article List

Prologue (12/1-3)

Day	Title
1	Starting Indie Development: From Idea to First Commit
2	Tech Selection for AI-Driven Development: Finding the Right Stack
3	Next.js + Supabase for Indie Dev: Project Structure Overview

Foundation: Design, DB & Auth (12/4-9)

Day	Title
4	Documentation Strategy for Indie Dev: Design Docs & Thought Logs
5	Git Branch Strategy: Workflow for Solo Development
6	Supabase Schema Design: Table Separation and Normalization
7	Database ID Design: Choosing ID Types and Primary Keys
8	DB Migration Operations: Safely Managing Dev and Prod
9	NextAuth.js to Better Auth: Why I Migrated Auth Libraries

Frontend, API & Infrastructure (12/10-13)

Day	Title
10	App Router Directory Design: Next.js Project Structure
11	Why I Migrated from MPA to SPA: App Router Refactoring
12	Next.js Route Handler to Hono: Why API Design Got Easier
13	Vercel Optimization: Reducing Build Time and Improving Response

UX & Features (12/14-17)

Day	Title
14	Mobile-First for Optimal UX: Responsive Design in Practice
15	Infinite Scroll × Zustand × React 19: Async Pitfalls
16	No-Code Excel-Like Tables: Implementing Drag & Drop UI
17	Implementing Semantic Search: pgvector + OpenAI Embeddings

Practical Challenges (12/18-22)

Day	Title
18	Bugs Found with TypeScript Strict Mode: Type Safety in Practice
19	December 2025 React Vulnerability: Security for Solo Devs
20	Implementing Tiered Pricing with Stripe: Monetizing Indie Dev
21	Visualizing User Behavior: Setting Up GA4 and Microsoft Clarity
22	Building Multi-Tenant SaaS Solo: Pursuing Enterprise Quality

Retrospective (12/23-25)

Day	Title
23	How Claude Code Changed My Indie Dev: AI Pair Programming
24	Progress-Driven Development (PDD): Indie Dev with AI Agents
25	2025 Year in Review: Lessons from Solo SaaS Development (This Article)

Progress-Driven Development (PDD): Solo Development with AI Agents

pipipi-dev — Wed, 24 Dec 2025 09:54:08 +0000

This is Day 24 of the Building a SaaS Solo - Design, Implementation, and Operations Advent Calendar 2025.

Yesterday's article covered "AI Pair Programming with Claude Code." Today, I'll introduce "Progress-Driven Development (PDD)," a methodology for collaborating with AI agents.

:::message
"Progress-Driven Development (PDD)" is a term and concept I coined for this article. Drawing from over 10 years of PM/PdM experience with various progress management tools and methodologies, I developed this approach while exploring progress management methods suited to collaborating with AI agents.
:::

💡 What is Progress-Driven Development?

Progress-Driven Development (PDD: Progress-Driven Development) is a methodology that structures the entire development process and clarifies completion criteria for each step, enabling humans and AI to collaborate efficiently.

Challenges in Solo Development

When continuing solo development, do you ever face challenges like these?

Can't remember "how far did I get with that feature?"
Don't know what to do next when resuming after a break
Can't grasp what percentage of the overall project is complete

Spec-Driven Development (SDD: Spec-Driven Development) is a methodology that uses specification documents as the SSoT (Single Source of Truth) to drive design and implementation. Test-Driven Development (TDD: Test-Driven Development) is a methodology that repeats short cycles of writing a failing test (Red), implementing to pass the test (Green), and refactoring (Refactor).

These methodologies focus on "what to build" and "how to build it," but a separate mechanism is needed to understand "how much is done."

Reference Documents

PDD's Position

PDD doesn't reject SDD or TDD. It complements them by adding a progress management perspective.

SDD:  Drive implementation using specification documents as the single source of truth
TDD:  Ensure code quality through short test-implementation cycles
PDD:  Visualize progress to understand "how much is done"

By breaking development into multiple steps and clarifying completion criteria for each, you can see at a glance "how far along we are now."

Comparison with SDD/TDD

Method	Focus	Artifact	Cycle
SDD	Specification clarity	Spec documents	Spec→Design→Implement
TDD	Code quality	Test code	Test→Implement→Refactor
PDD	Progress visualization	Progress matrix	Check→Implement→Scan→Review

If TDD is a methodology for developers, PDD is a methodology for management. These are not mutually exclusive and can be combined.

Application to Team Development

While I conceived this methodology for solo development, it can also be applied to team development. PDD progress tables can be shown directly to non-engineering team members.

Method	Artifact Readability	Progress Visualization	Stakeholder Sharing
SDD	Spec documents (anyone can read)	Fulfillment level (progress hard to see)	Easy
TDD	Test code (for technical people)	pass/fail (progress hard to see)	Explanation needed
PDD	Progress table (anyone can read)	Matrix display (progress easy to understand)	Easy

🔢 Feature × Step Matrix

PDD's characteristic is managing progress with a Feature (vertical axis) × Step (horizontal axis) matrix.

Step Definition

In my project, I manage each feature in 10 stages. I use 10 stages because it makes progress calculation easy at 10% increments (10% × 10 steps = 100%).

#	Step	Content	Owner
01	spec	Specification (requirements)	AI/Human
02	design	Design (API design, DB design, etc.)	AI/Human
03	database	Schema & migrations	AI
04	ui	Screens & components	AI
05	api	API endpoints	AI
06	usecase	Business logic	AI
07	repository	Data access layer	AI
08	unit-test	Unit tests	AI
09	guide	User guide	AI
10	review	Overall review	Human

The number and content of steps can be freely designed according to your product. My product requires a user guide, so I include guide, but you can omit it if unnecessary. 5 or 8 stages work fine too. What's important is clarifying "what constitutes completion."

In my case, 01-spec and 02-design are created collaboratively by humans and AI, 03-09 are implemented by AI. The final 10-review is where humans do the final confirmation.

Status Definition

In my project, I set 5 status levels for each cell.

Status	Symbol	Progress	Meaning
none	`[n]`	0%	Not started
started	`[s]`	25%	Started
draft	`[d]`	50%	Draft complete
reviewed	`[r]`	75%	Reviewed
done	`[x]`	100%	Complete

The number and names of status levels can also be freely designed according to your project. A simple 3-stage "Not started / In progress / Complete" works fine too.

🧩 Progress Management System

In my project, I place progress management files in docs/progress/. I created these by consulting with Claude Code. You can request it with a prompt like this:

I want to create a progress management system for my project.

Requirements:
- Manage progress with JSON files per feature
- Each feature consists of 10 steps (spec, design, database, ui, api, usecase, repository, unit-test, guide, review)
- Status has 5 levels: none/started/draft/reviewed/done
- Also create JSON files listing related file paths per step (for quick document access)
- CLI commands for progress display and auto-scanning
- Matrix format display with color coding

First, propose the directory structure and an example JSON file for one feature.

You don't need to create something perfect from the start. It's fine to improve it as you use it. Below, I'll introduce the structure I actually use.

Directory Structure

docs/progress/
├── features/           # Progress files per feature
│   ├── 01-auth/
│   │   ├── 01-register.json
│   │   ├── 02-verify-email.json
│   │   ├── 03-login.json
│   │   └── ...
│   ├── 02-home/
│   ├── 03-contents/
│   └── ...
├── steps/              # File lists per step
│   ├── 01-spec.json
│   ├── 02-design.json
│   └── ...
├── checklists/         # Completion criteria per step
│   ├── 01-spec.md
│   ├── 02-design.md
│   ├── 03-database.md
│   └── ...
└── scripts/            # CLI tools
    └── pdd.ts          # Provides pdd scan / pdd status

1. Progress Management per Feature

Progress for each feature is managed with JSON files.

{
  "id": "login",
  "name": "Login",
  "description": "Login with email/password",
  "steps": {
    "01-spec": {
      "status": "done",
      "files": [{ "path": "src/_spec.md", "reviewed": false }]
    },
    "02-design": {
      "status": "done",
      "files": [{ "path": "src/client/components/auth/login/_design.md", "reviewed": false }]
    },
    "03-database": { "status": "done", "files": [...] },
    "04-ui": {
      "status": "done",
      "files": [
        { "path": "src/app/[locale]/(auth)/login/page.tsx", "reviewed": false },
        { "path": "src/client/components/auth/login/LoginPage.tsx", "reviewed": false }
      ]
    },
    "05-api": { "status": "done", "files": [...] },
    "06-usecase": { "status": "na" },
    "07-repository": { "status": "na" },
    "08-unit-test": { "status": "done", "files": [...] },
    "09-guide": { "status": "none" },
    "10-review": { "status": "none", "note": "Need final auth flow confirmation" }
  }
}

Key points:

files: Records files created for that step (updated by auto-scan)
reviewed: Tracks whether each file has been reviewed
note: Records supplementary information and TODOs
na: When that step is not applicable

2. Artifact List per Step

The steps/ directory contains JSON files summarizing artifacts (file paths) per step.

In my project, I place design documents (_design.md) near the implementation files. This makes it easier for AI agents to reference designs during implementation. However, when humans review, design documents are scattered and hard to find. By summarizing lists in steps/, both humans and AI agents can proceed with development smoothly.

{
  "step": "02-design",
  "name": "Design",
  "categories": [
    {
      "category": "auth",
      "categoryName": "01 Auth",
      "subcategories": [
        {
          "subcategory": "01-01",
          "subcategoryName": "User Registration",
          "files": [
            { "path": "src/client/components/auth/register/_design.md" }
          ]
        },
        {
          "subcategory": "01-02",
          "subcategoryName": "Email Verification",
          "files": [
            { "path": "src/client/components/auth/verify-email/_design.md" }
          ]
        },
        {
          "subcategory": "01-03",
          "subcategoryName": "Login",
          "files": [
            { "path": "src/client/components/auth/login/_design.md" }
          ]
        }
      ]
    }
  ]
}

Combined with the VS Code extension "Open File From Path," you can place your cursor on a path in the JSON file and press a shortcut key (alt+d) to jump directly to that file. It's convenient when you want to "check design documents" or "see the unit test list."

https://marketplace.visualstudio.com/items?itemName=jack89ita.open-file-from-path

3. Completion Criteria Checklists

Each step has completion criteria defined as checklists. With these checklists, AI can self-determine "what to do next."

04-ui (Screen) example:

## Completion Criteria
- [ ] Required page components exist
- [ ] Required UI components exist
- [ ] TypeScript compiles successfully
- [ ] Screen displays correctly

## Quality Criteria
| State | Criteria |
|-------|----------|
| done | User operations are processed, loading/error states implemented |
| draft | UI displays but operations not implemented, using dummy data |
| none | Component files don't exist |

10-review (Overall Review) example:

## Completion Criteria
- [ ] Code review completed
- [ ] Functionality verification completed
- [ ] Usability confirmed
- [ ] Security review completed

## AI's Role
- AI cannot "perform" the review
- AI can detect and report "review is needed"

🎮 Progress Management Commands

I've prepared a CLI tool pdd for progress management. It's implemented in TypeScript and placed in docs/progress/scripts/pdd.ts.

Command	Role
`pdd scan`	Auto-update status based on file existence
`pdd status`	Display progress in terminal

The benefit of CLI-based management is that it's self-contained locally without requiring external services like progress management tools. Progress data is included in the repository as JSON files, so it can also be version-controlled with Git. Implementation is simple - just JSON file reading/writing and directory traversal. You can implement it in your preferred language or tools.

Auto Scan

Traverses source code and auto-updates progress file statuses.

pdd scan

Behavior:

Traverse source code directories
Check for files corresponding to each feature
Auto-update to done if files exist, none if not
Don't overwrite manually set statuses (draft and started are preserved)

By running this command after implementation, progress is automatically reflected.

Progress Display

Reads progress files and displays progress.

pdd status

Summary Display:

First displays overall progress summary.

Overall Progress  [██████████████░░░░░░] 70%

By Section
  01 Auth               [███████░░░] 68%
  02 Home               [███████░░░] 70%
  03 Contents           [███████░░░] 74%
  04 Search             [██████░░░░] 63%

By Step
  01 spec               [██████████] 100%
  02 design             [██████████] 100%
  03 database           [█████████░] 86%
  08 unit-test          [███░░░░░░░] 25%
  10 review             [░░░░░░░░░░] 0%

You can see at a glance: "70% overall complete," "tests are behind," "review not yet started."

Matrix Display:

Then displays detailed per-feature information in matrix format.

Legend: [n]Not started [s]Started [d]Draft [r]Reviewed [x]Done [-]N/A
Steps: [1]spec [2]design [3]database [4]ui [5]api [6]usecase [7]repository [8]unit-test [9]guide [10]review

🚀 01 Auth
  01 User Registration  [██████░░░░] 63% [x] [x] [x] [-] [-] [x] [x] [n] [n] [n]
  02 Email Verification [███████░░░] 67% [x] [x] [x] [-] [-] [x] [x] [n] [-] [n]
  03 Login              [████████░░] 75% [x] [x] [x] [-] [-] [x] [x] [x] [n] [n]

🚀 02 Home
  01 Bookmarks          [█████████░] 89% [x] [x] [x] [x] [x] [x] [x] [x] [-] [n]
  02 Public             [███████░░░] 67% [x] [x] [-] [-] [-] [x] [x] [n] [-] [n]

In my environment, I display with color coding in the terminal (green=80%+, yellow=50%+, red=below 50%).

🚀 Development Workflow

Daily Workflow

My daily development flow is as follows.

1. Check Progress

pdd status

Check overall progress and what's behind.

2. Instruct AI

"Please implement 08-unit-test for the login feature.
Refer to docs/progress/checklists/08-unit-test.md for the checklist."

AI can self-determine what to do by looking at the checklist.

3. Auto Scan

pdd scan

Detect newly created files and auto-update status.

4. Review
Verify actual operation, update 10-review to done if no issues.

With this repetition, you can continue development without wondering "what to do next."

Combining with Parallel Development

PDD becomes even more efficient when combined with parallel development using Git Worktree.

Worktree	Assigned Steps	Scope
spec-design	01-spec, 02-design	Spec & design documents
database	03-database	Schema & migrations
frontend	04-ui	Screens & components
backend	05-api, 06-usecase, 07-repository	Server-side implementation
unit-test	08-unit-test	Test code
guide	09-guide	Guides & seed data
develop	10-review	Integration, final review

Different AI agents work in parallel in each Worktree, then integrate in the develop branch.

Merge Order (considering dependencies):

1. spec-design  ← Reference for other implementations
2. database     ← Can't write repository without schema
3. frontend     ← Create screen mocks first
4. backend      ← Depends on DB schema
5. unit-test    ← Depends on implementation
6. guide        ← After implementation complete

By merging in order considering dependencies, conflicts are minimized.

For team development, everyone checks progress together, and a manager should consolidate progress file updates to avoid conflicts.

✅ Summary

I introduced Progress-Driven Development (PDD).

Point	Content
Position	Adds progress management perspective to SDD/TDD
Matrix Management	Visualize progress with Feature × Step
Progress System	JSON + Checklists + Auto-scan
Role Division	Spec/Design=collaborate, Implementation=AI, Review=Human
Parallel Development	Multiple AIs work simultaneously with Git Worktree

PDD is a methodology that maximizes AI agent capabilities while humans guarantee final quality. By visualizing progress, "what to do next" becomes clear, helping sustain solo development. It can also be applied to team development.

Tomorrow, I'll write about "Reflecting on 2025 Solo Development."

Other Articles in This Series

12/23: How Claude Code Changed My Solo Dev Workflow: AI Pair Programming
12/25: Reflecting on 2025 Solo Development: Lessons in Technology, Design, and Operations

How Claude Code Changed My Solo Dev Workflow: AI Pair Programming

pipipi-dev — Tue, 23 Dec 2025 07:02:26 +0000

This is Day 23 of the Building a SaaS Solo - Design, Implementation, and Operations Advent Calendar 2025.

Yesterday's article covered "Multi-tenant SaaS Design." Today, I'll share my practical experience developing with Claude Code.

:::message
The basics of Claude Code are well documented in official resources and other articles. This article focuses on my personal workflow and insights gained from continuous use in solo development.
:::

Reference Documents

🛠️ Think Like a Construction Site

Through continuous development with Claude Code, I found that approaching it like a construction site works well.

1. Draw blueprints (Requirements)
2. Build scaffolding (Basic/Detailed Design)
3. Construct (Implementation)
4. Write "why we built it this way" on the walls (Comments, README, CLAUDE.md)
5. Remove scaffolding (Integrate specs into implementation)

Draw Blueprints (Requirements)

First, clarify "what to build."

## Feature Overview
A feature for users to create and manage learning content

## Use Cases
- Create, edit, and delete content
- View own content in a list
- Write body text in Markdown format

## Constraints
- Cannot see other tenants' content
- Title is required, body is optional

By providing this blueprint to Claude Code, the AI can generate code with a complete understanding of the big picture.

Build Scaffolding (Basic/Detailed Design)

Once requirements are set, decide "how to build it." Organize file structure and processing flow in plain language.

## File Structure
- src/types/content.ts - Type definitions
- src/app/api/contents/route.ts - API endpoint
- src/client/components/ContentForm.tsx - Input form

## API Endpoints
### GET /api/contents
- Authentication check
- Filter by tenant_id
- Return in descending order by update time

### POST /api/contents
- Authentication check
- Validation (title required, body optional)
- Save to DB and return created record

With this design document, Claude Code can easily understand "what to implement and how."

Construct (Implementation)

Once scaffolding is ready, it's time to implement. This is where Claude Code shines.

Please implement src/app/api/contents/route.ts.
Follow these specifications:
- GET: Filter by tenant_id and return content list
- POST: Create new content
- Reference existing src/app/api/labels/route.ts for error handling

Having it reference existing code maintains consistency within the project.

Write the Reasoning

After implementation, document "why it was implemented this way" in comments or README.

// Check tenant_id at application layer in addition to RLS
// Defense in depth in case of RLS configuration oversight
const contents = await db
  .select()
  .from(contentsTable)
  .where(eq(contentsTable.tenantId, tenantId));

This record helps future you or AI understand "why it's built this way."

Remove Scaffolding

Finally, integrate design document content into the implementation. Delete temporary TODO comments, organize type definitions, and clean up obsolete specs.

This also "prevents Context pollution." If old design documents or temporary comments remain, AI might read them and get confused. Making source code the Single Source of Truth reduces AI misreadings.

💬 Context Sharing with CLAUDE.md

In Claude Code, placing CLAUDE.md at the project root helps AI understand the project context.

# Project Overview
Memoreru - A tool to organize knowledge and nurture thinking

# Tech Stack
- Next.js 15 (App Router)
- TypeScript strict mode
- Drizzle ORM + PostgreSQL (Supabase)
- Hono (API)
- shadcn/ui

# Coding Conventions
- Use function components
- Prefer named exports
- Error handling uses Result type pattern

# Directory Structure
src/
├── app/          # Next.js App Router
├── client/       # Client-side logic
├── server/       # Server-side logic
├── database/     # DB schema & queries
└── shared/       # Common utilities

Write this once, and you won't need to explain it every time.

Documenting Implementation Patterns

It's also helpful to document project-specific implementation patterns in CLAUDE.md.

# API Endpoint Patterns

## Authenticated Endpoints
1. Get user ID from session
2. Verify access rights to tenant_id
3. Set RLS context
4. Execute processing

## Error Response Format
{ error: string, code?: string }

⚡ Using Extensions

Claude Code has extensions like MCP and Skills.

MCP

MCP (Model Context Protocol) is a protocol that enables integration with external tools. I use these three:

Playwright: Browser automation, E2E testing
Supabase: Database schema inspection
Serena: IDE integration

https://modelcontextprotocol.io

MCP is convenient, but overuse can bloat Context. As AI processes more information, response speed and accuracy can be affected. I recommend limiting to essentials.

https://code.claude.com/docs/mcp

Skills

Skills is a mechanism for templating instructions for specific tasks. Place SKILL.md files in the .claude/skills/ directory.

I haven't fully utilized this yet, but it seems useful for sharing rules like review guidelines across teams. An official Skills marketplace is also available.

https://claude.com/skills

💡 Tips for Interacting with AI

Be Specific

Vague instructions lead to unexpected results. Communicate what you want specifically.

❌ "Make it better"
✅ "Sort the list by update time in descending order"

Request Incrementally

Break large features into smaller requests. If you request everything at once, course corrections become difficult.

1. First, define the Contents table schema
2. Next, create CRUD API endpoints
3. Finally, create the frontend form

State Constraints Explicitly

Communicating what you don't want prevents unintended changes.

Please implement with these constraints:
- Don't change existing API response format
- Don't add new libraries
- Prioritize readability over performance

Prevent Over-Engineering

Claude Code tends to add complexity by considering backward compatibility. Be explicit about keeping things simple.

❌ What AI tends to do on its own:
- Keep old API and add new API
- Create wrapper functions with deprecation warnings
- Add feature flags to toggle between old and new

✅ State explicitly:
"Backward compatibility is not needed. Please modify existing code directly."

🧠 Role Division

Here's the role division between humans and AI that emerged from six months of development.

What Humans Decide

Product direction: What to build, what not to build
Architecture: Technology selection, directory structure
Security: Authentication/authorization design, vulnerability checks
User experience: Usability, clarity
Final verification: Does it actually work without issues?

What to Delegate to AI

Pattern-based code generation: CRUD APIs, form components
Refactoring: Naming consistency, directory organization
Boilerplate creation: Type definitions, test scaffolds
Error investigation: Root cause inference from stack traces

AI changed the "How." The "What" and "Why" remain human work.

Always Review Code

Always review AI-generated code yourself.

Security: Is user ID being taken directly from request?
Type safety: Is any or as any being used to bypass type errors?
Edge cases: Are empty arrays, null values, etc. considered?

AI generates code that "works," but that doesn't mean it's "safe."

Being conscious of this role division has made collaboration with AI smoother. It's not about "delegating everything" but "building together."

✅ Summary

I shared my practices for developing with Claude Code.

Point	Content
Construction Site Approach	Blueprint → Scaffolding → Build → Reasoning → Remove
CLAUDE.md	Share project context with AI
Extensions	MCP/Skills (minimal usage)
Interaction Tips	Be specific, incremental, state constraints
Role Division	How=AI, What/Why=Human, Review required

AI is a powerful tool, but humans are the ones who wield it. I continue development with a mindset of "collaboration" rather than "delegation."

Tomorrow, I'll explain "Progress-Driven Development (PDD)."

Other Articles in This Series

12/22: Building Multi-tenant SaaS as a Solo Developer: Pursuing Enterprise Quality
12/24: Progress-Driven Development (PDD): Solo Development with AI Agents

Building Multi-Tenant SaaS as a Solo Developer

pipipi-dev — Mon, 22 Dec 2025 06:21:05 +0000

This article is part of the Solo SaaS Development Advent Calendar 2025.

In the previous article, I covered GA4 and Microsoft Clarity setup. In this article, I'll share how I built a multi-tenant SaaS architecture.

:::message
The content in this article reflects the design I adopted for my personal project. Rather than best practices, please read this as a record of trial and error from a solo developer.
:::

Why Multi-Tenant?

When building a SaaS, you need to separate data by user.

For team or organization-based services, the following requirements emerge:

Organization A's data must not be visible to Organization B
Even within the same organization, access rights may differ by team
Administrators and regular members have different operation scopes

Multi-tenant architecture realizes these requirements.

Why I Considered Multi-Tenant

For many solo development projects, multi-tenant architecture is probably unnecessary. For consumer-facing services, filtering by user ID is sufficient.

In my case, I was aiming to serve both individual users and enterprise customers, so I designed with multi-tenancy in mind from the start. Adding it later could require restructuring the entire data model.

Tenant Structure Design

In my project, I adopted the following hierarchical structure:

Tenant (Organization)
├── Team A
│   ├── Member 1 (Owner)
│   └── Member 2 (Regular)
└── Team B
    ├── Member 1 (Leader)
    └── Member 3 (View Only)

Tenant Table Design

This table manages tenant (organization) information.

// Example: Tenant table
const tenants = pgTable('tenants', {
  tenant_id: text('tenant_id').primaryKey(),
  name: text('name').notNull(),
  slug: text('slug').unique().notNull(),
  owner_id: text('owner_id').notNull(),
  plan: text('plan').default('free'),
  status: text('status').default('active'),
  settings: jsonb('settings'),
  created_at: timestamp('created_at').defaultNow(),
});

The slug is an identifier used in URLs. settings stores plan-specific limits in JSON format.

Membership Design

This manages the relationship between users and tenants.

// Example: Tenant members table
const tenantMembers = pgTable('tenants_members', {
  tenant_id: text('tenant_id').notNull(),
  user_id: text('user_id').notNull(),
  role: text('role').notNull(), // 'owner' | 'admin' | 'member' | 'viewer'
  status: text('status').default('active'),
  joined_at: timestamp('joined_at').defaultNow(),
}, (table) => ({
  pk: primaryKey({ columns: [table.tenant_id, table.user_id] }),
}));

By using a composite primary key (tenant_id + user_id), I enabled users to belong to multiple tenants.

Role Definition

For example, the following roles can be considered:

Role	Permissions
owner	Full permissions, can delete tenant
admin	Member management, settings changes
member	Create and edit content
viewer	View only

Row-Level Security (RLS)

The most important aspect of multi-tenancy is data isolation. If controlled only through application code, bugs could expose one tenant's data to another.

I adopted PostgreSQL's Row-Level Security (RLS), which enables access control at the database level.

RLS Policy Implementation

-- Enable RLS
ALTER TABLE app_content.labels ENABLE ROW LEVEL SECURITY;

-- SELECT: Only retrieve data from same tenant
CREATE POLICY labels_select_policy ON app_content.labels
  FOR SELECT
  USING (tenant_id = current_setting('app.current_tenant_id', true));

-- INSERT: Only create in same tenant, admin or above
CREATE POLICY labels_insert_policy ON app_content.labels
  FOR INSERT
  WITH CHECK (
    tenant_id = current_setting('app.current_tenant_id', true)
    AND current_setting('app.current_user_role', true) IN ('OWNER', 'ADMIN')
  );

current_setting('app.current_tenant_id', true) retrieves the tenant ID set in the session.

Setting Session Context

I set the current tenant ID and role in the session during API requests.

// Setting in API middleware
async function setTenantContext(tenantId: string, role: string) {
  await db.execute(sql`
    SELECT set_config('app.current_tenant_id', ${tenantId}, true);
    SELECT set_config('app.current_user_role', ${role}, true);
  `);
}

After this, subsequent queries are automatically filtered by RLS policies.

Access Control Implementation

Membership Verification

At API endpoints, I first verify whether the user is a member of the tenant.

// Verify tenant access
async function checkTenantAccess(userId: string, tenantId: string) {
  const membership = await db
    .select({ role: tenantMembers.role })
    .from(tenantMembers)
    .where(and(
      eq(tenantMembers.tenant_id, tenantId),
      eq(tenantMembers.user_id, userId),
      eq(tenantMembers.status, 'active')
    ));

  if (membership.length === 0) {
    throw new Error('Access denied');
  }

  return membership[0].role;
}

Role-Based Permission Checks

I verify the required role for each operation.

// Example: Team creation
app.post('/api/tenants/:tenantId/teams', async (c) => {
  const user = c.get('user');
  const { tenantId } = c.req.param();

  // Verify membership
  const role = await checkTenantAccess(user.id, tenantId);

  // Only owner/admin can create
  if (!['owner', 'admin'].includes(role)) {
    return c.json({ error: 'No permission to create team' }, 403);
  }

  // Team creation logic...
});

Data Isolation with Composite Keys

I use composite primary keys including tenant_id in all content tables.

// Example: Contents table
const contents = pgTable('contents', {
  tenant_id: text('tenant_id').notNull(),
  content_id: text('content_id').notNull(),
  title: text('title').notNull(),
  // ... other columns
}, (table) => ({
  pk: primaryKey({ columns: [table.tenant_id, table.content_id] }),
}));

Master data can be managed as shared data across all tenants using a reserved tenant_id like 'SYSTEM'.

Implementation Tips

Explicit Filtering in Queries

In addition to RLS, I explicitly filter by tenant_id in application code as well.

// Add explicit filter
const userContents = await db
  .select()
  .from(contents)
  .where(and(
    eq(contents.tenant_id, tenantId),  // Explicit filter
    eq(contents.created_by, userId)
  ));

Even with RLS, this makes intent clear during code reviews.

Tenant Switching Consideration

I also implemented switching functionality for users who belong to multiple tenants.

// Get list of tenants user belongs to
async function getUserTenants(userId: string) {
  return await db
    .select({
      tenant: tenants,
      role: tenantMembers.role,
    })
    .from(tenants)
    .innerJoin(tenantMembers, eq(tenants.tenant_id, tenantMembers.tenant_id))
    .where(and(
      eq(tenantMembers.user_id, userId),
      eq(tenantMembers.status, 'active')
    ));
}

The current tenant is managed in the session and can be switched through the UI.

Infrastructure Options

In December 2025, Vercel announced "Vercel for Platforms." It provides features like automatic routing for wildcard domains (*.yourapp.com) and SSL certificate management for custom domains.

https://vercel.com/changelog/introducing-vercel-for-platforms

Combined with the data isolation design introduced in this article, you can build more sophisticated multi-tenant SaaS applications.

Summary

I've shared how I built a multi-tenant SaaS architecture.

Point	Description
Tenant Structure	Organization → Team → Member hierarchy
RLS	Database-level isolation with PostgreSQL
Roles	owner / admin / member / viewer, etc.
Composite Keys	Design with tenant_id in primary keys
Double Check	Verify in both RLS and application code

Whether you need to go this far in solo development depends on your product's nature. However, if you're aiming for enterprise SaaS, considering this from the start makes future expansion easier.

Other Articles in This Series

12/21: Visualizing User Behavior: Setting Up GA4 and Microsoft Clarity
12/23: How Claude Code Changed My Solo Development: AI Pair Programming in Practice

Visualizing User Behavior: Setting Up GA4 and Microsoft Clarity

pipipi-dev — Sun, 21 Dec 2025 04:55:12 +0000

This article is Day 21 of the Solo SaaS Development Advent Calendar 2025.

Yesterday I wrote about implementing tiered pricing with Stripe. Today, I'll cover setting up Google Analytics 4 and Microsoft Clarity to visualize user behavior.

🤔 Why Analytics Matter

Once you launch a service, you naturally want to know how it's being used:

Which pages are most viewed?
Where do users drop off?
Which buttons get clicked?

Without this data, you can't make informed decisions about improvements. Instead of relying on gut feelings, I wanted to make data-driven decisions. That's why I implemented analytics tools.

Tool Selection

I use three tools in combination:

Tool	Purpose	Features
Google Analytics 4	Traffic analysis	User count, page views, traffic sources
Microsoft Clarity	Behavior visualization	Heatmaps, session recordings
Search Console	SEO analysis	Search keywords, rankings

All three are free. While GA4 alone provides basic analysis, combining it with Clarity reveals the "why" behind the numbers.

📈 Setting Up Google Analytics 4

Component Implementation

In Next.js, we use next/script to load the GA4 script:

// components/analytics/GoogleAnalytics.tsx
'use client';

import Script from 'next/script';

interface GoogleAnalyticsProps {
  measurementId: string;
}

export function GoogleAnalytics({ measurementId }: GoogleAnalyticsProps) {
  if (!measurementId) {
    return null;
  }

  return (
    <>
      <Script
        src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
        strategy="afterInteractive"
      />
      <Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', '${measurementId}', {
            page_path: window.location.pathname,
          });
        `}
      </Script>
    </>
  );
}

By specifying strategy="afterInteractive", the script runs without blocking page load, preserving user experience while tracking.

Adding to Layout

Load the component in your root layout. Check for the environment variable to ensure it only runs in production:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  const gaMeasurementId = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;

  return (
    <html>
      <body>
        {children}
        {gaMeasurementId && <GoogleAnalytics measurementId={gaMeasurementId} />}
      </body>
    </html>
  );
}

Sending Custom Events

For tracking specific actions like button clicks, use custom events:

export function trackEvent(
  eventName: string,
  eventParams?: Record<string, string | number | boolean>
) {
  if (typeof window !== 'undefined' && 'gtag' in window) {
    (window as Window & { gtag: (...args: unknown[]) => void }).gtag(
      'event',
      eventName,
      eventParams
    );
  }
}

// Usage examples
trackEvent('button_click', { button_name: 'signup' });
trackEvent('content_view', { content_id: '123' });

🎥 Setting Up Microsoft Clarity

Clarity visualizes user behavior through heatmaps and session recordings. While GA4 tells you "what happened," Clarity shows you "why it happened."

Component Implementation

Similar to GA4, load it using next/script:

// components/analytics/MicrosoftClarity.tsx
'use client';

import Script from 'next/script';

interface MicrosoftClarityProps {
  projectId: string;
}

export function MicrosoftClarity({ projectId }: MicrosoftClarityProps) {
  if (!projectId) {
    return null;
  }

  return (
    <Script id="microsoft-clarity" strategy="afterInteractive">
      {`
        (function(c,l,a,r,i,t,y){
          c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
          t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
          y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
        })(window, document, "clarity", "script", "${projectId}");
      `}
    </Script>
  );
}

User Identification

To identify logged-in users, use Clarity's API:

export function identifyClarityUser(userId: string) {
  if (typeof window !== 'undefined' && 'clarity' in window) {
    (window as Window & { clarity: (...args: unknown[]) => void }).clarity(
      'identify',
      userId
    );
  }
}

// Set tags for segmentation
export function setClarityTag(key: string, value: string) {
  if (typeof window !== 'undefined' && 'clarity' in window) {
    (window as Window & { clarity: (...args: unknown[]) => void }).clarity(
      'set',
      key,
      value
    );
  }
}

// Usage examples
identifyClarityUser('user_123');
setClarityTag('plan', 'premium');

By setting tags per plan, you can analyze differences in behavior between free and paid users.

🔍 Setting Up Search Console

Foundation for SEO Analysis

Search Console analyzes your performance in Google search:

What keywords are users searching for?
How many times did you appear in search results?
What's your click-through rate?

Unlike GA4 and Clarity, it shows user behavior before they reach your site.

Ownership Verification

To use Search Console, you need to verify site ownership. The HTML tag method is the simplest:

// app/layout.tsx
export const metadata: Metadata = {
  verification: {
    google: 'your-verification-code',
  },
};

This outputs a <meta name="google-site-verification"> tag. Just click the verify button in the Search Console dashboard to complete setup.

Note that unlike GA4 and Clarity, data takes 1-2 days to appear. Make it a habit to check regularly.

🔗 Tool Integration

Connecting the three tools enables deeper analysis.

GA4 and Search Console Integration

Link Search Console from the GA4 admin panel to combine search queries with on-site behavior analysis.

This allows analysis like "Which pages do users who came from this search keyword view most?"

GA4 and Clarity Integration

Enable "Google Analytics integration" in Clarity settings to link GA4 sessions with Clarity recordings.

When GA4 shows a page with high bounce rate, you can watch the Clarity recordings for that page to understand why.

💡 Implementation Tips

Enable Only in Production

Development traffic creates noise in your data. Use environment variables to enable analytics only in production:

# .env.local (development)
# Don't set these

# Vercel environment variables (production)
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
NEXT_PUBLIC_CLARITY_PROJECT_ID=xxxxxxxxxx

If the environment variable isn't set, the component renders nothing.

Data Reflection Timing

Tool	Reflection Time
GA4	Real-time
Clarity	Real-time
Search Console	1-2 days

GA4 and Clarity data is immediately available, but Search Console takes time. I check SEO data the next day.

CSP Configuration

If you have Content Security Policy (CSP) configured, you need to allow the analytics domains:

// middleware.ts
const cspHeader = `
  script-src 'self' https://www.googletagmanager.com https://*.clarity.ms;
  connect-src 'self' https://www.google-analytics.com https://*.clarity.ms;
`;

Forgetting this will block the analytics scripts.

✅ Summary

I covered setting up three analytics tools:

Tool	Purpose
GA4	Traffic analysis, detailed tracking with custom events
Clarity	Visualize behavior with heatmaps and session recordings
Search Console	SEO analysis with search keywords and rankings

Key implementation points: enable only in production, don't forget CSP settings, and integrate the tools together.

For solo development, you don't need to track every metric. Start with "which pages are most viewed" and "where users drop off," then add more tracking as needed.

Tomorrow I'll cover building a multi-tenant SaaS as a solo developer.

Other Articles in This Series

Day 20: Tiered Pricing with Stripe: Monetization for Solo Developers
Day 22: Building Multi-tenant SaaS as a Solo Developer

Tiered Pricing with Stripe: Monetization for Solo Developers

pipipi-dev — Sat, 20 Dec 2025 03:56:16 +0000

This article is part of the Solo SaaS Development Advent Calendar 2025 (Day 20).

Yesterday I wrote about "Security Practices." In this article, I'll share how I designed and implemented tiered pricing with Stripe.

:::message
The content in this article reflects the approach I adopted for my personal product. Rather than best practices, please read this as a record of trial and error from a solo developer.
:::

🤔 Thinking About Monetization for Solo Projects

When building a service as a solo developer, monetization is an unavoidable challenge.

Providing a service for free indefinitely isn't realistic. Server costs, domain fees, API usage charges—operational costs are guaranteed. Revenue is necessary for a sustainable service.

Why I Chose Stripe

There are several payment services available, but I chose Stripe.

Comprehensive documentation: The official docs are detailed, so implementation rarely gets stuck
Easy-to-use test environment: You can test with test API keys using the same features as production
Complex processes handled for you: No need to implement cancellation, plan changes, or invoice generation yourself

In solo development, choosing "not to implement it yourself" is important. Payment processing is an area where mistakes are especially unforgivable, so I decided to entrust it to a reliable service.

🎯 Designing the Pricing Plan

When designing the pricing plan, I focused on tiered value delivery.

Design Considerations

1. The free plan should be fully usable

I made sure the free plan includes usable core features. The goal is not "I tried it but it wasn't enough," but rather "I tried it and it was useful, I want to use it more."

I aimed to let users experience value for free first, then have those who want more consider paid plans.

2. Price differences have reasons

Higher-tier plans have clear value differentiators: more pages, more storage, more team members. It's important to be able to explain "why this price."

3. Feature restrictions based on operational costs

AI features and API access are only available on higher-tier plans. These incur costs based on usage, so opening them to free users would inflate operational costs.

Type Definition for Plan Limits

I define "what can be used and to what extent" for each plan using types.

interface PlanLimits {
  maxPages: number;         // Number of pages that can be created
  maxTables: number;        // Number of tables that can be created
  maxStorageMB: number;     // Storage capacity (MB)
  maxTeamMembers: number;   // Number of team members
  maxApiCallsPerMonth: number;  // Monthly API call limit
  hasApiAccess: boolean;    // API access available
  hasAiFeatures: boolean;   // AI features available
}

Based on this type, I set limit values for each plan. The system checks the current plan's limits whenever a user performs an action.

🧩 Stripe Implementation

Creating a Checkout Session

Here's the flow when a user clicks the "Upgrade" button:

Create a Stripe "Checkout Session" on the server side
Return the URL of the Stripe-hosted payment page
Redirect the user to that URL

The key point is not handling card information on your own server. By redirecting to Stripe's page, you significantly reduce security risks.

// app/api/billing/create-checkout/route.ts
export async function POST(request: Request) {
  const { priceId, planType } = await request.json();
  const session = await auth();

  if (!session?.user?.id) {
    return Response.json({ error: 'Authentication required' }, { status: 401 });
  }

  // Get or create Stripe customer
  const customer = await getOrCreateCustomer(session.user.id);

  // Create Checkout session
  const checkoutSession = await stripe.checkout.sessions.create({
    customer: customer.id,
    payment_method_types: ['card'],
    mode: 'subscription',  // Subscription billing
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXTAUTH_URL}/billing/success`,
    cancel_url: `${process.env.NEXTAUTH_URL}/billing/cancel`,
    metadata: { userId: session.user.id, planType },  // For later use
  });

  return Response.json({ url: checkoutSession.url });
}

The key is including the user ID in metadata. When the payment completes, we receive it via Webhook to identify which user made the payment.

Managing Subscriptions with Webhooks

When a payment completes, we need to update the database. But since the payment completion happens on Stripe's page, our server doesn't know about it directly.

This is where Webhooks come in. When events like payment completion occur, Stripe sends HTTP requests to a pre-registered URL.

// app/api/webhooks/stripe/route.ts
export async function POST(request: Request) {
  const body = await request.text();
  const signature = headers().get('stripe-signature')!;

  // Verify signature (confirm it's a legitimate request from Stripe)
  const event = stripe.webhooks.constructEvent(
    body,
    signature,
    process.env.STRIPE_WEBHOOK_SECRET!
  );

  // Branch processing based on event type
  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckoutCompleted(event.data.object);
      break;
    case 'customer.subscription.updated':
      await handleSubscriptionUpdated(event.data.object);
      break;
    case 'customer.subscription.deleted':
      await handleSubscriptionDeleted(event.data.object);
      break;
  }

  return Response.json({ received: true });
}

Signature verification (constructEvent) is essential. Without it, malicious third parties could send fake requests.

When we receive a checkout.session.completed event, we save the subscription information to the database.

async function handleCheckoutCompleted(session: Stripe.Checkout.Session) {
  // Get user info from metadata
  const { userId, planType } = session.metadata!;

  const subscription = await stripe.subscriptions.retrieve(
    session.subscription as string
  );

  // Save to database
  await db.insert(subscriptions).values({
    userId,
    planType,
    status: 'active',
    subscriptionId: subscription.id,
    currentPeriodEnd: new Date(subscription.current_period_end * 1000),
  });
}

Customer Portal

I leave cancellation and plan changes to Stripe's Customer Portal.

export async function createCustomerPortalSession(userId: string, returnUrl: string) {
  const subscription = await getSubscription(userId);

  const portalSession = await stripe.billingPortal.sessions.create({
    customer: subscription.customerId,
    return_url: returnUrl,  // URL to return to from portal
  });

  return portalSession.url;
}

The Customer Portal handles everything:

Plan changes (upgrade/downgrade)
Payment method changes
Invoice viewing
Cancellation

Implementing these yourself means dealing with many edge cases: "How to handle prorated billing?" "What about remaining time after cancellation?" By leaving it to Stripe, I significantly reduced implementation costs.

💡 Implementation Tips

Checking Plan Limits

Check plan limits whenever a user performs an action.

export async function checkPlanLimit(
  userId: string,
  resource: 'pages' | 'tables' | 'storage',
  currentCount: number
): Promise<{ allowed: boolean; limit: number }> {
  const subscription = await getSubscription(userId);
  const limits = getPlanLimits(subscription?.planType ?? 'free');

  const limitMap = {
    pages: limits.maxPages,
    tables: limits.maxTables,
    storage: limits.maxStorageMB,
  };

  return {
    allowed: currentCount < limitMap[resource],
    limit: limitMap[resource],
  };
}

Here's an example of checking when creating a page:

export async function createPage(userId: string, data: PageData) {
  const pageCount = await getPageCount(userId);
  const check = await checkPlanLimit(userId, 'pages', pageCount);

  if (!check.allowed) {
    throw new Error('Page limit reached');
  }

  return await db.insert(pages).values({ ...data, userId });
}

When the limit is reached, I display a UI prompting an upgrade.

Webhook Idempotency

The same event may be sent multiple times. This happens because Stripe resends due to network issues.

Idempotency means "the result doesn't change no matter how many times you execute the same process." For Webhooks, you need to handle the same request coming in without issues.

await db
  .insert(subscriptions)
  .values(subscriptionData)
  .onConflictDoUpdate({
    target: subscriptions.subscriptionId,
    set: subscriptionData,
  });

By making subscriptionId a unique key, existing records get updated rather than duplicated. This prevents duplicate registrations.

Using the Test Environment

Stripe has production and test environments. You can switch between them just by changing API keys.

# Development
STRIPE_SECRET_KEY=sk_test_...

# Production
STRIPE_SECRET_KEY=sk_live_...

In the test environment, you can try the payment flow with test card numbers (like 4242 4242 4242 4242). No actual charges occur, so you can develop with confidence.

✅ Summary

I've shared my approach and implementation points for tiered pricing with Stripe.

Point	Content
Pricing design	Free plan is usable, price differences have reasons
Checkout	Use Stripe's hosted payment page
Webhook	Event-driven DB updates, signature verification is essential
Customer Portal	Leave cancellation and changes to Stripe
Test environment	Safely test payment flows

In solo development, it's also important not to spend too much time on payment processing. Stripe's documentation is comprehensive, so I recommend implementing while reading the official docs.

https://docs.stripe.com/

Tomorrow I'll cover "Visualizing User Behavior: Setting Up GA4 and Microsoft Clarity."

Other articles in this series

12/19: What the React 2025 Vulnerability Taught Me About Solo Dev Security
12/21: Visualizing User Behavior: Setting Up GA4 and Microsoft Clarity

What the React 2025 Vulnerability Taught Me About Solo Dev Security

pipipi-dev — Fri, 19 Dec 2025 05:45:00 +0000

This article is part of the and Design Advent Calendar 2025 (Day 19).

Yesterday I wrote about "TypeScript Strict Mode." In this article, I'll share the security practices I follow in my solo development projects.

🚨 Security Incidents in December 2025

In December 2025, critical vulnerabilities were discovered in the Next.js/React ecosystem. Security is not someone else's problem, even for solo developers.

React Server Components Vulnerability (CVE-2025-55182)

On December 3, 2025, a remote code execution vulnerability in React Server Components was disclosed. The CVSS score, which indicates severity, is 10.0—the maximum possible value.

https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components

Affected: All applications using React 19.0 to 19.2.0
Attack vector: Malicious HTTP requests can execute arbitrary code on the server
Affected frameworks: Next.js, React Router, Waku, Parcel RSC, and others

# For Next.js, update to a patched version
npm install next@15.1.11  # For 15.1.x
npm install next@15.0.7   # For 15.0.x
npm install next@14.2.35  # For 14.x

For Memoreru, the app I'm developing, I noticed a warning on Vercel's deployment screen and immediately updated to Next.js 15.5.9 and React 19.2.3. Because I had made a habit of keeping dependencies updated, the transition was smooth.

https://x.com/pipipi_dev/status/1996301018532118914

Multiple Node.js Vulnerabilities

Also in December 2025, multiple vulnerabilities were reported in Node.js.

https://nodejs.org/en/blog/vulnerability/december-2025-security-releases

Severity	Count	Affected Versions
High	3	v20.x, v22.x, v24.x, v25.x
Medium	1	Same as above
Low	1	Same as above

Patches are scheduled for release on January 7, 2026 (as of December 19, 2025).

🛡️ Security Practices I Follow

Here are the security measures I've implemented in Memoreru's development.

1. Keeping Dependencies Updated

The most fundamental and effective measure is keeping dependencies up to date.

# Check for vulnerabilities
npm audit

# Fix automatically fixable vulnerabilities
npm audit fix

# For breaking changes (use with caution)
npm audit fix --force

Setting up Dependabot or Renovate automatically creates PRs for dependency updates.

2. Input Validation

I implement with the assumption that all user input is untrusted. Using Zod, you can manage validation and type definitions in one place.

import { z } from 'zod';

// Schema definition
const CreateUserSchema = z.object({
  email: z.string().email('Please enter a valid email address'),
  password: z
    .string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, 'Must include uppercase, lowercase, and numbers'),
  name: z.string().min(1).max(100),
});

// Validation execution
const result = CreateUserSchema.safeParse(requestBody);
if (!result.success) {
  return Response.json({ error: result.error.issues }, { status: 400 });
}

// result.data is type-safe
const { email, password, name } = result.data;

I validate API query parameters the same way.

const QuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  search: z.string().max(200).optional(),
});

3. Authentication and Authorization

I use libraries for authentication rather than building it myself. For Memoreru, I chose Better Auth. Auth.js is also an option.

// API middleware requiring authentication
export async function requireAuth(request: Request) {
  const session = await getSession();

  if (!session?.user?.id) {
    return Response.json(
      { error: 'Authentication required' },
      { status: 401 }
    );
  }

  return session;
}

I also implement authorization (permission checks).

// Resource ownership check
const content = await db.query.contents.findFirst({
  where: (contents, { eq }) => eq(contents.id, contentId),
});

if (content?.userId !== session.user.id) {
  return Response.json(
    { error: 'You do not have permission to access this resource' },
    { status: 403 }
  );
}

4. Environment Variable Management

I manage secrets through environment variables and avoid hardcoding them in code.

# .env.local (include in gitignore)
DATABASE_URL="postgresql://user:password@host:5432/db"
AUTH_SECRET="random string of 32+ characters"
STRIPE_SECRET_KEY="sk_live_..."

I prepare a .env.example file for developers to document required environment variables.

# .env.example (commit to repository)
DATABASE_URL="postgresql://user:password@host:5432/db"
AUTH_SECRET=""
STRIPE_SECRET_KEY=""

5. Security Headers

In Next.js, you can configure security headers in next.config.ts.

const nextConfig: NextConfig = {
  headers: async () => [
    {
      source: '/:path*',
      headers: [
        // Clickjacking protection
        { key: 'X-Frame-Options', value: 'DENY' },
        // MIME sniffing protection
        { key: 'X-Content-Type-Options', value: 'nosniff' },
        // Referrer information control
        { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
        // Disable unnecessary features
        { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
      ],
    },
  ],
};

In production, I also add the HSTS (HTTP Strict Transport Security) header. This header ensures browsers automatically use HTTPS.

{
  key: 'Strict-Transport-Security',
  value: 'max-age=31536000; includeSubDomains'
}

6. CSRF Protection

CSRF (Cross-Site Request Forgery) is an attack that tricks users into sending unintended requests. For example, simply opening a malicious site could trigger actions on a service you're logged into.

As a countermeasure, I use CSRF tokens for form submissions and API requests.

// Token generation (with HMAC-SHA256 signature)
async function generateCsrfToken(userId: string): Promise<string> {
  const timestamp = Date.now();
  const nonce = crypto.randomUUID();
  const payload = `${userId}:${timestamp}:${nonce}`;

  const signature = await signWithHmac(payload, process.env.CSRF_SECRET);
  return `${Buffer.from(payload).toString('base64')}.${signature}`;
}

// Token validation
async function validateCsrfToken(token: string, userId: string): Promise<boolean> {
  const [payloadBase64, signature] = token.split('.');
  const payload = Buffer.from(payloadBase64, 'base64').toString();
  const [tokenUserId, timestamp] = payload.split(':');

  // Signature verification
  const expectedSignature = await signWithHmac(payload, process.env.CSRF_SECRET);
  if (signature !== expectedSignature) return false;

  // Expiration check (1 hour)
  if (Date.now() - parseInt(timestamp) > 3600000) return false;

  // User ID match check
  if (tokenUserId !== userId) return false;

  return true;
}

7. SQL Injection Protection

SQL injection is an attack that executes malicious SQL through user input. For example, entering special characters in a login form could bypass authentication or steal data.

Using an ORM (a library that lets you write database operations in code) correctly is generally safe, but when writing raw SQL, I use parameterized queries.

// Dangerous: String concatenation
const query = `SELECT * FROM users WHERE email = '${email}'`;

// Safe: Parameterized query
const query = `SELECT * FROM users WHERE email = $1`;
const result = await db.query(query, [email]);

Using Drizzle ORM or Prisma automatically parameterizes queries.

// With Drizzle ORM
const users = await db
  .select()
  .from(usersTable)
  .where(eq(usersTable.email, email));

8. Rate Limiting

Rate limiting restricts the number of requests within a time window. This helps mitigate DoS attacks that overwhelm servers with requests, and brute force password attacks.

Here's a simple implementation.

const rateLimitMap = new Map<string, { count: number; resetTime: number }>();

export function checkRateLimit(
  identifier: string,
  maxRequests = 100,
  windowMs = 60000
): boolean {
  const now = Date.now();
  const record = rateLimitMap.get(identifier);

  if (!record || now > record.resetTime) {
    rateLimitMap.set(identifier, { count: 1, resetTime: now + windowMs });
    return true;
  }

  if (record.count >= maxRequests) {
    return false; // Rate limit exceeded
  }

  record.count++;
  return true;
}

For production scaling, distributed rate limiting using Redis with services like Upstash is also an option.

📋 Security Checklist

Here's a summary of items I check.

Category	Check Item
Dependencies	No vulnerabilities in `npm audit`
Dependencies	Major packages (Next.js, React, Node.js) are up to date
Input Validation	All user input is validated
Authentication	Using an auth library (not custom implementation)
Authorization	Resource access permissions are verified
Environment Variables	No secrets hardcoded in code
Headers	Security headers are configured
HTTPS	HTTPS is enforced in production
CSRF	CSRF tokens are used for form submissions
SQL	Using parameterized queries or ORM
API	Rate limiting is implemented

🔔 Staying Updated on Vulnerabilities

Make it a habit to regularly check security information. Following official accounts and developers who actively share security information on social media like X helps you catch important updates quickly.

Next.js Security - Next.js official
React Blog - React official
Node.js Security Releases - Node.js official

✅ Summary

Even for solo development, basic security measures are essential.

Measure	Priority	Reason
Dependency updates	Highest	Prevents known vulnerabilities
Input validation	Highest	Entry point for many attacks
Authentication/Authorization	High	Prevents unauthorized access
Environment variable management	High	Prevents information leaks
Security headers	High	Effective with minimal effort
CSRF protection	High	Prevents unintended actions
SQL injection protection	Medium	Handled automatically by ORM
Rate limiting	Medium	Mitigates high-volume attacks

"I'll add security later" is dangerous. Building in basic protections from the start lets you develop with peace of mind.

Tomorrow I'll cover "Implementing Tiered Pricing with Stripe."

Other articles in this series

12/18: TypeScript Strict Mode in Practice: Catching Bugs with Type Safety
12/20: Implementing Tiered Pricing with Stripe: Monetization Design for Solo Developers

TypeScript Strict Mode in Practice: Catching Bugs with Type Safety

pipipi-dev — Fri, 19 Dec 2025 05:44:57 +0000

This article is part of the and Design Advent Calendar 2025 (Day 18).

Yesterday I wrote about "Semantic Search." Today, I'll share my experience introducing TypeScript's strict mode to an existing project.

Why I Introduced Strict Mode

Even with TypeScript, runtime errors still occur.

Cannot read property 'name' of null
undefined is not a function

When these errors started piling up, I investigated and found a common pattern. They were happening in places where type checking was too lenient.

TypeScript uses lenient settings by default. Without enabling strict mode, many problems slip through undetected.

Options I Enabled

{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false
  }
}

noImplicitAny

Parameters without type annotations implicitly become any type. Since any allows any operation, type checking becomes ineffective.

// With noImplicitAny: false
function double(value) {  // value is any type
  return value * 2;
}

double("hello");  // Compiles fine, but result is NaN

With noImplicitAny: true, parameters without type annotations cause errors. You can immediately spot "places where you forgot to write types."

strictNullChecks

Without this option, all types implicitly include null and undefined.

// With strictNullChecks: false
const user: User = getUser();  // Might return null
console.log(user.name);  // Could crash at runtime

With strictNullChecks: true, functions that might return null must explicitly declare User | null. Since you get compile errors without null checks, you can prevent missed checks.

Effect of These Two Options

Option	Errors Prevented
`noImplicitAny`	Crashes from operating on unknown types
`strictNullChecks`	Crashes from null/undefined access

I delegated unused variable checking (noUnusedLocals) to Biome. TypeScript doesn't recognize _ prefixed variables, which causes issues when you only want to use part of a destructured assignment.

Division of Responsibilities: TypeScript and Biome

Biome is a tool that combines linting (code quality checking) and formatting (code styling). I chose it over ESLint because it's faster and has simpler configuration.

I divide checking responsibilities between TypeScript and Biome.

Check Item	Tool	Reason
Type consistency	TypeScript	Core strength of the type system
Null safety	TypeScript	Detectable at type level
Unused variables	Biome	Supports `_` prefix convention
any type usage	Biome	Easier exception management with biome-ignore
Code style	Biome	Managed together with formatting

Here's an example Biome configuration.

{
  "linter": {
    "rules": {
      "correctness": {
        "noUnusedVariables": "warn",
        "noUnusedImports": "warn"
      },
      "suspicious": {
        "noExplicitAny": "error",
        "noDoubleEquals": "error"
      }
    }
  }
}

By setting noExplicitAny to error, I strictly limit the use of any types. When absolutely necessary, I leave a comment explaining why.

Bugs Prevented by Strict Mode

Here are typical bug patterns that strict mode can detect.

1. Missing Null Checks

The most common issue is missing null checks.

// Problematic code
function getUserName(user: User | null) {
  return user.name; // user might be null
}

With strictNullChecks enabled, this becomes a compile-time error.

// Fixed
function getUserName(user: User | null) {
  return user?.name ?? 'Anonymous';
}

This pattern is especially common with relational data. When a user is deleted, the creator field of related data becomes null. Code that doesn't account for this will crash at runtime.

2. Handling Optional Properties

Optional properties in API responses are another easy-to-miss pattern.

interface ApiResponse {
  data: {
    items: Item[];
    nextCursor?: string; // Optional
  };
}

// Problematic code
function getNextPage(response: ApiResponse) {
  return fetch(`/api?cursor=${response.data.nextCursor}`);
  // If nextCursor is undefined, this becomes "?cursor=undefined"
}

// Fixed
function getNextPage(response: ApiResponse) {
  if (!response.data.nextCursor) return null;
  return fetch(`/api?cursor=${response.data.nextCursor}`);
}

3. Type Definition and Schema Mismatch

During refactoring, it's easy to forget to update type definitions.

// Changed DB schema
// column_name → field_name

// Forgot to update type definition
interface Column {
  column_name: string; // Still using old name
}

With strict mode, everywhere using this type will show errors. You'll see red underlines in your IDE, so you won't miss any needed fixes.

IDE Benefits

When you enable strict mode, you immediately benefit in editors like VS Code.

Real-time Error Detection

When you write problematic code, red squiggly lines appear in the editor. You can catch issues before running the code, dramatically reducing debugging time.

Accurate Completions

When types are clear, property and method completion suggestions become accurate. When you type user., only properties that actually exist like name and email appear as suggestions.

Safer Refactoring

When you change a type definition, errors appear everywhere affected. You don't need to manually search for "what needs to be fixed."

// If you remove email from User type
interface User {
  id: string;
  name: string;
  // email: string;  removed
}

// Errors appear everywhere user.email is used

If there are any missed fixes, you get compile errors, so you can change code with confidence.

Preventing New Errors

Even if you fix existing errors, it's pointless if new code introduces more.

Husky is a tool for managing git hooks (scripts that run automatically on commit or push). I set up a pre-commit hook to run type checking before every commit.

#!/bin/sh
# .husky/pre-commit

echo "Running type check..."
bun run type-check

if [ $? -ne 0 ]; then
  echo "TypeScript errors found. Please fix before committing."
  exit 1
fi

{
  "scripts": {
    "type-check": "tsc --noEmit"
  }
}

Commits are blocked if there are TypeScript errors. Since "I'll fix it later" isn't allowed, errors don't accumulate.

Tips for Gradual Adoption

Here are tips for introducing strict mode to an existing project.

1. Progress Gradually

Trying to fix a large number of errors at once is discouraging. A more sustainable approach is to fix a few surrounding errors while working on features, or make only new files strict first and gradually convert the rest.

2. Document Reasons for any Types

When you absolutely need an any type, leave a comment explaining why. This allows for review when type definitions improve later.

// TODO: Type definitions will improve in library v3
// biome-ignore lint/suspicious/noExplicitAny: temporary workaround
const result = someLibrary.parse(data) as any;

3. Validate External Data with Zod

Zod is a library for runtime data validation. When you define a schema, TypeScript types are automatically generated.

For external data like API responses and form inputs, validate with Zod. This lets you manage type definitions and validation in one place.

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

// Validate at runtime
const user = UserSchema.parse(apiResponse);

Summary

Here are the key points for introducing TypeScript strict mode to an existing project.

Point	Details
Enable selectively	Choose high-impact options rather than `strict: true`
Divide responsibilities	Split duties between TypeScript and Biome
Fix gradually	Progress bit by bit, not all at once
Prevent accumulation	Make type checking mandatory with pre-commit hooks

Ideally, these settings should be enabled from the project's start. Since retrofitting them incurs fixing costs, I recommend enabling strict mode from the beginning for new projects.

Tomorrow I'll discuss "Security Measures for Solo Development."

Other Articles in This Series

12/17: Implementing "Search by Meaning": Introduction to pgvector + OpenAI Embeddings
12/19: Security Measures for Solo Development: The Minimum You Should Do

TypeScript Strict Mode in Practice: Catching Bugs with Type Safety

pipipi-dev — Thu, 18 Dec 2025 00:00:51 +0000

This article is part of the and Design Advent Calendar 2025 (Day 18).

Yesterday I wrote about "Semantic Search." Today, I'll share my experience introducing TypeScript's strict mode to an existing project.

Why I Introduced Strict Mode

Even with TypeScript, runtime errors still occur.

Cannot read property 'name' of null
undefined is not a function

When these errors started piling up, I investigated and found a common pattern. They were happening in places where type checking was too lenient.

TypeScript uses lenient settings by default. Without enabling strict mode, many problems slip through undetected.

Options I Enabled

{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false
  }
}

noImplicitAny

Parameters without type annotations implicitly become any type. Since any allows any operation, type checking becomes ineffective.

// With noImplicitAny: false
function double(value) {  // value is any type
  return value * 2;
}

double("hello");  // Compiles fine, but result is NaN

With noImplicitAny: true, parameters without type annotations cause errors. You can immediately spot "places where you forgot to write types."

strictNullChecks

Without this option, all types implicitly include null and undefined.

// With strictNullChecks: false
const user: User = getUser();  // Might return null
console.log(user.name);  // Could crash at runtime

With strictNullChecks: true, functions that might return null must explicitly declare User | null. Since you get compile errors without null checks, you can prevent missed checks.

Effect of These Two Options

Option	Errors Prevented
`noImplicitAny`	Crashes from operating on unknown types
`strictNullChecks`	Crashes from null/undefined access

I delegated unused variable checking (noUnusedLocals) to Biome. TypeScript doesn't recognize _ prefixed variables, which causes issues when you only want to use part of a destructured assignment.

Division of Responsibilities: TypeScript and Biome

Biome is a tool that combines linting (code quality checking) and formatting (code styling). I chose it over ESLint because it's faster and has simpler configuration.

I divide checking responsibilities between TypeScript and Biome.

Check Item	Tool	Reason
Type consistency	TypeScript	Core strength of the type system
Null safety	TypeScript	Detectable at type level
Unused variables	Biome	Supports `_` prefix convention
any type usage	Biome	Easier exception management with biome-ignore
Code style	Biome	Managed together with formatting

Here's an example Biome configuration.

{
  "linter": {
    "rules": {
      "correctness": {
        "noUnusedVariables": "warn",
        "noUnusedImports": "warn"
      },
      "suspicious": {
        "noExplicitAny": "error",
        "noDoubleEquals": "error"
      }
    }
  }
}

By setting noExplicitAny to error, I strictly limit the use of any types. When absolutely necessary, I leave a comment explaining why.

Bugs Prevented by Strict Mode

Here are typical bug patterns that strict mode can detect.

1. Missing Null Checks

The most common issue is missing null checks.

// Problematic code
function getUserName(user: User | null) {
  return user.name; // user might be null
}

With strictNullChecks enabled, this becomes a compile-time error.

// Fixed
function getUserName(user: User | null) {
  return user?.name ?? 'Anonymous';
}

This pattern is especially common with relational data. When a user is deleted, the creator field of related data becomes null. Code that doesn't account for this will crash at runtime.

2. Handling Optional Properties

Optional properties in API responses are another easy-to-miss pattern.

interface ApiResponse {
  data: {
    items: Item[];
    nextCursor?: string; // Optional
  };
}

// Problematic code
function getNextPage(response: ApiResponse) {
  return fetch(`/api?cursor=${response.data.nextCursor}`);
  // If nextCursor is undefined, this becomes "?cursor=undefined"
}

// Fixed
function getNextPage(response: ApiResponse) {
  if (!response.data.nextCursor) return null;
  return fetch(`/api?cursor=${response.data.nextCursor}`);
}

3. Type Definition and Schema Mismatch

During refactoring, it's easy to forget to update type definitions.

// Changed DB schema
// column_name → field_name

// Forgot to update type definition
interface Column {
  column_name: string; // Still using old name
}

With strict mode, everywhere using this type will show errors. You'll see red underlines in your IDE, so you won't miss any needed fixes.

IDE Benefits

When you enable strict mode, you immediately benefit in editors like VS Code.

Real-time Error Detection

When you write problematic code, red squiggly lines appear in the editor. You can catch issues before running the code, dramatically reducing debugging time.

Accurate Completions

When types are clear, property and method completion suggestions become accurate. When you type user., only properties that actually exist like name and email appear as suggestions.

Safer Refactoring

When you change a type definition, errors appear everywhere affected. You don't need to manually search for "what needs to be fixed."

// If you remove email from User type
interface User {
  id: string;
  name: string;
  // email: string;  removed
}

// Errors appear everywhere user.email is used

If there are any missed fixes, you get compile errors, so you can change code with confidence.

Preventing New Errors

Even if you fix existing errors, it's pointless if new code introduces more.

Husky is a tool for managing git hooks (scripts that run automatically on commit or push). I set up a pre-commit hook to run type checking before every commit.

#!/bin/sh
# .husky/pre-commit

echo "Running type check..."
bun run type-check

if [ $? -ne 0 ]; then
  echo "TypeScript errors found. Please fix before committing."
  exit 1
fi

{
  "scripts": {
    "type-check": "tsc --noEmit"
  }
}

Commits are blocked if there are TypeScript errors. Since "I'll fix it later" isn't allowed, errors don't accumulate.

Tips for Gradual Adoption

Here are tips for introducing strict mode to an existing project.

1. Progress Gradually

2. Document Reasons for any Types

When you absolutely need an any type, leave a comment explaining why. This allows for review when type definitions improve later.

// TODO: Type definitions will improve in library v3
// biome-ignore lint/suspicious/noExplicitAny: temporary workaround
const result = someLibrary.parse(data) as any;

3. Validate External Data with Zod

Zod is a library for runtime data validation. When you define a schema, TypeScript types are automatically generated.

For external data like API responses and form inputs, validate with Zod. This lets you manage type definitions and validation in one place.

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

// Validate at runtime
const user = UserSchema.parse(apiResponse);

Summary

Here are the key points for introducing TypeScript strict mode to an existing project.

Point	Details
Enable selectively	Choose high-impact options rather than `strict: true`
Divide responsibilities	Split duties between TypeScript and Biome
Fix gradually	Progress bit by bit, not all at once
Prevent accumulation	Make type checking mandatory with pre-commit hooks

Ideally, these settings should be enabled from the project's start. Since retrofitting them incurs fixing costs, I recommend enabling strict mode from the beginning for new projects.

Tomorrow I'll discuss "Security Measures for Solo Development."

Other Articles in This Series

12/17: Implementing "Search by Meaning": Introduction to pgvector + OpenAI Embeddings
12/19: Security Measures for Solo Development: The Minimum You Should Do

Implementing Semantic Search with pgvector + OpenAI Embeddings

pipipi-dev — Wed, 17 Dec 2025 04:56:33 +0000

This is Day 17 of the and and and and and and and and and and Solo SaaS Development Advent Calendar 2025.

Yesterday I wrote about "Excel-like table UI." Today, I'll explain how to implement semantic search—searching by "meaning" rather than keywords.

What is Semantic Search?

Traditional keyword search finds documents that exactly match (or partially match) the search terms. Searching for "chicken recipe" only returns documents containing that exact string.

Semantic search is different. Searching for "easy dinner ideas" can find documents about "quick recipes" or "meal prep" even though they don't contain those exact keywords—because they're semantically related.

This is made possible by vector search.

What is a Vector?

A vector is simply an "array of numbers."

"quick recipes" → [0.023, -0.041, 0.018, ..., 0.056]

To make this easier to understand, think of a map. Tokyo Station's location can be expressed as two numbers: "latitude 35.68, longitude 139.76." Looking at these numbers, you can tell that Yokohama Station (35.46, 139.62) is "farther" than Shinagawa Station (35.63, 139.74).

Vector search uses the same concept. It converts text into "coordinates in a semantic space." Similar texts become nearby coordinates, so comparing numbers alone can determine if meanings are "close."

This text-to-coordinate conversion is called "embedding." For example, "quick recipes" and "easy-to-make dishes" clearly mean the same thing to humans. With embeddings, these are converted to nearby coordinates, allowing computers to judge them as "semantically similar."

Tech Stack and Setup

Role	Technology
Vector Generation	OpenAI Embeddings API
Vector Storage & Search	PostgreSQL + pgvector
ORM	Drizzle ORM

While there are dedicated vector database services (Pinecone, Weaviate, etc.), I chose pgvector because it can be added to existing PostgreSQL, works with SQL, and is available on Supabase.

Enabling pgvector

On Supabase, enable it from the dashboard, or run this SQL:

CREATE EXTENSION IF NOT EXISTS vector;

Table Design

Create a table to store vectors:

CREATE TABLE search_vectors (
  id TEXT PRIMARY KEY,
  content_id TEXT NOT NULL,        -- Which content this vector belongs to
  text_content TEXT NOT NULL,      -- Original text
  embedding vector(1536) NOT NULL  -- Vector (1536 numbers)
);

vector(1536) is a column that stores vectors, matching the number of values output by OpenAI's model.

Implementation

Generating Vectors

Use OpenAI's Embeddings API to convert text to vectors:

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function generateEmbedding(text: string): Promise<number[]> {
  const response = await openai.embeddings.create({
    model: 'text-embedding-ada-002',
    input: text,
  });

  return response.data[0].embedding;
}

Pass in text and get back an array of numbers. This array represents the "meaning" of the text.

Splitting Long Text

Long texts like blog posts have issues when embedded as-is. The API has character limits, and putting long text into a single vector reduces search accuracy.

So, split long text by "paragraphs" or "fixed character counts" before embedding:

function chunkText(text: string, chunkSize = 500): string[] {
  const chunks: string[] = [];
  for (let i = 0; i < text.length; i += chunkSize) {
    chunks.push(text.substring(i, i + chunkSize));
  }
  return chunks;
}

By splitting, you can search pinpoint results like "the part of this article that discusses X."

Saving Vectors

Save generated vectors to the database. Vectorize and save text when content is registered or updated:

async function saveEmbedding(contentId: string, text: string) {
  const embedding = await generateEmbedding(text);
  const vectorString = `[${embedding.join(',')}]`;

  await db.execute(sql`
    INSERT INTO search_vectors (id, content_id, text_content, embedding)
    VALUES (${crypto.randomUUID()}, ${contentId}, ${text}, ${vectorString}::vector)
  `);
}

When content is updated, delete old vectors before saving new ones:

async function updateEmbeddings(contentId: string, chunks: string[]) {
  // Delete existing vectors
  await db.execute(sql`
    DELETE FROM search_vectors WHERE content_id = ${contentId}
  `);

  // Save new vectors
  for (const chunk of chunks) {
    await saveEmbedding(contentId, chunk);
  }
}

Similarity Search

The search flow is simple: convert the user's search keywords to a vector, compare with vectors stored in the database, and return the most similar ones:

async function searchSimilar(queryText: string, limit = 10) {
  const queryVector = await generateEmbedding(queryText);
  const vectorString = `[${queryVector.join(',')}]`;

  const results = await db.execute(sql`
    SELECT content_id, text_content
    FROM search_vectors
    ORDER BY embedding <=> ${vectorString}::vector
    LIMIT ${limit}
  `);

  return results;
}

<=> is pgvector's "distance comparison operator." With just this, you can find semantically similar documents.

Overall Flow

Preparation (When Registering Content)

Send text to OpenAI API
Save returned vector to DB

At Search Time

Vectorize search query with OpenAI API
Compare with DB vectors, return closest matches

In other words, the "text → vector" conversion is done in advance, and at search time, we just compare vectors. That's why semantic search is fast.

Improving Accuracy

Embed Titles and Body Separately

Rather than making the entire article one vector, embedding "title" and "body paragraphs" separately improves accuracy. Users often search with "title-like keywords," so having title-only vectors makes matching easier even with short search terms.

Combine with Keyword Search

Semantic search isn't perfect. For version numbers like "Next.js 15" or service names like "Supabase," you want to search for the exact string, not the meaning.

"Hybrid search" that uses both traditional keyword search and semantic search is effective:

Semantic search: "how to build auth" → hits login-related articles
Keyword search: "Supabase" → hits articles containing that word

Combining both results reduces missed matches.

Speed Up with Indexes

As data grows, comparing against all vectors every time becomes slow. pgvector can add vector indexes to speed up searches.

When you exceed a few thousand records, measure search speed and add indexes if it's getting slow. Adding them from the start is fine too, but the effect is minimal with little data.

About Costs

Embeddings API costs are very low:

Operation	Cost Estimate
Embed 1000 characters	~$0.00002
Embed 10,000 articles	A few dollars

Unlike the ChatGPT API, the Embeddings API is simple numeric conversion, so costs stay low. It's an accessible price point even for solo developers.

Summary

Key points for implementing semantic search:

Challenge	Solution
Convert text to numbers	OpenAI Embeddings API
Store and search vectors	PostgreSQL + pgvector
Handle long text	Split before embedding
Improve search accuracy	Embed title and body separately
Performance	Add indexes

With semantic search, users can find related documents even without remembering exact keywords. The more information you have, the more valuable this experience becomes.

Tomorrow I'll discuss "Bugs Found with TypeScript Strict Mode."

Other articles in this series

12/16: Building Excel-like Tables with No-Code: Implementing Drag & Drop UI
12/18: Bugs Found with TypeScript Strict Mode: Type Safety in Practice

Building No-Code Excel-like Tables: Implementing Drag & Drop UI

pipipi-dev — Tue, 16 Dec 2025 02:37:44 +0000

This article is Day 16 of the Solo SaaS Development - Design, Implementation, and Operations Advent Calendar 2025.

Yesterday's article covered "Infinite Scroll Pitfalls." Today, I'll explain how to implement an Excel-like table UI with drag & drop column reordering.

🎯 Features to Implement

We're building a table where users can freely manipulate columns, like Notion or Airtable.

Click cells to edit directly (inline editing)
Drag & drop to reorder columns
Reorder rows within the table
Resize column widths

The goal was to make it intuitive enough for non-engineers. This article introduces the design decisions and implementation patterns to achieve these features.

⚙️ Library Selection

Table Foundation: react-spreadsheet

There are several library options for table UI.

Library	Characteristics
AG Grid	Feature-rich, enterprise-scale, commercial license
TanStack Table	Headless, high flexibility, requires UI building
react-spreadsheet	Lightweight, Excel-like, easy customization

I chose react-spreadsheet. The deciding factor was the DataEditor/DataViewer pattern. It allows defining separate components for cell "display" and "editing," making it easy to implement different UIs for each data type.

AG Grid is powerful but implementing custom cell editors was somewhat complex. TanStack Table offers high flexibility as a headless library, but requires building UI from scratch. react-spreadsheet hit the "just right" balance.

Drag & Drop: dnd-kit

For drag & drop, I used @dnd-kit.

react-beautiful-dnd is also well-known, but maintenance has stagnated. dnd-kit supports React 18's Concurrent Mode and has excellent TypeScript definitions. With built-in accessibility (keyboard navigation) support, I chose it with future expansion in mind.

✏️ Inline Editing Design

Why Inline Editing?

The traditional "click edit button to open modal" UI works for editing one item at a time, but becomes frustrating when editing multiple cells consecutively. Being able to "click a cell and edit in place" like Excel greatly improves user efficiency.

DataEditor/DataViewer Pattern

In react-spreadsheet, you assign "display" and "editing" components to each cell.

// Display: State before clicking the cell
const TextViewer: DataViewerComponent<TextCell> = ({ cell }) => {
  return <span className="px-2">{cell?.value ?? ''}</span>;
};

// Editing: State after clicking the cell
const TextEditor: DataEditorComponent<TextCell> = ({ cell, onChange }) => {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    // Auto-focus and select all when entering edit mode
    inputRef.current?.focus();
    inputRef.current?.select();
  }, []);

  return (
    <input
      ref={inputRef}
      type="text"
      value={cell?.value ?? ''}
      onChange={(e) => onChange({ ...cell, value: e.target.value })}
    />
  );
};

The advantage of this pattern is providing optimal UI for each data type. Text gets an input field, dates get a calendar picker, choices get a dropdown—each with an appropriate editor.

Dropdown Considerations

When implementing dropdowns (select boxes), there's a common problem. The menu gets hidden by the table's overflow: hidden.

The solution is to render the menu directly on the body.

<Select
  menuPortalTarget={document.body}
  styles={{ menuPortal: (base) => ({ ...base, zIndex: 9999 }) }}
  // ...
/>

Specifying menuPortalTarget={document.body} moves the menu outside the table's DOM hierarchy, preventing it from being hidden by other elements.

🐧 Column Order Reordering

Reordering in the Design Screen

Column order can be changed in the design screen (field designer). This uses dnd-kit.

The key implementation point is preventing accidental operations.

const sensors = useSensors(
  useSensor(PointerSensor, {
    activationConstraint: { distance: 8 },
  })
);

Specifying distance: 8 means dragging won't start until you move 8 pixels or more. Without this, dragging starts on a simple click, causing unintended reordering.

Another point is limiting the drag handle.

<div ref={setNodeRef} style={style} {...attributes}>
  {/* listeners applied only to handle */}
  <button {...listeners} className="cursor-grab">
    <GripVertical />
  </button>
  <span>{item.name}</span>
  <button onClick={onEdit}>Edit</button>
</div>

By applying listeners only to the drag handle (grip icon), clicking the "Edit" button or other elements won't start dragging. Making the entire item draggable tends to conflict with other operations.

🐰 Table Row Reordering

Optimistic UI Updates

Table rows can also be reordered by dragging. The key here is optimistic UI updates.

const handleDrop = async (targetIndex: number) => {
  // 1. First, update the screen immediately (optimistic update)
  const reordered = [...localRows];
  const [dragged] = reordered.splice(draggedIndex, 1);
  reordered.splice(targetIndex, 0, dragged);
  setLocalRows(reordered);

  // 2. Then save to server
  await saveReorder(reordered);
};

The order changes on screen as soon as the drag completes, while server saving happens in the background. Users can move to the next operation without waiting.

Unsaved State Warning

If users try to leave the page after reordering without saving, we show a warning.

useEffect(() => {
  if (!hasUnsavedChanges) return;

  const handleBeforeUnload = (e: BeforeUnloadEvent) => {
    e.preventDefault();
    e.returnValue = 'Changes have not been saved';
  };

  window.addEventListener('beforeunload', handleBeforeUnload);
  return () => window.removeEventListener('beforeunload', handleBeforeUnload);
}, [hasUnsavedChanges]);

This prevents data loss even if users accidentally close the page.

🐙 Column Width Resizing

Persisting with localStorage

I thought it would be more user-friendly if adjusted column widths persisted on the next visit. While saving to the server is an option, column widths are user preferences that change frequently, so I saved them to localStorage.

const useColumnWidths = (tableId: string) => {
  const storageKey = `table_widths_${tableId}`;

  const [widths, setWidths] = useState<Record<string, number>>(() => {
    const saved = localStorage.getItem(storageKey);
    return saved ? JSON.parse(saved) : {};
  });

  // Update localStorage whenever widths change
  useEffect(() => {
    localStorage.setItem(storageKey, JSON.stringify(widths));
  }, [widths, storageKey]);

  return { widths, setWidths };
};

By saving with different keys per table, settings don't mix up even when using multiple tables.

Minimum Width Constraint

Setting a minimum width during resizing prevents the problem of columns becoming invisible when squished.

const handleResize = (columnId: string, newWidth: number) => {
  const clampedWidth = Math.max(50, newWidth); // Minimum 50px
  setWidths(prev => ({ ...prev, [columnId]: clampedWidth }));
};

✅ Summary

Here are the key points for implementing an Excel-like table UI.

Challenge	Solution
Different editing UI per data type	DataEditor/DataViewer pattern
Dropdown gets hidden	menuPortalTarget={document.body}
Drag triggers on click	activationConstraint: { distance: 8 }
Drag conflicts with other buttons	Limit listeners to drag handle
Wait time during reordering	Optimistic UI updates
Leaving with unsaved changes	beforeunload warning
Column width persistence	localStorage

For no-code tool UI, it's important that it not only "works" but is "usable without confusion." Preventing accidental operations, immediate feedback, state persistence—these details determine the user experience.

Tomorrow's article will cover "Implementing Semantic Search with pgvector + OpenAI Embeddings."

Other Articles in This Series

Day 15: Infinite Scroll with Zustand and React 19: Async Pitfalls
Day 17: Implementing "Search by Meaning": pgvector + OpenAI Embeddings Introduction

Infinite Scroll with Zustand and React 19: Async Pitfalls

pipipi-dev — Mon, 15 Dec 2025 04:01:54 +0000

This article is Day 15 of the Solo SaaS Development - Design, Implementation, and Operations Advent Calendar 2025.

Yesterday's article covered "Mobile-First Design." This article explains the pitfalls I encountered when implementing infinite scroll with Zustand and React 19, along with their solutions.

🎯 What is Infinite Scroll?

Infinite scroll is a mechanism that automatically loads the next content when a user approaches the bottom of the page. It's a familiar UI pattern from X and Instagram.

Compared to traditional pagination (clicking a "Next" button), it offers a more seamless user experience. However, implementation comes with unexpected pitfalls.

For Memoreru, my indie project, I had the following requirements:

Switch between three scopes (public, team, private) plus bookmarks view
Maintain independent pagination state for each view
Display initial data with SSR and load more on the client

It seems simple, but I encountered various issues when actually building it. This article shares that experience.

⚙️ Libraries and Architecture

Delegating Scroll Detection to a Library

For implementing infinite scroll, I used a library called react-infinite-scroll-component. It automates scroll position detection and loading state management.

<InfiniteScroll
  dataLength={items.length}    // Current item count
  next={loadMore}              // Function to load more
  hasMore={hasMore}            // Whether more data exists
  loader={<LoadingSpinner />}  // Loading display
  scrollThreshold={0.6}        // Trigger at 60% scroll
>
  {items.map(item => <ItemCard key={item.id} item={item} />)}
</InfiniteScroll>

You could implement IntersectionObserver yourself, but handling scroll container detection and edge cases is surprisingly tedious. By delegating to a proven library, you can focus on essential feature development.

scrollThreshold specifies "at what percentage of scrolling should we load the next page." Setting it to around 0.6 (60%) starts loading before the user reaches the bottom, making wait times less noticeable.

Managing Multiple Scopes with Zustand

I chose Zustand for state management. Each view (three scopes plus bookmarks) needs to maintain "item list," "current page," "has more data," and "is loading."

interface ContentStore {
  // Items for each scope
  publicItems: ContentItem[];
  privateItems: ContentItem[];
  teamItems: ContentItem[];
  bookmarkItems: ContentItem[];

  // Pagination state (per scope)
  pagination: {
    public: { page: number; hasMore: boolean };
    private: { page: number; hasMore: boolean };
    team: { page: number; hasMore: boolean };
    bookmarks: { page: number; hasMore: boolean };
  };

  // Loading state (per scope)
  loadingState: {
    public: boolean;
    private: boolean;
    team: boolean;
    bookmarks: boolean;
  };
}

I chose Zustand because it's lighter than Redux with less boilerplate, yet more flexible than React Context for splitting state. Since each scope's state is preserved when switching tabs, users don't need to reload when they return.

🚨 Pitfall 1: Same Data Displayed Twice

Root Cause

The first problem I encountered was duplicate items appearing while scrolling.

Investigation revealed that the API response contained items that had already been fetched. This can happen when data is added or deleted during pagination offset calculation.

For example, if a new item is added after fetching page 1, the beginning of page 2 will contain the last item from page 1.

Solution: ID-Based Duplicate Check

As a countermeasure, I implemented ID-based duplicate filtering before adding items.

const loadMoreItems = useCallback(async () => {
  const newItems = await fetchNextPage();

  setItems(prev => {
    // Manage existing IDs with a Set
    const existingIds = new Set(prev.map(item => item.id));
    // Filter out duplicates before adding
    const uniqueNewItems = newItems.filter(item => !existingIds.has(item.id));
    return [...prev, ...uniqueNewItems];
  });
}, []);

The key is using Set. The array's includes method slows down proportionally to the number of elements, but Set's has method searches in nearly constant time. This difference matters when handling hundreds of items in infinite scroll.

🚨 Pitfall 2: Data Order Gets Scrambled

Root Cause

The next issue I encountered was data order getting scrambled when scrolling quickly.

This is a phenomenon called a Race Condition. Network requests don't necessarily complete in the order they were issued.

Page 1 request starts
↓
Page 2 request starts (fast scrolling)
↓
Page 2 response arrives (completes first)
↓
Page 1 response arrives (completes later)

In this case, page 1 data gets appended after page 2 data.

Solution: Track Loading State with Ref

React state (useState) updates asynchronously, so you can't accurately determine "is it currently loading?" Instead, use a Ref that can be referenced synchronously.

const loadingRef = useRef<boolean>(false);

const loadMore = useCallback(async () => {
  // Do nothing if already loading
  if (loadingRef.current) return;
  loadingRef.current = true;

  try {
    const newItems = await fetchNextPage();
    // Process data...
  } finally {
    loadingRef.current = false;
  }
}, []);

You still need useState's loading state for UI display, but the key is using Ref to determine "is it okay to issue a request?" Since Ref updates synchronously, it reliably prevents duplicate requests even with consecutive scroll events.

🚨 Pitfall 3: SSR Data Disappears

Root Cause

I was fetching initial data with Next.js SSR, but the data would sometimes disappear after client-side hydration completed.

Investigation revealed that the client-side API request returned an empty response, overwriting the 10 items fetched via SSR with 0 items.

This can happen when SSR and client make requests with different API conditions (authentication state, filter conditions, etc.).

Solution: Protect SSR Data

Manage a flag for whether SSR data has been loaded, and skip overwriting when "SSR data exists" and "API returns empty response."

const fetchData = useCallback(async () => {
  const items = await fetch(apiUrl).then(res => res.json());

  // Don't overwrite if SSR data exists and API returns empty
  if (store.isSSRDataLoaded && store.items.length > 0 && items.length === 0) {
    console.warn('Blocked overwriting SSR data');
    return;
  }

  updateStore(items);
}, []);

Ideally, SSR and client should call the API with the same conditions, but authentication state synchronization can be tricky. Adding defensive code provides peace of mind.

⚛️ React 19 Considerations

The three issues above can occur with infinite scroll in general, but there are also React 19-specific considerations.

In React 19, state updates are batched more aggressively. This usually contributes to performance improvements, but can cause unexpected issues when coordinating Zustand with React state.

When updating React's local state immediately followed by updating Zustand's store, batching may reorder them. In such cases, use flushSync from react-dom to execute synchronously.

import { flushSync } from 'react-dom';

const updateItems = useCallback((newItems) => {
  let mergedItems;

  flushSync(() => {
    setLocalState(prev => {
      mergedItems = [...prev, ...newItems];
      return mergedItems;
    });
  });

  // At this point, setLocalState has definitely completed
  updateZustandStore(mergedItems);
}, []);

flushSync shouldn't be overused, but it's effective when you need to strictly synchronize multiple state stores.

📊 Performance Optimizations

Suppressing Re-renders with useShallow

When retrieving multiple values from a Zustand store, re-renders occur even for unrelated value changes. Using useShallow triggers re-renders only when specified properties change.

import { useShallow } from 'zustand/react/shallow';

// Bad: pagination recalculates when publicItems changes
const store = useContentStore();

// Good: subscribe only to needed properties
const { items, hasMore } = useContentStore(
  useShallow(state => ({
    items: state.publicItems,
    hasMore: state.pagination.public.hasMore,
  }))
);

Since infinite scroll handles large amounts of items, suppressing unnecessary re-renders is important.

Auto-Load Until Screen is Filled

If no scrollbar appears on initial display, users can't scroll and the next page won't load. This happens with large monitors or when item height is small.

I added a mechanism using ResizeObserver to automatically continue loading until the screen is filled.

useEffect(() => {
  const checkScrollbar = () => {
    const hasScrollbar =
      document.documentElement.scrollHeight > window.innerHeight;

    // Load if no scrollbar and more data exists
    if (!hasScrollbar && hasMore) {
      loadMore();
    }
  };

  const timer = setTimeout(checkScrollbar, 300);
  const observer = new ResizeObserver(checkScrollbar);
  observer.observe(document.body);

  return () => {
    clearTimeout(timer);
    observer.disconnect();
  };
}, [hasMore, loadMore]);

ResizeObserver also detects layout changes like sidebar open/close and triggers additional loading.

🔧 Consolidating into a Custom Hook

I created a usePagination hook that consolidates these processes. The same logic can be reused across different screens.

export function usePagination({ items, scope, loadMoreData, pagination }) {
  const loadedItems = items || [];
  const hasMore = pagination?.hasMore || false;

  const loadMore = useCallback(() => {
    if (!loadMoreData || !hasMore) return;
    loadMoreData(scope);
  }, [loadMoreData, scope, hasMore]);

  // Auto-load to fill screen (useEffect above)
  // ...

  return { loadedItems, hasMore, loadMore };
}

✅ Summary

This article explained the pitfalls and solutions when implementing infinite scroll with Zustand and React 19.

Problem	Cause	Solution
Duplicate data	Pagination offset shift	Filter with Set
Order scrambled	Race condition	Track loading with Ref
SSR data loss	Overwritten by empty response	Protect with flag
React 19 batching	Update order reversal	Synchronize with flushSync

Infinite scroll is more complex than it looks. Especially when multiple data sources and SSR are involved, the edge cases to consider multiply. I hope this article helps those facing similar challenges.

Tomorrow's article will cover "Creating Excel-like Tables with No-Code."

Other Articles in This Series

Day 14: Designing Mobile-First UX: Responsive Design in Practice
Day 16: Creating Excel-like Tables with No-Code: Implementing Drag & Drop UI