DEV Community: Carlos Oliva Pascual

React 19 useTransition & useDeferredValue: When to Use Which (2026)

Carlos Oliva Pascual — Wed, 24 Jun 2026 13:38:49 +0000

Both useTransition and useDeferredValue exist because React 19 cares about which renders are urgent and which can wait. But they operate at different points in the update cycle.

Here's the clearest way to think about it:

useTransition — you control when the state update happens. You wrap the setter.
useDeferredValue — you control when the new value propagates. You wrap the value.

Same goal, different leverage point.

What "Transition" Actually Means

React's concurrent mode introduced the concept of priority. Not every update needs to happen at the same urgency. Typing a keystroke should respond immediately. Rendering 500 filtered items can wait.

A "transition" marks an update as low-priority — one that can be deferred if something urgent arrives.

useTransition: Wrap the Setter

import { useState, useTransition } from 'react'

function FilteredList({ items }: { items: string[] }) {
  const [query, setQuery] = useState('')
  const [filteredItems, setFilteredItems] = useState(items)
  const [isPending, startTransition] = useTransition()

  function handleSearch(e: React.ChangeEvent<HTMLInputElement>) {
    const value = e.target.value
    setQuery(value) // urgent — input updates immediately

    startTransition(() => {
      // non-urgent — filtering can be deferred
      setFilteredItems(items.filter((item) =>
        item.toLowerCase().includes(value.toLowerCase())
      ))
    })
  }

  return (
    <div>
      <input value={query} onChange={handleSearch} placeholder="Filter..." />
      {isPending && <span className="text-sm text-muted-foreground">Updating...</span>}
      <ul className={isPending ? 'opacity-50' : ''}>
        {filteredItems.map((item) => <li key={item}>{item}</li>)}
      </ul>
    </div>
  )
}

isPending is true while React is computing the transition. Use it to show a spinner or dim stale content.

useTransition with Server Actions

In React 19, startTransition accepts async callbacks — making it the right way to track Server Action state:

'use client'

import { useTransition } from 'react'
import { updateProfile } from './actions'

export function ProfileForm({ user }: { user: { name: string; bio: string } }) {
  const [isPending, startTransition] = useTransition()

  function handleSubmit(formData: FormData) {
    startTransition(async () => {
      await updateProfile(formData) // Server Action
    })
  }

  return (
    <form action={handleSubmit}>
      <input name="name" defaultValue={user.name} />
      <textarea name="bio" defaultValue={user.bio} />
      <button type="submit" disabled={isPending}>
        {isPending ? 'Saving...' : 'Save changes'}
      </button>
    </form>
  )
}

No manual useState boolean for loading state — isPending handles it.

Navigation Loading State

'use client'

import { useRouter } from 'next/navigation'
import { useTransition } from 'react'

export function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
  const router = useRouter()
  const [isPending, startTransition] = useTransition()

  return (
    <button
      onClick={() => startTransition(() => router.push(href))}
      className="relative"
    >
      {children}
      {isPending && <span className="absolute inset-x-0 -bottom-0.5 h-0.5 bg-primary animate-pulse" />}
    </button>
  )
}

useDeferredValue: Wrap the Value

Use this when you receive a value from outside and passing it to an expensive component causes slowdown.

import { useState, useDeferredValue, memo } from 'react'

// CRITICAL: memo() is required for useDeferredValue to help
const MemoizedSearchResults = memo(SearchResults)

export function SearchPage() {
  const [query, setQuery] = useState('')
  const deferredQuery = useDeferredValue(query)
  const isStale = query !== deferredQuery

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      <div className={isStale ? 'opacity-60' : ''}>
        <MemoizedSearchResults query={deferredQuery} />
      </div>
    </div>
  )
}

The input always shows the latest value. The expensive search results catch up when React has a free frame.

memo() is required. Without it, the component re-renders on every keystroke regardless of the deferred value — useDeferredValue does nothing.

How it works frame by frame

When the user types "react" fast:

Keystroke "r":  query = "r",      deferredQuery = ""     → shows "" results
Keystroke "e":  query = "re",     deferredQuery = "r"    → shows "r" results
...pause...
After pause:    query = "react",  deferredQuery = "react" → shows "react" results

The input is always instant. Results catch up.

useOptimistic: The Third Member

React 19's useOptimistic pairs with useTransition for instant optimistic UI:

'use client'

import { useOptimistic, useTransition } from 'react'
import { toggleLike } from './actions'

export function LikeButton({ postId, initialLikes, initialLiked }) {
  const [isPending, startTransition] = useTransition()
  const [optimistic, addOptimistic] = useOptimistic(
    { likes: initialLikes, liked: initialLiked },
    (state, liked: boolean) => ({
      likes: liked ? state.likes + 1 : state.likes - 1,
      liked,
    })
  )

  function handleClick() {
    const newLiked = !optimistic.liked
    startTransition(async () => {
      addOptimistic(newLiked) // instant UI update
      await toggleLike(postId, newLiked) // server mutation
    })
  }

  return (
    <button onClick={handleClick} disabled={isPending}>
      {optimistic.liked ? '❤️' : '🤍'} {optimistic.likes}
    </button>
  )
}

If the server call fails, React rolls back automatically.

The Actual Difference

// useTransition: wrap the setter
const [isPending, startTransition] = useTransition()
startTransition(() => setState(newValue))

// useDeferredValue: wrap the value
const deferredValue = useDeferredValue(value)
<ExpensiveComponent data={deferredValue} />

	`useTransition`	`useDeferredValue`
What you wrap	The state setter	The value itself
isPending	Yes	No (compute manually)
Requires memo()	No	Yes
Best for	Server Actions, navigation	Search, prop-driven renders

Common Mistakes

1. Using useTransition for animations — it's about rendering priority, not CSS animations.

2. Forgetting memo() with useDeferredValue — without it, nothing is deferred.

3. Marking urgent updates as transitions:

// Wrong — input updates should always be urgent
startTransition(() => setInputValue(e.target.value))

// Right
setInputValue(e.target.value)                         // urgent
startTransition(() => setFilteredResults(filter(...))) // non-urgent

Full article at stacknotice.com/blog/react-19-transitions-guide-2026

Next.js Partial Prerendering (PPR) Guide (2026)

Carlos Oliva Pascual — Tue, 23 Jun 2026 12:09:44 +0000

For years the rendering decision in Next.js was binary: either pre-render the page at build time (SSG) or render it fresh on every request (SSR). The problem is that most real pages don't fit cleanly into either bucket.

A product page has a static title and description (same for everyone), a live stock count (changes every few minutes), and a personalized recommendations section (different per user). With classic Next.js you pick one strategy for the whole page and compromise everywhere else.

Partial Prerendering fixes this. It renders the static parts at build time and fills in the dynamic parts at request time — on the same page, without workarounds.

How PPR Works

PPR uses <Suspense> boundaries to declare which parts of a page are dynamic. Everything outside a Suspense boundary is the static shell — pre-rendered at build time and cached at the edge. Everything inside a Suspense boundary that reads request-time data is a dynamic hole — rendered fresh at request time and streamed to the client.

Build time  ┌───────────────────────────────┐
            │  Header (static)              │ ← edge-cached HTML
            │  Product name + description   │ ← edge-cached HTML
            │  ┌─────────────────────────┐  │
            │  │  <Suspense>             │  │ ← rendered fresh per request
            │  │  Stock count · Price    │  │
            │  └─────────────────────────┘  │
            └───────────────────────────────┘

Users get the static shell from the CDN instantly. Dynamic content streams in right behind it.

Enabling PPR

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    ppr: 'incremental', // opt-in per route
  },
}

export default nextConfig

Then opt in on each route:

// app/products/[id]/page.tsx
export const experimental_ppr = true

export default function ProductPage({ params }: { params: { id: string } }) {
  // ...
}

Building a PPR Page

// app/products/[id]/page.tsx
import { Suspense } from 'react'
import { ProductDetails } from './product-details'
import { StockBadge } from './stock-badge'
import { PersonalizedSection } from './personalized-section'

export const experimental_ppr = true

export default function ProductPage({ params }: { params: { id: string } }) {
  return (
    <main className="container mx-auto py-8">
      {/* Static — pre-rendered at build time */}
      <ProductDetails productId={params.id} />

      {/* Dynamic — stock changes constantly */}
      <Suspense fallback={<div className="h-8 w-32 animate-pulse bg-muted rounded" />}>
        <StockBadge productId={params.id} />
      </Suspense>

      {/* Dynamic — personalized per user */}
      <Suspense fallback={<PersonalizedSkeleton />}>
        <PersonalizedSection productId={params.id} />
      </Suspense>
    </main>
  )
}

The static component

// product-details.tsx — runs at BUILD TIME
import { db } from '@/lib/db'
import { notFound } from 'next/navigation'

export async function ProductDetails({ productId }: { productId: string }) {
  const product = await db.query.products.findFirst({
    where: (p, { eq }) => eq(p.id, productId),
  })

  if (!product) notFound()

  return (
    <div className="space-y-4">
      <h1 className="text-3xl font-bold">{product.name}</h1>
      <p className="text-muted-foreground">{product.description}</p>
      <p className="text-2xl font-semibold">${product.price.toFixed(2)}</p>
    </div>
  )
}

The dynamic components

// stock-badge.tsx — runs at REQUEST TIME
import { unstable_noStore as noStore } from 'next/cache'
import { getInventoryLevel } from '@/lib/inventory'

export async function StockBadge({ productId }: { productId: string }) {
  noStore() // force fresh rendering every request

  const stock = await getInventoryLevel(productId)

  if (stock === 0) return <span className="text-destructive font-medium">Out of stock</span>
  if (stock <= 5) return <span className="text-amber-600 font-medium">Only {stock} left</span>
  return <span className="text-emerald-600 font-medium">In stock</span>
}

// personalized-section.tsx — dynamic because of cookies()
import { cookies } from 'next/headers'
import { getRecommendations } from '@/lib/recommendations'

export async function PersonalizedSection({ productId }: { productId: string }) {
  const cookieStore = cookies() // makes this component dynamic automatically
  const userId = cookieStore.get('user_id')?.value

  const recs = await getRecommendations({ productId, userId })

  return (
    <section className="mt-12">
      <h2 className="text-xl font-semibold mb-4">
        {userId ? 'Recommended for you' : 'You might also like'}
      </h2>
      <div className="grid grid-cols-4 gap-4">
        {recs.map((p) => <ProductCard key={p.id} product={p} />)}
      </div>
    </section>
  )
}

Calling cookies() automatically makes the component dynamic — no need for noStore() when you're already reading request-time data.

Deduplicate Requests with `cache()`

When multiple components need the same data, use React's cache():

// lib/queries/product.ts
import { cache } from 'react'
import { db } from '@/lib/db'

export const getProduct = cache(async (id: string) => {
  return db.query.products.findFirst({
    where: (p, { eq }) => eq(p.id, id),
  })
})

Both static and dynamic components can call getProduct(id) — only one database query runs per render cycle.

Suspense Fallbacks That Don't Shift Layout

Design fallbacks that match the real content's dimensions:

function PersonalizedSkeleton() {
  return (
    <div className="grid grid-cols-4 gap-4 mt-12">
      {Array.from({ length: 4 }).map((_, i) => (
        <div key={i} className="space-y-2">
          <div className="aspect-square rounded-lg animate-pulse bg-muted" />
          <div className="h-4 w-3/4 rounded animate-pulse bg-muted" />
          <div className="h-4 w-1/2 rounded animate-pulse bg-muted" />
        </div>
      ))}
    </div>
  )
}

Nested Suspense Boundaries

Control the order of streaming with nesting:

export default function CheckoutPage() {
  return (
    <main>
      <CheckoutForm /> {/* static */}

      <Suspense fallback={<OrderSummarySkeleton />}>
        <OrderSummary />

        {/* resolves after OrderSummary — needs order data + location */}
        <Suspense fallback={<ShippingEstimateSkeleton />}>
          <ShippingEstimate />
        </Suspense>
      </Suspense>

      {/* resolves independently */}
      <Suspense fallback={<PaymentSkeleton />}>
        <PaymentSection />
      </Suspense>
    </main>
  )
}

OrderSummary streams in when cart data resolves. ShippingEstimate and PaymentSection resolve independently — none of them block each other.

PPR vs Other Strategies

	SSG	ISR	SSR	PPR
Build time work	Full page	Full page	None	Static shell
Request time work	None	None	Full page	Dynamic holes
Fresh dynamic data	No	After revalidation	Yes	Yes
Personalization	No	No	Yes	Yes
Edge cache	Full page	Full page	Varies	Shell only

Isolating `searchParams`

Reading searchParams forces the entire page dynamic. Isolate them to preserve a static shell:

// app/products/page.tsx
export const experimental_ppr = true

export default function ProductsPage({
  searchParams,
}: {
  searchParams: { q?: string; category?: string }
}) {
  return (
    <main>
      {/* Static — no searchParams dependency */}
      <FeaturedBanner />

      {/* Dynamic — only this component reads searchParams */}
      <Suspense fallback={<ProductGridSkeleton />}>
        <ProductGrid searchParams={searchParams} />
      </Suspense>
    </main>
  )
}

What Makes a Component Dynamic (Checklist)

If a component you expect to be static is rendering dynamically, check for:

❌ Calling cookies() or headers() anywhere in its tree
❌ Reading searchParams directly on the page
❌ Calling unstable_noStore() explicitly
❌ Using Date.now() or Math.random() in the render path
❌ A third-party component that internally calls any of the above

Run npm run build and check the output — routes with PPR show as ◐ (PPR) with the static shell size listed.

When to Use PPR

PPR makes the most sense when your page has a meaningful static shell worth caching:

✅ Product pages — static description + dynamic stock/price/recommendations
✅ Blog posts — static content + dynamic comment count or reactions
✅ Dashboards — static navigation and layout + dynamic data widgets
✅ Landing pages — static hero/content + dynamic logged-in state

Skip PPR when everything is user-specific (use SSR) or nothing changes (use SSG).

Full article with more patterns at stacknotice.com/blog/nextjs-partial-prerendering-2026

Git Worktrees + Claude Code: Run Parallel AI Agents on the Same Repo (2026)

Carlos Oliva Pascual — Tue, 23 Jun 2026 10:48:49 +0000

The standard Claude Code workflow is one session, one branch, one task at a time. That works fine for a focused bug fix. But when you have a feature to build, a module to refactor, and tests to write — all of which Claude Code could handle — you're leaving a lot of speed on the table by doing them serially.

Git worktrees change that. They let you check out multiple branches from the same repository into separate directories. Each directory is independent. Each can run its own Claude Code session. Multiple AI agents working in parallel, zero interference.

What Git Worktrees Actually Are

A git worktree is a linked working directory attached to the same repository. You get a separate folder with its own branch, its own staging area, and its own HEAD — but sharing the same .git history and object store.

# Normal repo: one branch at a time
my-app/
  .git/
  src/
  # active branch: main

# With worktrees: multiple branches simultaneously
my-app/          # main branch
my-app-dash/     # feature/dashboard
my-app-refactor/ # refactor/auth-module

Each extra directory is a full checkout. You can git status, git add, git commit in any of them independently. Changes in one don't touch the others.

Why This Pairs Well with Claude Code

Claude Code operates inside a directory — it reads files there, edits them, runs shell commands in that context. If two tasks touch different parts of your codebase, running them in the same directory creates friction:

Context bleed: Claude sees half-done work from task A while doing task B
File conflicts: both tasks might edit a shared file for unrelated reasons
Serial bottleneck: you wait for task one before starting task two

With worktrees, each Claude Code session gets a clean working copy on its own branch. They run in true parallel, completely isolated.

Setting Up Worktrees

# Inside your main repo
cd my-app

# Create a worktree for a new feature (creates the branch too)
git worktree add ../my-app-dashboard -b feature/dashboard

# Create one for a refactor
git worktree add ../my-app-auth -b refactor/auth-cleanup

Now you have three separate directories, each on its own branch, all pointing at the same git repository.

Starting Claude Code in each

# Terminal 1
cd ../my-app-dashboard
claude

# Terminal 2
cd ../my-app-auth
claude

Two Claude Code sessions running in parallel, on different branches, no overlap.

A Real Parallel Workflow

Say today's backlog has three independent tasks:

Build a /dashboard page with charts and a stats row
Refactor the auth module from better-auth v1 to v2
Add missing Vitest coverage for src/lib/payments.ts

None of them share files. All three can run simultaneously.

# Create the worktrees
git worktree add ../my-app-dashboard -b feature/dashboard
git worktree add ../my-app-auth      -b refactor/auth-v2
git worktree add ../my-app-tests     -b tests/payments-coverage

# Install dependencies in each
for dir in ../my-app-dashboard ../my-app-auth ../my-app-tests; do
  (cd "$dir" && npm install --silent) &
done
wait

Then kick off all three with focused prompts:

# Terminal 1 — cd ../my-app-dashboard, then claude:
"Build a /dashboard page with a revenue chart using Recharts, a recent orders
table using shadcn DataTable, and a stats summary row. Use the existing layout.tsx."

# Terminal 2 — cd ../my-app-auth, then claude:
"Read src/lib/auth.ts first, then migrate it to better-auth v2.
session.create() replaces createSession(). user.findById() replaces getUserById().
Keep the same exports."

# Terminal 3 — cd ../my-app-tests, then claude:
"Write Vitest unit tests for src/lib/payments.ts.
Cover createSubscription, cancelSubscription, applyPromoCode.
Mock the Stripe client at the module level."

Per-Task CLAUDE.md

Your project's CLAUDE.md is shared across all worktrees since they point to the same repo. But you can add a task-specific CLAUDE.md at the worktree root for focused context:

# CLAUDE.md — refactor/auth-v2 worktree

## Current goal
Migrate src/lib/auth.ts from better-auth v1 to v2.

## Do not touch
- src/lib/auth-adapters/ — already migrated
- src/middleware.ts — separate PR

## better-auth v2 breaking changes
- `createSession()` → `session.create()`
- `getUserById()` → `user.findById()`
- All methods return `{ data, error }` now

Worktrees vs Subagents

Claude Code subagents also run tasks in parallel. The difference matters:

	Worktrees + parallel sessions	Subagents
Isolation	Separate directories + branches	Same working directory
File conflicts	Impossible	Possible
Context	Each session is independent	Shared parent context
Best for	Long independent tasks (hours)	Short parallel lookups (minutes)

Use worktrees when tasks are genuinely independent and involve many file changes. Use subagents when tasks are quick and need to share results within one session.

Headless Batch Execution

Combine worktrees with Claude Code's -p flag for fully automated parallel execution:

#!/bin/bash
declare -A TASKS
TASKS["dashboard"]="feature/dashboard|Build the /dashboard page with revenue charts and a stats summary row"
TASKS["auth"]="refactor/auth-v2|Migrate src/lib/auth.ts to better-auth v2. Read the file first."
TASKS["tests"]="tests/payments|Write Vitest tests for src/lib/payments.ts"

mkdir -p logs

for name in "${!TASKS[@]}"; do
  IFS='|' read -r branch prompt <<< "${TASKS[$name]}"

  git worktree add "../$(basename "$PWD")-$name" -b "$branch" 2>/dev/null || true

  (
    cd "../$(basename "$PWD")-$name"
    npm install --silent
    claude -p "$prompt" --output-format text > "../logs/$name.log" 2>&1
    echo "done: $name"
  ) &
done

wait
echo "All tasks finished. Logs in ./logs/"

Managing Worktrees

# See all worktrees
git worktree list

# Remove after merging
git worktree remove ../my-app-dashboard

# Prune if manually deleted
git worktree prune

Common Issues

"fatal: 'feature/dashboard' is already checked out"
A branch can only be active in one worktree. Use a new branch name:

git worktree add ../my-app-dashboard -b feature/dashboard-v2

.env not found
Worktrees don't copy .env files. Symlink it:

ln -s "$(pwd)/.env" ../my-app-dashboard/.env

node_modules not found
Worktrees share the git index but not node_modules. Run npm install in each new worktree.

Shell Alias

function cw() {
  local name=$1
  local branch=${2:-feature/$1}
  local dir="../$(basename "$PWD")-$name"

  git worktree add "$dir" -b "$branch"
  cd "$dir"
  npm install --silent
  claude
}

# Usage
cw dashboard feature/dashboard

The setup takes about two minutes. Any Claude Code task that runs longer than two minutes — which is most real tasks — pays off immediately.

Full article with more patterns at stacknotice.com/blog/claude-code-worktrees-2026

Next.js 15 SEO: metadata, OG Images, Sitemap, and Structured Data (2026)

Carlos Oliva Pascual — Mon, 22 Jun 2026 15:07:32 +0000

Next.js 15 App Router handles SEO in TypeScript, co-located with your routes. This guide covers every layer — metadata, OG images, sitemaps, structured data — with real production patterns.

Two Ways to Define Metadata

Static export — when metadata doesn't depend on fetched data:

// app/about/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'About Us',
  description: 'Learn about our team and mission.',
  openGraph: { title: 'About Us', description: 'Learn about our team.', type: 'website' },
}

generateMetadata — when metadata depends on route params or DB data:

// app/blog/[slug]/page.tsx
import type { Metadata, ResolvingMetadata } from 'next'
import { getPost } from '@/lib/posts'

interface Props { params: Promise<{ slug: string }> }

export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { slug } = await params
  const post = await getPost(slug)
  if (!post) return { title: 'Post not found' }

  const parentImages = (await parent).openGraph?.images ?? []

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      type: 'article',
      publishedTime: post.publishedAt.toISOString(),
      authors: [post.author.name],
      images: [
        { url: post.coverImage, width: 1200, height: 630, alt: post.title },
        ...parentImages,
      ],
    },
    twitter: {
      card: 'summary_large_image',
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  }
}

Title Templates

Configure once in the root layout — child pages only set their own title:

// app/layout.tsx
export const metadata: Metadata = {
  title: {
    template: '%s — Acme',     // "Pricing — Acme"
    default: 'Acme — Build faster',
  },
}

// app/pricing/page.tsx
export const metadata: Metadata = {
  title: 'Pricing',  // renders as "Pricing — Acme"
}

Dynamic Open Graph Images

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { getPost } from '@/lib/posts'

export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'

export default async function OgImage({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug)

  return new ImageResponse(
    (
      <div
        style={{
          background: 'linear-gradient(135deg, #080B14, #0D1117)',
          width: '100%',
          height: '100%',
          display: 'flex',
          flexDirection: 'column',
          justifyContent: 'flex-end',
          padding: '64px',
          fontFamily: 'sans-serif',
        }}
      >
        <div style={{ fontSize: '18px', color: '#38BDF8', letterSpacing: '3px', marginBottom: '20px' }}>
          YOUR SITE
        </div>
        <div style={{ fontSize: '56px', fontWeight: 900, color: 'white', lineHeight: 1.15 }}>
          {post?.title ?? 'Blog Post'}
        </div>
      </div>
    ),
    { ...size }
  )
}

The URL (/blog/my-post/opengraph-image) is automatically referenced in the page metadata. Next.js caches the output.

sitemap.xml

// app/sitemap.ts
import type { MetadataRoute } from 'next'
import { getAllPosts } from '@/lib/posts'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const posts = await getAllPosts()
  const baseUrl = 'https://example.com'

  return [
    { url: baseUrl, lastModified: new Date(), changeFrequency: 'daily', priority: 1.0 },
    { url: `${baseUrl}/blog`, lastModified: new Date(), changeFrequency: 'daily', priority: 0.9 },
    ...posts.map((post) => ({
      url: `${baseUrl}/blog/${post.slug}`,
      lastModified: post.updatedAt,
      changeFrequency: 'weekly' as const,
      priority: 0.8,
    })),
  ]
}

Available at /sitemap.xml.

robots.txt

// app/robots.ts
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return {
    rules: [{ userAgent: '*', allow: '/', disallow: ['/api/', '/admin/'] }],
    sitemap: 'https://example.com/sitemap.xml',
  }
}

JSON-LD Structured Data

Add as a <script> tag in the page component — not through the metadata API:

// app/blog/[slug]/page.tsx
export default async function BlogPost({ params }: Props) {
  const { slug } = await params
  const post = await getPost(slug)
  if (!post) return null

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: post.title,
    description: post.excerpt,
    image: post.coverImage,
    author: { '@type': 'Person', name: post.author.name },
    publisher: {
      '@type': 'Organization',
      name: 'Acme',
      logo: { '@type': 'ImageObject', url: 'https://example.com/logo.png' },
    },
    datePublished: post.publishedAt.toISOString(),
    dateModified: post.updatedAt.toISOString(),
  }

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      <article>{/* content */}</article>
    </>
  )
}

Canonical URLs

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  return {
    alternates: {
      canonical: `https://example.com/blog/${slug}`,
    },
  }
}

For paginated routes:

return {
  alternates: {
    canonical: page === '1'
      ? 'https://example.com/blog'
      : `https://example.com/blog/page/${page}`,
  },
}

Deduplicating Data Fetches

generateMetadata and the page component run independently. Use cache() to prevent double DB calls:

// lib/posts.ts
import { cache } from 'react'

export const getPost = cache(async (slug: string) => {
  return db.post.findUnique({ where: { slug } })
})

Same call in generateMetadata and page.tsx = one query, two uses.

Common Pitfalls

Missing descriptions — meta description is your ad copy in search results. Don't leave it empty.
Generic OG images — per-page dynamic images improve social CTR noticeably.
Duplicate titles — every page needs a unique title; the template handles the suffix, you handle the unique part.
Unvalidated JSON-LD — invalid structured data is silently ignored. Test with Google's Rich Results Test.
Not checking what social platforms see — use Twitter Card Validator and Facebook Sharing Debugger.

Quick Verification

# Check metadata in rendered HTML
curl -s https://your-site.com/blog/your-post | grep -E 'og:|twitter:|canonical'

# Validate sitemap
curl -s https://your-site.com/sitemap.xml | head -30

Full guide at stacknotice.com/blog/nextjs-seo-guide-2026

Claude Code in Scripts: Headless Mode and Automation (2026)

Carlos Oliva Pascual — Mon, 22 Jun 2026 07:29:12 +0000

Most people use Claude Code as an interactive REPL. But there's a second mode — headless, non-interactive — that turns it into a scriptable tool you can wire into bash pipelines, git hooks, cron jobs, and CI.

The same model. None of the conversation. Just input and output.

The -p Flag

-p (or --print) runs Claude in print mode. Prompt goes in, result comes to stdout, Claude exits.

# One-shot
claude -p "Generate a TypeScript interface for a blog post"

# Pipe a file
cat src/lib/auth.ts | claude -p "Review this for security issues. Be specific."

# Multiple files
cat src/lib/actions/user.ts src/types/user.ts | claude -p "Are these types consistent?"

Output Formats

# Plain text (no markdown)
claude -p "List 3 improvements" --output-format text < src/lib/payments.ts

# JSON — pipe into jq
claude -p 'Analyze and return JSON: { "issues": [{"severity","description","line"}] }' \
  --output-format json < src/lib/auth.ts \
  | jq '.issues[] | select(.severity == "high")'

Real Script: Auto-Changelog

#!/bin/bash
# scripts/generate-changelog.sh

SINCE=${1:-"1 week ago"}
COMMITS=$(git log --oneline --since="$SINCE")

[ -z "$COMMITS" ] && echo "No commits since $SINCE" && exit 0

CHANGELOG=$(claude -p "$(cat <<EOF
Generate a changelog entry in markdown for these git commits.
Group by: Features, Bug Fixes, Improvements, Other.
Use bullet points. Be concise and developer-friendly.

Commits:
$COMMITS
EOF
)" --output-format text)

echo "## $(date +%Y-%m-%d)" > /tmp/entry.md
echo "" >> /tmp/entry.md
echo "$CHANGELOG" >> /tmp/entry.md
echo "" >> /tmp/entry.md
cat /tmp/entry.md CHANGELOG.md > /tmp/full.md
mv /tmp/full.md CHANGELOG.md

echo "Changelog updated."

./scripts/generate-changelog.sh              # since 1 week ago
./scripts/generate-changelog.sh "1 day ago"

Real Script: Commit Message Generator

#!/bin/bash
# Usage: git diff --staged | ./scripts/commit-msg-gen.sh

DIFF=$(cat)
[ -z "$DIFF" ] && echo "No staged changes." && exit 1

claude -p "$(cat <<EOF
Generate a conventional commit message for this diff.
Format: <type>(<scope>): <description>
Types: feat, fix, refactor, docs, test, chore, perf
Keep under 72 characters. Output the message only.

Diff:
$DIFF
EOF
)" --output-format text

# Preview
git diff --staged | ./scripts/commit-msg-gen.sh

# Use directly
git commit -m "$(git diff --staged | ./scripts/commit-msg-gen.sh)"

Real Script: Batch PR Review

#!/bin/bash
# scripts/pr-review.sh

BASE=${1:-"main"}
FILES=$(git diff --name-only "$BASE"...HEAD)

echo "# PR Review Report — $(date)" > pr-review.md

for file in $FILES; do
  case "$file" in *.md|*.json|*.lock|*.svg) continue ;; esac
  [ ! -f "$file" ] && continue

  echo "Reviewing $file..."

  REVIEW=$(cat "$file" | claude -p "$(cat <<EOF
Review for: bugs, security issues, missing error handling, performance.
Be specific with line numbers. Say "Looks good." if nothing to flag.
File: $file
EOF
)" --output-format text)

  echo "## $file" >> pr-review.md
  echo "$REVIEW" >> pr-review.md
  echo "" >> pr-review.md
done

echo "Done → pr-review.md"

Git Hook: Auto-suggest Commit Messages

# .git/hooks/prepare-commit-msg
#!/bin/bash

COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

if [ "$COMMIT_SOURCE" = "" ]; then
  STAGED=$(git diff --staged)
  if [ -n "$STAGED" ]; then
    SUGGESTION=$(echo "$STAGED" | claude -p \
      "Write a conventional commit message. One line, under 72 chars." \
      --output-format text 2>/dev/null)
    if [ -n "$SUGGESTION" ]; then
      echo "# Suggested: $SUGGESTION" > /tmp/msg
      cat "$COMMIT_MSG_FILE" >> /tmp/msg
      mv /tmp/msg "$COMMIT_MSG_FILE"
    fi
  fi
fi

chmod +x .git/hooks/prepare-commit-msg

In CI/CD

# .github/workflows/claude-review.yml
- name: Review changed files
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    FILES=$(git diff --name-only origin/main...HEAD)
    for file in $FILES; do
      case "$file" in
        *.ts|*.tsx|*.js|*.jsx)
          cat "$file" | claude -p "Flag security issues or bugs. Be specific." \
            --output-format text \
            --dangerously-skip-permissions \
            >> review.txt
          ;;
      esac
    done
    cat review.txt

Error Handling

RESULT=$(cat src/main.ts | claude -p "Analyze" --output-format text)
[ $? -ne 0 ] && echo "Claude failed" >&2 && exit 1
echo "$RESULT"

When to Use Headless vs Interactive

Use -p for: well-defined tasks, batch file processing, CI pipelines, automation with known input/output.

Use interactive for: exploratory work, refactoring sessions that need back-and-forth, anything where you'd naturally say "yes, do that" or "try this instead."

Don't force complex context-heavy tasks into a single -p call. The interactive session can read files, adjust course, and ask clarifying questions in ways one-shot prompts can't.

Full guide at stacknotice.com/blog/claude-code-headless-scripting-2026

TypeScript Utility Types: The Complete Guide (2026)

Carlos Oliva Pascual — Fri, 19 Jun 2026 12:37:27 +0000

TypeScript ships with a set of generic utility types that transform existing types into new ones. They eliminate repetitive type definitions and make your types more precise without writing more code.

Most developers know Partial and Pick. Most are missing Awaited, Extract, and the composed patterns that make utility types genuinely powerful.

Why Utility Types Exist

Without utility types, you copy and modify types by hand:

// Manual — goes out of sync when User changes:
interface UserUpdateInput {
  email?: string
  name?: string
  role?: 'admin' | 'member' | 'viewer'
}

// Derived — always in sync:
type UserUpdateInput = Partial<Omit<User, 'id' | 'createdAt'>>

Partial<T>

Makes all properties optional.

async function updateUser(id: string, data: Partial<Omit<User, 'id'>>) {
  return db.user.update({ where: { id }, data })
}

await updateUser('123', { name: 'Alice' })                          // valid
await updateUser('123', { email: 'alice@example.com', role: 'admin' }) // valid

Required<T>

Makes all properties required — removes optional modifiers.

interface Config {
  apiUrl?: string
  timeout?: number
  retries?: number
}

function resolveConfig(input: Config): Required<Config> {
  return {
    apiUrl: input.apiUrl ?? 'https://api.example.com',
    timeout: input.timeout ?? 5000,
    retries: input.retries ?? 3,
  }
}

Readonly<T>

Makes all properties readonly — TypeScript errors on any mutation.

function getConfig(): Readonly<AppConfig> {
  return { apiUrl: process.env.API_URL!, featureFlags: { newDashboard: true } }
}

const config = getConfig()
config.apiUrl = 'something' // TS Error: Cannot assign to 'apiUrl' because it is a read-only property

Pick<T, K>

Creates a type with only the selected properties.

interface User {
  id: string
  email: string
  name: string
  passwordHash: string
  createdAt: Date
}

// Safe to send to client
type PublicUser = Pick<User, 'id' | 'email' | 'name'>

export async function getCurrentUser(): Promise<PublicUser | null> {
  return db.user.findUnique({
    where: { id: session.userId },
    select: { id: true, email: true, name: true },
  })
}

Omit<T, K>

The inverse — removes the listed properties.

type CreatePostInput = Omit<Post, 'id' | 'createdAt' | 'updatedAt'>
type UpdatePostInput = Partial<Omit<Post, 'id' | 'createdAt' | 'updatedAt' | 'authorId'>>
type PostResponse = Omit<Post, 'authorId'>

Pick vs Omit: Use Pick when you want a small subset. Use Omit when you want everything except a few fields.

Record<K, T>

Creates an object type with typed keys and values.

type Role = 'admin' | 'member' | 'viewer'

const permissions: Record<Role, string[]> = {
  admin: ['read', 'write', 'delete'],
  member: ['read', 'write'],
  viewer: ['read'],
  // TS error if any role key is missing
}

Better than { [key: string]: T } because it enforces exhaustive keys when K is a union.

Exclude<T, U> and Extract<T, U>

These work on union types, not object types.

type Status = 'draft' | 'published' | 'archived' | 'deleted'

type ActiveStatus = Exclude<Status, 'archived' | 'deleted'>
// 'draft' | 'published'

type InactiveStatus = Extract<Status, 'archived' | 'deleted'>
// 'archived' | 'deleted'

Real use case — filtering discriminated union events:

type AppEvent =
  | { type: 'user.created'; userId: string }
  | { type: 'user.deleted'; userId: string }
  | { type: 'post.published'; postId: string }

type UserEvent = Extract<AppEvent, { type: `user.${string}` }>
// { type: 'user.created'; ... } | { type: 'user.deleted'; ... }

function handleUserEvent(event: UserEvent) {
  // Fully type-safe — only receives user events
}

NonNullable<T>

Removes null and undefined.

const maybeUsers: (User | null)[] = await Promise.all(ids.map(getUser))

const users: User[] = maybeUsers.filter(
  (u): u is NonNullable<typeof u> => u !== null
)

ReturnType<T> and Parameters<T>

async function getUser(id: string) {
  return db.user.findUnique({ where: { id } })
}

type ResolvedUser = Awaited<ReturnType<typeof getUser>>
// User | null

// Get types of third-party functions without explicit imports:
import { auth } from '@clerk/nextjs/server'
type AuthResult = Awaited<ReturnType<typeof auth>>

Parameters<T> extracts parameter types — useful for wrapping functions:

function withLogging<T extends (...args: unknown[]) => unknown>(
  fn: T,
  name: string
): (...args: Parameters<T>) => ReturnType<T> {
  return (...args: Parameters<T>) => {
    console.log(`[${name}]`, args)
    return fn(...args) as ReturnType<T>
  }
}

Awaited<T>

Unwraps nested promises recursively.

async function fetchDashboardData() {
  const [user, posts, stats] = await Promise.all([getUser(), getPosts(), getStats()])
  return { user, posts, stats }
}

type DashboardData = Awaited<ReturnType<typeof fetchDashboardData>>
// { user: User; posts: Post[]; stats: Stats }

Combining Utility Types

The real power is composition:

// All derived from one source type:
type CreatePostInput = Omit<Post, 'id' | 'createdAt' | 'updatedAt'>
type UpdatePostInput = Partial<Omit<Post, 'id' | 'createdAt' | 'updatedAt' | 'authorId'>>
type PostResponse   = Omit<Post, 'authorId'>

// Form values from an API type:
type ProfileFormValues = Partial<Pick<UserProfile, 'name' | 'bio' | 'avatarUrl'>>

With Zod

const userSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  name: z.string(),
  role: z.enum(['admin', 'member', 'viewer']),
})

type User = z.infer<typeof userSchema>

// Derive without duplicating the schema:
type UserPatch = Partial<Omit<User, 'id'>>

Quick Reference

Utility Type	What it does
`Partial<T>`	All properties optional
`Required<T>`	All properties required
`Readonly<T>`	All properties readonly
`Pick<T, K>`	Keep listed properties
`Omit<T, K>`	Remove listed properties
`Record<K, T>`	Object with typed keys
`Exclude<T, U>`	Remove union members
`Extract<T, U>`	Keep union members
`NonNullable<T>`	Remove null/undefined
`ReturnType<T>`	Return type of function
`Parameters<T>`	Parameter tuple
`Awaited<T>`	Unwrap promises

The signal: when you find yourself copying a type definition by hand with one field changed, there's a utility type for it.

Full guide at stacknotice.com/blog/typescript-utility-types-guide-2026

Bringing Claude Code Into an Existing Codebase (2026)

Carlos Oliva Pascual — Fri, 19 Jun 2026 11:08:50 +0000

Starting a new project with Claude Code is straightforward. Starting with an existing 50,000-line codebase is a different challenge entirely. The model has no idea what "our auth middleware" means, why you chose this folder structure, or that you migrated away from Redux six months ago and there are still old patterns scattered around.

The teams that get real value from Claude Code on existing projects fast are the ones who treat onboarding like documentation — not for humans, for the model.

Why Existing Codebases Are Harder

Without context, Claude writes code that compiles but doesn't fit. It suggests patterns you've moved away from, adds abstractions you already have elsewhere, or misses that a certain function has a side effect that matters.

The problems:

Accumulated decisions not obvious from the code
Inconsistencies between old and new modules
Dead code that looks active
Hidden dependencies (env vars, DB triggers, webhooks)

The /init Command

cd your-project
claude
> /init

/init reads your project structure and generates a starting CLAUDE.md. It's a foundation — generic enough to be a starting point, not complete enough to be useful on its own. Edit it.

Writing a CLAUDE.md That Actually Helps

Architecture decisions and why:

## Architecture
- Next.js App Router with server components where possible
- Server actions for all mutations — no REST endpoints (migrated Q1 2025)
- Prisma for DB access — raw SQL only in /lib/db/queries.ts
- No Redux — Zustand for global UI state, TanStack Query for server state

Current state:

## Current state
- Auth: fully migrated to Clerk (old next-auth code in /archive/old-auth — ignore it)
- Email: Resend with templates in /emails/ — do not use nodemailer (legacy)
- Background jobs: Inngest — see /inngest/ folder

Things to not touch:

## Do not modify
- /lib/generated/ — auto-generated by Prisma, overwritten on next db push
- /public/static/ — managed by marketing, not in our deploy pipeline
- /legacy/reports/ — frozen, consumed by finance integration

Common patterns:

## Patterns we use
- All server actions in /lib/actions/[domain].ts
- Error handling returns { ok: true/false } — never throw from server actions
- Loading states use Suspense, not isLoading boolean

The "do not modify" section is often the most valuable. Claude will try to be helpful and touch things it shouldn't. Explicit constraints prevent most of that.

The First Tasks: Small, High-Learning

Don't start with "refactor the auth system." Start with read-only tasks that teach Claude the codebase:

"Read the /lib/actions/ folder and describe what each action does.
Don't modify anything — just map what's there."

"Look at an existing component in /components/ui/ and write a new
one that follows the same patterns. Show me before saving."

After two or three of these, you can verify Claude understands your conventions before it touches production code.

Always Read Before Editing

Before any editing prompt, add:

"Before making any changes, read [file] and [related file].
Summarize what you find so I can verify you understand the context."

This feels slow. It isn't. It prevents the two-hour debugging session that happens when Claude refactors a file it never actually read, based entirely on what the filename suggests.

For non-obvious dependencies:

"Read src/services/OrderService.ts. What does it import?
What other files import from it? Map the dependency graph
before we make any changes."

Handling Legacy Patterns

Most existing codebases have two generations of patterns. CLAUDE.md handles most of this, but for ambiguous cases, explicit prompting helps:

"We're in /components/. Older ones use class-based React, newer ones
use function components. We only write function components. Treat
class components as legacy — don't follow their patterns."

"Some files use CSS modules, some use Tailwind. We've standardized
on Tailwind for all new code. Ignore the CSS module files as references."

The Vocabulary Problem

Every codebase has its own vocabulary. When Claude uses a term incorrectly, add it to CLAUDE.md:

## Domain vocabulary
- Order: a purchase record in the orders table (not a cart)
- Cart: temporary pre-purchase state, not persisted to DB
- Member: a User who has an active subscription
- Processing: Order status between "placed" and "fulfilled" — triggers warehouse notification

After a few weeks, your CLAUDE.md has a domain model that makes Claude significantly more accurate on business logic tasks.

Context Management

Reading ten files before making a change puts a lot of tokens in the window. Two strategies:

Read summaries, not full files:

"Read src/services/UserService.ts and give me a 5-sentence summary.
Don't show me the full implementation."

Scope the reading:

"Read only the exported functions from /lib/actions/posts.ts —
just signatures, not implementations."

Use /compact after Claude builds its understanding of the codebase, before it starts writing code.

Incremental Trust

Don't let Claude commit autonomously on day one. Start with:

Claude proposes changes
You review the diff
You commit manually

After a week you'll know which task types Claude handles reliably on your specific codebase.

Updating CLAUDE.md Over Time

Every time Claude makes a mistake because it lacked context, that's a CLAUDE.md entry:

Wrong pattern → add the right one with an example
Touched something it shouldn't → add to "do not modify"
Wrong term → add to vocabulary
Missed a constraint → add to architecture

After a month, your CLAUDE.md captures institutional knowledge that survives session resets — useful for new engineers too, not just Claude.

The First Week Checklist

Run /init — get the baseline CLAUDE.md
Edit CLAUDE.md — architecture, current state, do-not-modify, vocabulary
Run 3 read-only tasks — verify Claude's understanding is accurate
Pick one small, low-risk task — review the output carefully
Update CLAUDE.md from what Claude got wrong
Repeat

The payoff comes after two or three weeks when Claude is writing code that fits your codebase so naturally that reviewers can't tell which parts came from a model.

Full guide at stacknotice.com/blog/claude-code-existing-codebase-guide-2026

Next.js 15 Error Handling: error.tsx, Server Actions, and Sentry (2026)

Carlos Oliva Pascual — Thu, 18 Jun 2026 11:20:17 +0000

Proper error handling in Next.js 15 is spread across four different mechanisms that serve different purposes. Most guides cover one of them. This covers all four — and how they work together in a production app.

The Four Layers of Error Handling

error.tsx — Client component that catches rendering errors in a route segment
global-error.tsx — Catches errors in the root layout itself
Server action errors — Errors that happen during mutations and form submissions
not-found.tsx — Handles 404s from notFound() calls

These are separate concerns with separate solutions. Confusing them leads to errors that silently fail or crash the wrong boundary.

error.tsx — Route-Level Boundaries

Every folder in your app/ directory can have its own error.tsx. When a component in that segment throws, Next.js renders the error.tsx instead.

// app/dashboard/error.tsx
'use client'

import { useEffect } from 'react'
import * as Sentry from '@sentry/nextjs'

interface ErrorProps {
  error: Error & { digest?: string }
  reset: () => void
}

export default function DashboardError({ error, reset }: ErrorProps) {
  useEffect(() => {
    Sentry.captureException(error, {
      tags: { section: 'dashboard', digest: error.digest },
    })
  }, [error])

  return (
    <div className="flex flex-col items-center justify-center min-h-[400px] gap-4">
      <h2 className="text-xl font-semibold text-gray-900">
        Something went wrong
      </h2>
      <p className="text-sm text-gray-500 max-w-md text-center">
        {error.message || 'An unexpected error occurred.'}
      </p>
      <button
        onClick={reset}
        className="px-4 py-2 bg-blue-600 text-white rounded-md text-sm hover:bg-blue-700"
      >
        Try again
      </button>
    </div>
  )
}

The reset function re-renders the segment. The error.digest is a server-side hash you can use to correlate client errors with server logs.

Important: error.tsx must include 'use client'. Error boundaries in React require client-side code.

The error.tsx in app/dashboard/ catches errors in app/dashboard/page.tsx and any nested routes. It does not catch errors in app/dashboard/layout.tsx itself.

global-error.tsx — Root Layout Boundary

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <div className="flex flex-col items-center justify-center min-h-screen gap-4 p-8">
          <h1 className="text-2xl font-bold">Something went wrong</h1>
          <p className="text-gray-600 text-center max-w-md">
            A critical error occurred. Please refresh the page.
          </p>
          <button
            onClick={reset}
            className="px-6 py-2 bg-red-600 text-white rounded-md hover:bg-red-700"
          >
            Refresh
          </button>
        </div>
      </body>
    </html>
  )
}

Notice it includes <html> and <body> — it replaces the root layout entirely when it triggers. In development, Next.js shows its own error overlay instead.

not-found.tsx

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { getPost } from '@/lib/posts'

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)

  if (!post) {
    notFound()
  }

  return <article>{/* render post */}</article>
}

// app/not-found.tsx
import Link from 'next/link'

export default function NotFound() {
  return (
    <div className="flex flex-col items-center justify-center min-h-[60vh] gap-4">
      <h2 className="text-4xl font-bold text-gray-900">404</h2>
      <p className="text-gray-600">The page you're looking for doesn't exist.</p>
      <Link href="/" className="px-4 py-2 bg-gray-900 text-white rounded-md text-sm">
        Go home
      </Link>
    </div>
  )
}

Unlike error.tsx, not-found.tsx is a Server Component by default. You can have one per route segment.

Server Action Errors

Throwing inside a server action in production shows nothing useful to the client. The pattern that works is returning a typed result object instead:

// lib/actions/auth.ts
'use server'

type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string }

export async function signIn(
  formData: FormData
): Promise<ActionResult<{ userId: string }>> {
  const email = formData.get('email') as string
  const password = formData.get('password') as string

  if (!email || !password) {
    return { success: false, error: 'Email and password are required' }
  }

  try {
    const user = await db.user.findUnique({ where: { email } })

    if (!user || !(await verifyPassword(password, user.passwordHash))) {
      return { success: false, error: 'Invalid credentials' }
    }

    return { success: true, data: { userId: user.id } }
  } catch (err) {
    console.error('SignIn error:', err)
    return { success: false, error: 'Authentication failed. Please try again.' }
  }
}

On the client side, use useActionState:

// app/login/page.tsx
'use client'

import { useActionState } from 'react'
import { signIn } from '@/lib/actions/auth'

type State = { error?: string } | null

export default function LoginPage() {
  const [state, formAction, isPending] = useActionState(
    async (_prev: State, formData: FormData): Promise<State> => {
      const result = await signIn(formData)
      if (!result.success) return { error: result.error }
      return null
    },
    null
  )

  return (
    <form action={formAction} className="flex flex-col gap-4 max-w-sm mx-auto">
      <input name="email" type="email" placeholder="Email" required className="border rounded-md px-3 py-2" />
      <input name="password" type="password" placeholder="Password" required className="border rounded-md px-3 py-2" />
      {state?.error && (
        <p className="text-sm text-red-600">{state.error}</p>
      )}
      <button
        type="submit"
        disabled={isPending}
        className="px-4 py-2 bg-blue-600 text-white rounded-md disabled:opacity-50"
      >
        {isPending ? 'Signing in...' : 'Sign in'}
      </button>
    </form>
  )
}

Typed Errors with Discriminated Unions

For complex apps, typed error codes prevent string messages from getting out of control:

// lib/errors.ts
export type AppError =
  | { code: 'NOT_FOUND'; resource: string }
  | { code: 'UNAUTHORIZED'; reason: string }
  | { code: 'VALIDATION_FAILED'; fields: Record<string, string> }
  | { code: 'RATE_LIMITED'; retryAfter: number }
  | { code: 'INTERNAL'; message: string }

export function getErrorMessage(error: AppError): string {
  switch (error.code) {
    case 'NOT_FOUND':
      return `${error.resource} not found`
    case 'UNAUTHORIZED':
      return `Unauthorized: ${error.reason}`
    case 'VALIDATION_FAILED':
      return Object.values(error.fields).join(', ')
    case 'RATE_LIMITED':
      return `Too many requests. Try again in ${error.retryAfter}s`
    case 'INTERNAL':
      return 'An unexpected error occurred'
  }
}

TypeScript enforces that you handle every error code — no silent fallthrough.

Sentry Integration

npm install @sentry/nextjs
npx @sentry/wizard@latest -i nextjs

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.05,
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
})

For server actions, capture before returning:

import * as Sentry from '@sentry/nextjs'

export async function createPost(formData: FormData) {
  try {
    // ...
  } catch (err) {
    Sentry.captureException(err, { tags: { action: 'createPost' } })
    return { ok: false, error: { code: 'INTERNAL' as const, message: 'Failed' } }
  }
}

Handling Errors in Layouts

If app/dashboard/layout.tsx throws, the app/dashboard/error.tsx does not catch it. Use try/catch inside the layout:

// app/dashboard/layout.tsx
import { redirect } from 'next/navigation'
import { getUser } from '@/lib/auth'

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  let user

  try {
    user = await getUser()
  } catch {
    redirect('/login')
  }

  if (!user) redirect('/login')

  return (
    <div className="min-h-screen bg-gray-50">
      <nav>{/* nav */}</nav>
      <main className="container mx-auto py-8">{children}</main>
    </div>
  )
}

The Complete File Structure

app/
  dashboard/
    layout.tsx       ← shared layout
    page.tsx         ← content (async Server Component)
    loading.tsx      ← skeleton while page.tsx suspends
    error.tsx        ← error boundary (Client Component)
    not-found.tsx    ← 404 for this segment

Next.js automatically wraps page.tsx in a <Suspense> boundary when loading.tsx is present, and in an error boundary when error.tsx is present.

Quick Reference

Scenario	Solution
Route segment throws	`error.tsx` in same folder
Root layout throws	`global-error.tsx`
Resource not found	`notFound()` + `not-found.tsx`
Server action fails	Return `{ ok: false, error }`
Track in production	Sentry in `error.tsx` + server actions
Layout error	try/catch in layout or parent `error.tsx`

Production apps fail. The question is whether they fail gracefully with useful Sentry traces and clear user messages, or with a blank white screen and zero context to debug from.

Full guide at stacknotice.com/blog/nextjs-error-handling-2026

Refactoring with Claude Code: The Workflow That Actually Works (2026)

Carlos Oliva Pascual — Thu, 18 Jun 2026 08:47:37 +0000

Refactoring is where most developers discover Claude Code's real limitations — and its real strengths. Sent into a large file without context, Claude hallucinates method names and misses side effects. Given the right structure, it can refactor a 600-line god component in under ten minutes while keeping every test green.

The difference is entirely in the workflow.

Why Refactoring Is Hard for AI

A fresh context window knows nothing. It doesn't know that UserService calls AuthService under the hood. It doesn't know the database expects snake_case. It doesn't know you migrated from Redux to Zustand six months ago.

This is exactly why refactoring fails out of the box: you hand Claude a file, ask it to clean it up, and it invents new abstractions that break three other files you didn't show it.

The fix is context — but not context in the chat window. Context in your codebase.

Rule 0: Always Read Before Changing

Before asking Claude to refactor anything, make sure it has read:

The file being changed
Every file that imports from it
Every file it imports from
Relevant types or interfaces

# Instead of: "refactor UserService"
# Do this first:

claude "Read src/services/UserService.ts, src/types/user.ts, and every file
that imports UserService. Once you understand the full picture, summarize
what UserService does and what would break if we changed its interface."

The summary step is not optional. It forces Claude to actually read instead of pattern-matching on the filename.

CLAUDE.md as Your Refactoring Brief

If you're doing a large refactoring effort that spans multiple sessions, your CLAUDE.md is the place to encode the rules.

# CLAUDE.md — Refactoring Context

## Current goal
Splitting the monolithic UserController into:
- UserAuthController (login, register, token refresh)
- UserProfileController (read/update profile)
- UserAdminController (admin-only operations)

## Rules for this refactor
- Keep all existing HTTP endpoints — external clients depend on them
- New services are injectable (constructor injection, not singletons)
- All database calls go through the repository layer, not direct Prisma calls
- Error responses follow the existing ErrorResponse type in src/types/errors.ts

## Already done
- UserAuthController: done, tests passing
- UserProfileController: done, tests passing
- UserAdminController: in progress

## Do not touch
- src/middleware/auth.ts — frozen until v2
- src/types/ApiResponse.ts — external contract

This pays off immediately. Every new session starts knowing where you are, what the rules are, and what not to break. You skip five minutes of re-explaining the codebase at the start of each task.

The Four-Step Refactoring Workflow

Step 1: Understand

Never start with a change. Start with a question.

"Read src/components/UserDashboard.tsx and its imports. Tell me:
- What does it currently do?
- What are its dependencies?
- What state does it manage?
- What would be risky to move?"

Step 2: Plan

Ask Claude to propose the refactoring before writing a single line.

"Based on what you've read, propose how you'd split UserDashboard into
smaller components. List each new component, what it would contain,
and what props it would need. Don't write any code yet."

Review the plan. This is where you catch bad ideas before they're in the code.

Step 3: Execute in Chunks

Never ask Claude to refactor an entire large file in one shot.

"Implement step 1 from the plan: extract UserDashboardHeader into
its own file at src/components/UserDashboardHeader.tsx. Keep the
logic identical — no behavior changes, just extraction. Update
the import in UserDashboard.tsx."

One thing at a time. One file changed, one file updated. After each chunk, run your tests.

Step 4: Verify

"The tests are passing. Now review the diff of what changed.
Does UserDashboard.tsx still have any logic that belongs in
UserDashboardHeader? Is there anything we missed?"

Handling Large Files

Files over 400–500 lines hit a practical problem: Claude reads them, but the beginning is compressed by the time it's writing changes at line 450.

Strategy A: Read sections, not the full file

"Read lines 1-150 of src/services/OrderService.ts.
Tell me what those lines do and what functions they define."

Work section by section. Use /compact between major chunks to keep the context clean.

Strategy B: Extract the interface first

"Read src/services/OrderService.ts and extract only the public
method signatures (not the implementations) into a summary.
We'll use this as our working reference while we refactor."

Renaming at Scale

"I need to rename `userId` to `user_id` across the repository
to match our database naming convention.

1. First, use grep to find every file that uses `userId`
2. List them — don't change anything yet
3. I'll tell you which files to update"

The list-first step is important. Blindly changing every occurrence will catch false positives — comments, test fixtures, generated code you shouldn't touch.

Extracting Services from God Components

The most common real-world refactoring: a React component that has grown to 500+ lines.

The extraction order matters:

Extract types first — Zero risk, zero behavior change.
Extract pure functions — Any function that doesn't touch state goes to utils.ts.
Extract hooks — Any useState/useEffect cluster that belongs together becomes a custom hook.
Extract sub-components — Once hooks are clean, JSX sections become obvious component boundaries.

Each step is a separate Claude session with a separate commit. Never combine steps.

Keeping Tests Green

Run tests after every step. Not after every session — after every step.

If your tests don't cover the code you're refactoring, write characterization tests before you start:

"Before we refactor UserService, write tests that cover its
current behavior. I don't care if the tests are ugly — I just
need a safety net that will tell me if the refactor changes
any observable behavior."

Common Pitfalls

Pitfall 1: Showing only the file you're refactoring

Claude doesn't know what imports it. Refactors perfectly in isolation, three callers break.

Fix: Always show callers when refactoring public interfaces.

Pitfall 2: Long sessions for large refactors

Context degrades after 90 minutes. Claude starts forgetting CLAUDE.md rules and re-introducing patterns you already corrected.

Fix: Use /compact aggressively. Break multi-day refactors into sessions.

Pitfall 3: Not committing between steps

Every successful step deserves a commit. If step 4 breaks everything, you want git revert to step 3, not start from scratch.

A Real Example: Splitting a God Service

Session 1:
"Read OrderService.ts and all files that import from it. Summarize
what the service does and identify natural domain boundaries."

→ Claude identifies: payment logic, inventory logic, notification logic

Session 2 (after /clear):
"Read OrderService.ts. Extract all payment-related methods into
PaymentService.ts. Keep OrderService calling PaymentService —
no interface changes for callers."

→ Commit: "refactor: extract PaymentService from OrderService"

Session 3 (after /clear):
"Read OrderService.ts. Extract inventory methods. Same pattern."

→ Commit: "refactor: extract InventoryService from OrderService"

Each session is focused, clean, and committed.

The Rule of One

Refactoring with Claude Code comes down to one principle: one thing at a time.

One file read. One change proposed. One step executed. One test run. One commit.

The urge to "just do the whole thing" leads to sessions where you've lost track of what changed, tests fail in three places, and you're debugging Claude's refactoring instead of shipping features.

Full guide with internal links at stacknotice.com/blog/claude-code-refactoring-guide-2026

Claude Code /compact vs /clear (2026): Managing Long Sessions Without Losing Quality

Carlos Oliva Pascual — Wed, 17 Jun 2026 14:02:34 +0000

You start a Claude Code session sharp. An hour in, responses get vague. Two hours in, Claude starts contradicting earlier decisions.

It's not Claude getting worse. It's what happens when a context window fills up and nobody manages it.

Full guide at stacknotice.com/blog/claude-code-compact-clear-context-2026

Why sessions degrade

As the context fills, earlier information gets less weight, contradictions between early and late instructions emerge, and Claude has less room to reason. The session that started great ends frustrating.

/compact — compress without losing flow

Summarizes earlier conversation history while keeping recent context intact. Key decisions and agreements are preserved in shorter form.

Use when:

Session is 45-60+ minutes in
You're mid-task and don't want to lose context
Responses are getting shorter or less precise

Preserves: current task state, key agreements, CLAUDE.md conventions
Loses: step-by-step detail from early in the session

> /compact

Claude: Summarized. Here's what I kept:
- Building checkout flow with Stripe
- Server actions for mutations (not API routes)
- Webhook handler done, working on UI next

Ready to continue.

Session continues. No re-explaining needed.

/clear — hard reset

Wipes the conversation completely. CLAUDE.md reloads automatically.

Use when:

Finished one task, starting something unrelated
Session went the wrong direction
/compact isn't enough

Preserves: CLAUDE.md, your project files
Loses: everything from the conversation

The decision

Still on the same task?  →  /compact
New task or wrong direction?  →  /clear

Patterns that help

Front-load context — tell Claude what you're building and the constraints at the start. It carries more weight early in the context.

Break large work into sessions — 4 hours of coding doesn't need one session. Finish the DB layer, /clear, start the API layer fresh.

Use /compact proactively — don't wait for quality to drop. Run it at natural checkpoints.

Reference CLAUDE.md instead of re-explaining — your conventions reload automatically. Don't waste context repeating them.

Extended thinking note

Ultrathink uses 3-5x more context per response. If you use it regularly, run /compact more aggressively — after every 2-3 extended thinking calls.

Full guide with the full decision tree at stacknotice.com/blog/claude-code-compact-clear-context-2026

Claude Code Custom Slash Commands (2026): Automate Your Repetitive Workflows

Carlos Oliva Pascual — Wed, 17 Jun 2026 11:15:11 +0000

Claude Code has built-in slash commands. Most devs stop there.

You can create your own — any workflow you repeat becomes a one-word command.

Full guide at stacknotice.com/blog/claude-code-custom-commands-2026

How it works

Create .claude/commands/ in your project root. Each file becomes a slash command:

.claude/commands/review.md      →  /review
.claude/commands/add-tests.md   →  /add-tests
.claude/commands/deploy-check.md →  /deploy-check

The file content is the prompt. No special syntax needed.

Your first command

<!-- .claude/commands/review.md -->
Review the current changes.

Check:
- Auth before any DB mutation
- Zod validation on all inputs
- CLAUDE.md convention compliance
- Error handling on async operations

Numbered list, file:line. Skip style and naming.

Now just type /review in any session.

Using $ARGUMENTS

<!-- .claude/commands/add-tests.md -->
Add tests for $ARGUMENTS.

Use Vitest. Happy path + one edge case + one error case.
Test behavior, not implementation. Match existing test style.

> /add-tests src/lib/stripe/webhooks.ts

Commands worth building immediately

/deploy-check — run before every deploy:

We're about to deploy to production.
Flag anything you would not ship right now.
One sentence per issue, most critical first.
If safe: say "Ready to deploy" and nothing else.

/security — focused security audit:

Security review of $ARGUMENTS.
Check: missing auth, ownership verification, unvalidated inputs, exposed secrets.
Issues only. No compliments.

/commit — generate commit messages:

Write a git commit message for staged changes.
Imperative mood, max 72 chars. Describe what changed and why.
Output the message only — don't run the commit.

Share with the team

git add .claude/commands/
git commit -m "add team Claude Code commands"

Every dev gets the same commands on pull. One push, team-wide consistency.

Personal vs project commands

Project: .claude/commands/ — this repo only
Global: ~/.claude/commands/ — all your projects

Project commands override global ones if names match.

Full guide with more examples at stacknotice.com/blog/claude-code-custom-commands-2026

Claude Code for PR Reviews (2026): How to Get Real Feedback, Not Generic Slop

Carlos Oliva Pascual — Tue, 16 Jun 2026 11:02:46 +0000

The first time you ask Claude to review code: "This looks good overall. Consider adding error handling and making sure tests are comprehensive."

That's not a review. That's a fortune cookie with TypeScript keywords.

The fix is context, not a better prompt.

Full guide at stacknotice.com/blog/claude-code-pr-review-guide-2026

Why generic AI review fails

When you paste a diff and say "review this," Claude doesn't know your conventions, your stack, your constraints. It falls back to universal best practices: add error handling, write tests. True but useless.

CLAUDE.md changes everything

Claude Code reads your CLAUDE.md automatically. If it says "Zustand only, no React Context" and a PR adds a Context provider — Claude flags it every time. That's specific, actionable feedback.

Prompt structure that works

Three parts: what changed, what to focus on, what to ignore.

claude "Review the PR that adds Stripe webhook handling.

Context: handles payment_intent.succeeded and customer.subscription.deleted.

Focus on:
- Idempotency: can these handlers be called twice safely?
- Auth: are we validating the Stripe signature?
- Ownership: does the subscription belong to the right org?

Skip: style, naming, test coverage."

Focused prompt → focused feedback. When Claude flags 5 things, all 5 matter.

The diff review pattern

git diff main...HEAD | claude --print \
  "Review this diff. Check: auth before data access, Zod validation on inputs,
   correct optimistic updates. Output as numbered list with file:line.
   Skip anything that's not correctness or security."

The two-Claude pattern

Most underused review technique: fresh session, no context from the author.

# Session 1: write the feature
claude "implement the cart checkout flow"

# Session 2: fresh terminal, fresh session
claude "review src/lib/checkout/ against CLAUDE.md.
What would a senior dev flag? Be direct, don't soften issues."

The author session is biased. The reviewer session isn't.

GitHub Actions

- name: Claude review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude --dangerously-skip-permissions --print \
      "Review this diff. Flag only real issues: missing auth checks,
       broken error handling, convention violations. Skip style.
       Format: file:line — issue — why it matters.
       DIFF: $(cat pr.diff)" > review.md

What Claude catches better than humans

Cross-file consistency — same error handling done 5 different ways across the diff
Ownership checks — mutation without verifying the record belongs to the user
Convention violations — anything in CLAUDE.md that the PR breaks
Missing validation — input going to DB without Zod

Humans catch: wrong approach, architectural problems, intent mismatch. Both are needed.

Full guide with prompt templates at stacknotice.com/blog/claude-code-pr-review-guide-2026

DEV Community: Carlos Oliva Pascual

React 19 useTransition & useDeferredValue: When to Use Which (2026)

What "Transition" Actually Means

useTransition: Wrap the Setter

useTransition with Server Actions

Navigation Loading State

useDeferredValue: Wrap the Value

How it works frame by frame

useOptimistic: The Third Member

The Actual Difference

Common Mistakes

Next.js Partial Prerendering (PPR) Guide (2026)

How PPR Works

Enabling PPR

Building a PPR Page

The static component

The dynamic components

Deduplicate Requests with cache()

Suspense Fallbacks That Don't Shift Layout

Nested Suspense Boundaries

PPR vs Other Strategies

Isolating searchParams

What Makes a Component Dynamic (Checklist)

When to Use PPR

Git Worktrees + Claude Code: Run Parallel AI Agents on the Same Repo (2026)

What Git Worktrees Actually Are

Why This Pairs Well with Claude Code

Setting Up Worktrees

Starting Claude Code in each

A Real Parallel Workflow

Per-Task CLAUDE.md

Worktrees vs Subagents

Headless Batch Execution

Managing Worktrees

Common Issues

Shell Alias

Next.js 15 SEO: metadata, OG Images, Sitemap, and Structured Data (2026)

Two Ways to Define Metadata

Title Templates

Dynamic Open Graph Images

sitemap.xml

robots.txt

JSON-LD Structured Data

Canonical URLs

Deduplicating Data Fetches

Common Pitfalls

Quick Verification

Claude Code in Scripts: Headless Mode and Automation (2026)

The -p Flag

Output Formats

Real Script: Auto-Changelog

Real Script: Commit Message Generator

Real Script: Batch PR Review

Git Hook: Auto-suggest Commit Messages

In CI/CD

Error Handling

When to Use Headless vs Interactive

TypeScript Utility Types: The Complete Guide (2026)

Why Utility Types Exist

Partial<T>

Required<T>

Readonly<T>

Pick<T, K>

Omit<T, K>

Record<K, T>

Exclude<T, U> and Extract<T, U>

NonNullable<T>

ReturnType<T> and Parameters<T>

Awaited<T>

Combining Utility Types

With Zod

Quick Reference

Bringing Claude Code Into an Existing Codebase (2026)

Why Existing Codebases Are Harder

The /init Command

Writing a CLAUDE.md That Actually Helps

The First Tasks: Small, High-Learning

Always Read Before Editing

Handling Legacy Patterns

The Vocabulary Problem

Deduplicate Requests with `cache()`

Isolating `searchParams`