Developer Guides & Reference Manuals

Server Actions are asynchronous functions executed on the server that can be invoked directly from Client or Server Components without manual REST endpoint definition.

tsx

'use server';

import { revalidatePath } from 'next/cache';

export async function createNoteAction(formData: FormData) {
  const text = formData.get('text') as string;
  if (!text || text.trim().length === 0) {
    return { error: 'Note text cannot be blank.' };
  }

  // Save to DB or backend service
  await db.note.create({ data: { text } });
  revalidatePath('/notes');
  return { success: true };
}

2. Optimistic UI with useOptimistic

Provide instant UI feedback to the user before the server request completes using React’s useOptimistic Hook.

tsx

'use client';

import { useOptimistic } from 'react';

export function NoteList({ initialNotes, createAction }) {
  const [optimisticNotes, addOptimisticNote] = useOptimistic(
    initialNotes,
    (state, newNote) => [newNote, ...state]
  );

  async function formAction(formData: FormData) {
    const text = formData.get('text');
    addOptimisticNote({ id: 'temp', text, isPending: true });
    await createAction(formData);
  }

  return <form action={formAction}>{/* render list */}</form>;
}

Storage & DB8 min read

Architecting Local-First Web Applications with IndexedDB

How to build privacy-first, zero-latency applications with IndexedDB object stores, version upgrades, and transactional safety.

1. Why Local-First Matters

Local-first architecture eliminates cloud latency and protects user privacy by storing application state entirely on the client machine.

typescript

// Safe IndexedDB Open with Schema Upgrades
export function openDatabase(): Promise<IDBDatabase> {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open('techtube_db', 2);
    req.onupgradeneeded = (e) => {
      const db = (e.target as IDBOpenDBRequest).result;
      if (!db.objectStoreNames.contains('notes')) {
        db.createObjectStore('notes', { keyPath: 'id' });
      }
    };
    req.onsuccess = () => resolve(req.result);
    req.onerror = () => reject(req.error);
  });
}

TypeScript5 min read

TypeScript Branded Types for Zero-Cost Type Safety

Prevent accidental primitive parameter swapping (e.g. passing a CustomerID where a UserID is expected) using branded nominal types.

1. The Problem with Structural Typing

In TypeScript, type UserId = string and type OrderId = string are completely interchangeable, leading to subtle runtime bugs.

typescript

// Define Brand Helper
declare const __brand: unique symbol;
type Brand<T, B> = T & { readonly [__brand]: B };

export type UserId = Brand<string, 'UserId'>;
export type OrderId = Brand<string, 'OrderId'>;

export function makeUserId(raw: string): UserId {
  return raw as UserId;
}

export function fetchOrder(orderId: OrderId) {
  // TypeScript enforces that ONLY OrderId can be passed!
}

'use server'; import { revalidatePath } from 'next/cache'; export async function createNoteAction(formData: FormData) { const text = formData.get('text') as string; if (!text || text.trim().length === 0) { return { error: 'Note text cannot be blank.' }; } // Save to DB or backend service await db.note.create({ data: { text } }); revalidatePath('/notes'); return { success: true }; }

'use client'; import { useOptimistic } from 'react'; export function NoteList({ initialNotes, createAction }) { const [optimisticNotes, addOptimisticNote] = useOptimistic( initialNotes, (state, newNote) => [newNote, ...state] ); async function formAction(formData: FormData) { const text = formData.get('text'); addOptimisticNote({ id: 'temp', text, isPending: true }); await createAction(formData); } return <form action={formAction}>{/* render list */}</form>; }

// Safe IndexedDB Open with Schema Upgrades export function openDatabase(): Promise<IDBDatabase> { return new Promise((resolve, reject) => { const req = indexedDB.open('techtube_db', 2); req.onupgradeneeded = (e) => { const db = (e.target as IDBOpenDBRequest).result; if (!db.objectStoreNames.contains('notes')) { db.createObjectStore('notes', { keyPath: 'id' }); } }; req.onsuccess = () => resolve(req.result); req.onerror = () => reject(req.error); }); }

// Define Brand Helper declare const __brand: unique symbol; type Brand<T, B> = T & { readonly [__brand]: B }; export type UserId = Brand<string, 'UserId'>; export type OrderId = Brand<string, 'OrderId'>; export function makeUserId(raw: string): UserId { return raw as UserId; } export function fetchOrder(orderId: OrderId) { // TypeScript enforces that ONLY OrderId can be passed! }