DEV Community: Carlos Oliva Pascual

Sentry + Next.js: Complete Error Monitoring Guide (2026)

Carlos Oliva Pascual — Wed, 01 Jul 2026 18:33:56 +0000

Most Next.js apps go to production with no idea what's actually failing for users. console.error doesn't reach you, Vercel logs have minified stack traces, and you find out about errors when a user reports them. Sentry fixes this — but the App Router setup has enough gotchas that a "quick install" turns into an afternoon.

Installation

npx @sentry/wizard@latest -i nextjs

The wizard creates the three config files, wraps next.config.ts, generates instrumentation.ts and global-error.tsx, and sets up source map upload.

Three Config Files

Sentry initializes separately for each Next.js runtime:

// 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,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [Sentry.replayIntegration({ maskAllText: true })],
  enabled: process.env.NODE_ENV === 'production',
})

// sentry.server.config.ts
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
  enabled: process.env.NODE_ENV === 'production',
})

// sentry.edge.config.ts (for middleware)
Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 })

instrumentation.ts

// instrumentation.ts (at root, not inside app/)
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('../sentry.server.config')
  }
  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('../sentry.edge.config')
  }
}

Error Boundaries in App Router

error.tsx — route segment errors

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

export default function DashboardError({
  error, reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // error.digest correlates client error with server log
    Sentry.captureException(error, { tags: { digest: error.digest } })
  }, [error])

  return (
    <div>
      <h2>Something went wrong</h2>
      <p>Reference: {error.digest}</p>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

global-error.tsx — root layout errors

error.tsx doesn't catch root layout errors. global-error.tsx does — and it must include <html> and <body>:

'use client'
export default function GlobalError({ error, reset }: { error: Error, reset: () => void }) {
  useEffect(() => { Sentry.captureException(error) }, [error])
  return (
    <html><body>
      <h1>Application Error</h1>
      <button onClick={reset}>Reload</button>
    </body></html>
  )
}

Server Actions Instrumentation

Server Actions aren't automatically captured. Wrap them explicitly:

'use server'
import * as Sentry from '@sentry/nextjs'

export const createPost = Sentry.withServerActionInstrumentation(
  'createPost',
  { recordResponse: true },
  async (formData: FormData) => {
    await db.insert(posts).values({
      title: formData.get('title') as string,
    })
    return { success: true }
  }
)

User Context

// After authentication
Sentry.setUser({ id: session.user.id, email: session.user.email })
Sentry.setTag('plan', 'pro')
Sentry.setContext('subscription', { seats: 25 })

// On logout
Sentry.setUser(null)

Source Maps

Without source maps: at n (chunks/pages.js:1:4523) — useless.
With source maps: at DashboardPage (app/dashboard/page.tsx:47:12) — actionable.

# .env.local + Vercel env vars
SENTRY_AUTH_TOKEN=your-token  # Settings → API Keys in Sentry dashboard
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug

withSentryConfig in next.config.ts uploads source maps automatically during next build.

Sampling Strategy

tracesSampler: (ctx) => {
  if (ctx.parentSampled) return 1        // always trace if parent does
  const url = ctx.location?.href ?? ''
  if (url.includes('/checkout')) return 0.5
  if (url.includes('/api/webhooks')) return 1.0
  return 0.05                             // default: 5%
},

Quick Reference

// Capture with context
Sentry.captureException(error, { tags: { action: 'checkout' } })

// User context
Sentry.setUser({ id: user.id, email: user.email })

// Custom span
await Sentry.startSpan({ name: 'db.query', op: 'db.query' }, () => db.select()...)

// Server Action wrapper
export const action = Sentry.withServerActionInstrumentation('name', {}, async () => {})

// error.tsx
useEffect(() => { Sentry.captureException(error) }, [error])

Minimum viable setup: run the wizard, set enabled: process.env.NODE_ENV === 'production', add error.digest in error.tsx, set user context after auth. Everything else layers in as the app matures.

Full article at stacknotice.com/blog/sentry-nextjs-complete-guide-2026

Core Web Vitals & INP Optimization for React Apps (2026)

Carlos Oliva Pascual — Tue, 30 Jun 2026 11:41:08 +0000

In March 2024, Google replaced FID (First Input Delay) with INP (Interaction to Next Paint) as a Core Web Vital. INP is harder to pass than FID — it measures all interactions throughout the page's life, not just the first one — and React apps have specific patterns that tank it.

What INP Measures

FID measured only the delay before processing started — it ignored how long the work took.

INP measures the full visual response time: from user click/tap/keypress to when the browser paints the next frame. It tracks ALL interactions throughout the session and reports the worst one.

Thresholds:

Good: < 200ms
Needs improvement: 200–500ms
Poor: > 500ms

A button click that triggers a 300ms React re-render fails INP. FID would have passed it.

What Causes High INP in React Apps

Long event handlers — the main thread can't paint until a task finishes:

// ❌ 300ms of sync work before the browser paints
function handleFilterChange(value: string) {
  setFilter(value)
  const filtered = heavyFilter(allProducts, value) // 200ms
  setFilteredProducts(filtered)
  updateAnalytics(value) // 80ms
}

Large React re-renders — updating state triggers full tree reconciliation:

// ❌ Input change re-renders 500 ProductCard components
function SearchPage() {
  const [query, setQuery] = useState('')
  const results = products.filter(p => p.name.includes(query))
  return (
    <>
      <input onChange={(e) => setQuery(e.target.value)} />
      <ProductGrid items={results} /> {/* 500 items, expensive */}
    </>
  )
}

Measuring INP

npm install web-vitals

import { onINP } from 'web-vitals'

onINP((metric) => {
  console.log('INP:', metric.value, 'ms', metric.rating)
  // metric.attribution tells you WHICH element caused it
  analytics.track('inp', {
    value: metric.value,
    rating: metric.rating,
    element: metric.attribution?.interactionTarget,
    type: metric.attribution?.interactionType,
  })
})

Fix 1: useTransition

Marks non-urgent updates as deferrable — the input responds immediately, the list updates after paint:

export function SearchPage({ products }: { products: Product[] }) {
  const [query, setQuery] = useState('')
  const [deferredQuery, setDeferredQuery] = useState('')
  const [isPending, startTransition] = useTransition()

  function handleSearch(value: string) {
    setQuery(value) // urgent — paint immediately
    startTransition(() => {
      setDeferredQuery(value) // deferred — after paint
    })
  }

  const filtered = useMemo(
    () => products.filter(p => p.name.toLowerCase().includes(deferredQuery.toLowerCase())),
    [products, deferredQuery]
  )

  return (
    <>
      <input value={query} onChange={(e) => handleSearch(e.target.value)}
             className={isPending ? 'opacity-70' : ''} />
      <ProductGrid items={filtered} />
    </>
  )
}

Fix 2: useDeferredValue

When the slow work is in a child component:

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

  return (
    <>
      <input onChange={(e) => setQuery(e.target.value)} />
      {/* Renders with stale query until React can update safely */}
      <ExpensiveList query={deferredQuery} />
    </>
  )
}

Fix 3: scheduler.yield()

Yields back to the browser in the middle of a long task:

async function processLargeDataset(items: Item[]) {
  const results = []
  for (let i = 0; i < items.length; i++) {
    results.push(expensiveProcess(items[i]))
    if (i % 50 === 0) {
      await scheduler.yield() // let the browser paint between chunks
    }
  }
  return results
}

Fix 4: Virtualize Long Lists

npm install @tanstack/react-virtual

import { useVirtualizer } from '@tanstack/react-virtual'

export function VirtualProductList({ products }: { products: Product[] }) {
  const parentRef = useRef<HTMLDivElement>(null)
  const virtualizer = useVirtualizer({
    count: products.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 72,
  })

  return (
    <div ref={parentRef} className="h-96 overflow-auto">
      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualItem) => (
          <div key={virtualItem.key}
               style={{ position: 'absolute', top: `${virtualItem.start}px`, width: '100%' }}>
            <ProductCard product={products[virtualItem.index]} />
          </div>
        ))}
      </div>
    </div>
  )
}

500 items → ~10 rendered. Re-render cost drops 98%.

Fix 5: Code Split Heavy Interactions

const HeavyDashboard = dynamic(() => import('@/components/analytics-dashboard'))

function AnalyticsButton() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <button
        onMouseEnter={() => import('@/components/analytics-dashboard')} // preload
        onClick={() => setOpen(true)}
      >
        View Analytics
      </button>
      {open && <HeavyDashboard />}
    </>
  )
}

Click handler is now just setOpen(true) — instant.

Fix 6: next/script for Third-Party Code

import Script from 'next/script'

{/* ❌ Blocks main thread */}
<script src="https://analytics.example.com/script.js" />

{/* ✅ Loads after page is interactive */}
<Script src="https://analytics.example.com/script.js" strategy="lazyOnload" />

INP Decision Tree

High INP?
├─ From click/tap:
│   ├─ Long event handler → startTransition() for non-urgent updates
│   ├─ Large re-render → useDeferredValue + memo()
│   ├─ Heavy component loading → next/dynamic + preload on hover
│   └─ Third-party script → next/script lazyOnload
│
└─ From keypress:
    ├─ useTransition for the filter/search update
    └─ useDeferredValue if slow work is in a child component

INP good in dev, bad in production:
└─ Profile on real hardware — DevTools CPU 4x throttle

The main lever: useTransition. Most React INP failures are large re-renders triggered by user input that can be deferred. Measure before and after with the web-vitals library.

Full article at stacknotice.com/blog/web-vitals-inp-optimization-2026

React Suspense & the use() Hook: Complete Guide (2026)

Carlos Oliva Pascual — Mon, 29 Jun 2026 11:19:40 +0000

Suspense has been in React since 16.6, but data fetching with Suspense was experimental until React 18/19. Now it's a first-class async UI primitive, and the new use() hook gives you a direct way to integrate it without a library.

What Suspense Actually Does

Suspense doesn't know anything about fetching. When a component throws a Promise during render, React catches it, renders the nearest <Suspense> boundary's fallback, and retries when the Promise resolves.

// Conceptually, what libraries do:
function fetchUser(id: string) {
  if (cache.has(id)) return cache.get(id)
  const promise = fetch(`/api/users/${id}`).then(r => r.json())
  cache.set(id, promise)
  throw promise  // ← Suspense catches this
}

The use() Hook

React 19's use() unwraps a Promise (or Context) inline during render, integrating with Suspense automatically:

import { use, Suspense } from 'react'

function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise) // suspends until resolved
  return <div><h2>{user.name}</h2><p>{user.email}</p></div>
}

function Page() {
  const userPromise = fetchUser('123') // created once, passed down

  return (
    <Suspense fallback={<ProfileSkeleton />}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  )
}

Critical: Create the Promise outside the component. If you create it inside, you get a new Promise on every render — infinite suspense loop:

// ❌ New Promise every render — infinite loop
function UserProfile({ id }: { id: string }) {
  const user = use(fetchUser(id))
}

// ✅ Stable Promise reference passed as prop
function Page({ id }: { id: string }) {
  const userPromise = useMemo(() => fetchUser(id), [id])
  return (
    <Suspense fallback={<Skeleton />}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  )
}

use() with Context

use() also works as a context reader — unlike useContext, it can be called inside conditions:

function Button({ disabled }: { disabled?: boolean }) {
  if (disabled) return <button disabled>...</button>

  const theme = use(ThemeContext) // ✅ conditional call works
  return <button className={theme.buttonClass}>...</button>
}

Error Boundaries

When a Promise rejects, you need an Error Boundary (Suspense only handles pending state):

npm install react-error-boundary

import { ErrorBoundary } from 'react-error-boundary'

function FallbackUI({ error, resetErrorBoundary }: FallbackProps) {
  return (
    <div>
      <p>Failed to load: {error.message}</p>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  )
}

// ErrorBoundary MUST be outside Suspense
<ErrorBoundary FallbackComponent={FallbackUI}>
  <Suspense fallback={<Loading />}>
    <AsyncComponent />
  </Suspense>
</ErrorBoundary>

Nested Suspense: Progressive Loading

Instead of one giant loading state, nest boundaries so each section loads independently:

export default function DashboardPage() {
  const statsPromise = fetchStats()          // fast
  const activityPromise = fetchActivity()    // medium
  const recsPromise = fetchRecommendations() // slow

  return (
    <main>
      <Suspense fallback={<StatsSkeleton />}>
        <StatsSection statsPromise={statsPromise} />
      </Suspense>

      <Suspense fallback={<ActivitySkeleton />}>
        <ActivityFeed activityPromise={activityPromise} />
      </Suspense>

      <Suspense fallback={<RecsSkeleton />}>
        <Recommendations recsPromise={recsPromise} />
      </Suspense>
    </main>
  )
}

Users see content progressively as each section resolves — no waiting for the slowest section.

Suspense in Next.js Server Components

Server Components can be async — they await data directly. Suspense coordinates streaming:

// Server Component — no 'use client'
async function StatsSection() {
  const stats = await fetchStats()
  return <StatsGrid stats={stats} />
}

export default function DashboardPage() {
  return (
    <main>
      {/* HTML streams to the client as each section completes */}
      <Suspense fallback={<StatsSkeleton />}>
        <StatsSection />
      </Suspense>
    </main>
  )
}

No client-side JavaScript needed, no useEffect, no re-fetching on hydration.

Pass Promises from Server to Client

Kick off fetching on the server, pass the Promise to a Client Component:

// Server Component — starts fetch immediately, doesn't await
export default async function ProductPage({ params }: { params: { id: string } }) {
  const reviewsPromise = fetchReviews(params.id) // no await

  return (
    <div>
      <ProductInfo id={params.id} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <ReviewsSection reviewsPromise={reviewsPromise} />
      </Suspense>
    </div>
  )
}

// Client Component
'use client'
function ReviewsSection({ reviewsPromise }: { reviewsPromise: Promise<Review[]> }) {
  const reviews = use(reviewsPromise)
  return <ReviewsList reviews={reviews} />
}

The fetch starts on the server before the client hydrates. By the time hydration happens, the Promise may already be resolved.

useTransition + Suspense: Avoid Fallback Flicker

When navigating or updating state, useTransition keeps the old content visible instead of showing the skeleton:

'use client'

function ProductList() {
  const [isPending, startTransition] = useTransition()
  const [category, setCategory] = useState('all')

  function handleChange(newCategory: string) {
    startTransition(() => setCategory(newCategory))
  }

  return (
    <div>
      <CategoryFilter onChange={handleChange} disabled={isPending} />
      {/* No skeleton flash — old content stays visible while new loads */}
      <Suspense fallback={<ProductsSkeleton />}>
        <Products category={category} />
      </Suspense>
    </div>
  )
}

Without startTransition: change → skeleton flash → new content.
With startTransition: change → old content stays (pending) → new content appears.

Common Mistakes

// ❌ ErrorBoundary inside Suspense — rejections bypass it
<Suspense fallback={<Skeleton />}>
  <ErrorBoundary fallback={<Error />}>  {/* wrong order */}

// ✅ ErrorBoundary outside Suspense
<ErrorBoundary fallback={<Error />}>
  <Suspense fallback={<Skeleton />}>

// ❌ No Suspense boundary around use()
function Page() {
  return <UserProfile userPromise={promise} />  // throws: no fallback specified

// ✅
function Page() {
  return (
    <Suspense fallback={<Skeleton />}>
      <UserProfile userPromise={promise} />
    </Suspense>
  )
}

Quick Reference

// use() for Promises
const data = use(dataPromise)

// use() for Context (works in conditions)
const theme = use(ThemeContext)

// Standard pattern
<Suspense fallback={<Loading />}>
  <AsyncComponent />
</Suspense>

// With error handling
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading />}>
    <AsyncComponent />
  </Suspense>
</ErrorBoundary>

// Avoid skeleton flash on navigation
startTransition(() => setState(newValue))

// Server Component
async function ServerComp() {
  const data = await fetchData()
  return <div>{data.title}</div>
}

Suspense and use() answer one question: "is this part of the UI ready to render?" If not, show the fallback. When it is, swap in the real content. The data layer plugs into this mechanism — the coordination logic stays in React.

Full article at stacknotice.com/blog/react-suspense-use-hook-2026

Next.js Environment Variables: The Complete Guide (2026)

Carlos Oliva Pascual — Mon, 29 Jun 2026 08:36:27 +0000

Environment variables in Next.js have more rules than most frameworks — and breaking them costs you either a runtime crash or a leaked secret. The NEXT_PUBLIC_ prefix, the .env file hierarchy, the build-time vs runtime distinction, the Docker baking problem — every one of these has caught developers in production.

The Two Environments: Build Time vs Runtime

The critical point: NEXT_PUBLIC_ variables are baked into the bundle at build time — they're not read from the environment at runtime. If you change them, you need to rebuild.

# NEXT_PUBLIC_ vars are embedded as string literals during `next build`
NEXT_PUBLIC_API_URL=https://api.myapp.com
# After build, the bundle literally contains: const apiUrl = "https://api.myapp.com"

Server-side variables (DATABASE_URL, API_SECRET) are read from the process environment at request time — no rebuild needed.

The .env File Hierarchy

.env                   # Shared defaults — committed to git
.env.local             # Local overrides — NEVER committed
.env.development       # Dev-specific — committed
.env.production        # Production defaults — committed

For most projects, you only need two:

# .env (committed — safe defaults)
DATABASE_URL=postgresql://localhost:5432/myapp
NEXT_PUBLIC_APP_NAME=MyApp

# .env.local (not committed — real secrets)
DATABASE_URL=postgresql://user:realpassword@prod-host:5432/myapp
NEXTAUTH_SECRET=your-real-secret-here

NEXT_PUBLIC_: The Client-Side Prefix

# Available in the browser
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
NEXT_PUBLIC_APP_URL=https://myapp.com

# Server-only (no prefix)
STRIPE_SECRET_KEY=sk_live_...
DATABASE_URL=postgresql://...

'use client'

// ❌ Returns undefined in the browser — no NEXT_PUBLIC_ prefix
const secret = process.env.MY_SECRET

// ✅ Works — prefixed and baked into the bundle
const appUrl = process.env.NEXT_PUBLIC_APP_URL

Type-Safe Env with t3-env

Raw process.env returns string | undefined for everything. t3-env validates at startup and gives you full TypeScript types:

npm install @t3-oss/env-nextjs zod

// env.ts
import { createEnv } from '@t3-oss/env-nextjs'
import { z } from 'zod'

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    NEXTAUTH_SECRET: z.string().min(32),
    STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  },
})

If a required variable is missing, the app throws at startup:

❌ Invalid environment variables:
  - DATABASE_URL: Invalid url
  - NEXTAUTH_SECRET: String must contain at least 32 character(s)

Use env.DATABASE_URL instead of process.env.DATABASE_URL everywhere — typed, validated, autocomplete works.

Manual Zod Validation (Without t3-env)

// lib/env.ts
import { z } from 'zod'

const serverSchema = z.object({
  DATABASE_URL: z.string().url(),
  NEXTAUTH_SECRET: z.string().min(32),
  NODE_ENV: z.enum(['development', 'test', 'production']),
})

export const serverEnv = serverSchema.parse(process.env)

Vercel Environment Variable Management

Vercel has three environments — Development, Preview, Production — each with separate values.

# Sync Vercel env vars to your local machine
vercel env pull .env.local

# Add a secret to production only
vercel env add DATABASE_URL production

# List all configured variables
vercel env ls

Set staging database URLs for Preview deployments so PRs don't hit production data:

vercel env add DATABASE_URL preview
# Enter your staging database URL

The Docker Build-Time Problem

NEXT_PUBLIC_ vars are baked in at build time. Passing them at docker run time is too late:

# ❌ Won't work — NEXT_PUBLIC_API_URL is already "" in the bundle
docker run -e NEXT_PUBLIC_API_URL=https://api.myapp.com myapp

Solution: build args

FROM node:20-alpine AS builder
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
COPY . .
RUN npm run build

docker build --build-arg NEXT_PUBLIC_API_URL=https://api.myapp.com -t myapp .

Common Mistakes

Destructuring process.env — Next.js can't statically analyze it:

// ❌ Doesn't work
const { NEXT_PUBLIC_API_URL } = process.env

// ✅
const apiUrl = process.env.NEXT_PUBLIC_API_URL

No validation — silent undefined in production:

// ❌ Fails silently
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

// ✅ Fails at startup with clear error
import { env } from '@/env'
const stripe = new Stripe(env.STRIPE_SECRET_KEY)

Quick Reference

# Pattern         | Browser | Server | Baked at build?
# NEXT_PUBLIC_X   | ✅      | ✅     | ✅ yes
# X (no prefix)   | ❌      | ✅     | ❌ read at runtime

# .env precedence (later overrides earlier)
.env → .env.local → .env.[mode] → .env.[mode].local

# Best practice
.env          # Committed — safe defaults
.env.local    # Not committed — real secrets

# Type-safe access
import { env } from '@/env'
env.DATABASE_URL  // validated + typed

# Vercel CLI
vercel env pull .env.local
vercel env add KEY production

The main rule: never put secrets in NEXT_PUBLIC_ (they end up in the browser bundle), never access server-only vars in Client Components (they return undefined), and always validate at startup.

Full article at stacknotice.com/blog/nextjs-env-variables-guide-2026

Next.js Dynamic Imports & Lazy Loading: The Complete Guide (2026)

Carlos Oliva Pascual — Fri, 26 Jun 2026 14:56:35 +0000

Every Next.js app has the same performance trap: you ship a heavy component that every user has to download, even when most users never interact with it. A rich text editor on an admin page. A chart library on a dashboard that half the users never open. A date picker that appears behind a modal.

Dynamic imports are the fix. They split these components into separate chunks that only load when needed. Less JavaScript on initial load, faster first paint, better Core Web Vitals.

This guide covers every dynamic import pattern in Next.js 15, when to use each, and how to measure the impact.

The Problem: Bundle Size

A Next.js page has two phases: the initial HTML from the server and the JavaScript bundle the browser has to parse and execute. The larger that bundle, the longer the Time to Interactive.

A single heavy library can add hundreds of kilobytes. Common offenders:

Chart libraries (Recharts, Chart.js, Victory) — 200–400KB each
Rich text editors (TipTap, Slate, Quill) — 300–600KB
Date pickers with locale data — 100–200KB
Map libraries (Leaflet, MapboxGL) — 300KB+
PDF renderers — 500KB+

If these are statically imported at the top of a file, every visitor downloads them on first load — including visitors who never see that component.

next/dynamic: The Next.js Approach

next/dynamic is Next.js's built-in wrapper around React.lazy with extra features for SSR control.

import dynamic from 'next/dynamic'

// Static import — included in main bundle
// import { HeavyChart } from '@/components/heavy-chart'

// Dynamic import — loaded only when rendered
const HeavyChart = dynamic(() => import('@/components/heavy-chart'), {
  loading: () => <div className="h-64 animate-pulse bg-muted rounded-lg" />,
})

export default function DashboardPage() {
  return (
    <main>
      <h1>Dashboard</h1>
      <HeavyChart data={data} />
    </main>
  )
}

When Next.js builds this page, HeavyChart is split into a separate JavaScript chunk. The browser only fetches that chunk when DashboardPage renders and HeavyChart is actually in the tree.

The loading prop

The loading prop renders while the chunk is fetching. Design it to match the real component's dimensions to avoid layout shift:

const RevenueChart = dynamic(() => import('@/components/revenue-chart'), {
  loading: () => (
    <div className="flex h-64 items-center justify-center rounded-lg border bg-muted/30">
      <div className="flex flex-col items-center gap-2 text-muted-foreground">
        <div className="h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
        <span className="text-sm">Loading chart...</span>
      </div>
    </div>
  ),
})

ssr: false — Client-Only Components

Some components can't render on the server at all: they use window, document, browser APIs, or libraries that aren't SSR-compatible.

Without ssr: false, these cause hydration errors or server-side exceptions. With it, Next.js skips server rendering entirely and renders only on the client:

// ❌ Breaks on the server — window is not defined
import { Map } from '@/components/map'

// ✅ Server renders nothing, client loads and renders normally
const Map = dynamic(() => import('@/components/map'), {
  ssr: false,
  loading: () => <div className="h-64 bg-muted rounded-lg" />,
})

Common use cases for ssr: false:

// Rich text editor
const RichTextEditor = dynamic(() => import('@/components/rich-text-editor'), {
  ssr: false,
  loading: () => <div className="h-48 animate-pulse bg-muted rounded-lg" />,
})

// Interactive map
const InteractiveMap = dynamic(() => import('@/components/map'), {
  ssr: false,
  loading: () => <div className="h-96 bg-muted rounded-lg" />,
})

// QR code generator (uses Canvas API)
const QRGenerator = dynamic(() => import('@/components/qr-generator'), {
  ssr: false,
})

Note: When you use ssr: false, the component is excluded from the server-rendered HTML entirely. The loading placeholder is what users with slow connections or JS disabled will see. Make sure it communicates something meaningful, not just a blank space.

Dynamic Imports with Named Exports

import() returns the default export. For named exports, map them in the promise:

// Named export: export function BarChart() { ... }
const BarChart = dynamic(
  () => import('@/components/charts').then((mod) => mod.BarChart),
  { loading: () => <ChartSkeleton /> }
)

// Or use a re-export file
// lib/dynamic-charts.ts
export const DynamicBarChart = dynamic(
  () => import('@/components/charts').then((mod) => mod.BarChart),
  { ssr: false }
)

next/dynamic vs React.lazy

Both lazy-load components, but they're different tools:

	`next/dynamic`	`React.lazy`
SSR control	`ssr: false` option	No SSR support
Loading state	`loading` prop	Requires `<Suspense>`
Works in Server Components	No (use in Client Components)	No
Named exports	`.then((mod) => mod.Export)`	Same pattern
Next.js integration	Yes — chunk naming, preloading	Partial

In the Next.js App Router, both work in Client Components. next/dynamic is more ergonomic for Next.js-specific patterns (especially ssr: false). React.lazy is fine for pure React component lazy loading where you don't need SSR control.

// React.lazy — fine for App Router Client Components
'use client'

import { lazy, Suspense } from 'react'

const HeavyComponent = lazy(() => import('@/components/heavy-component'))

export function Section() {
  return (
    <Suspense fallback={<div className="h-32 animate-pulse bg-muted rounded" />}>
      <HeavyComponent />
    </Suspense>
  )
}

Conditional Loading: Load Only When Needed

The biggest win is loading components only when the user actually needs them:

'use client'

import { useState } from 'react'
import dynamic from 'next/dynamic'

const PDFViewer = dynamic(() => import('@/components/pdf-viewer'), {
  ssr: false,
  loading: () => <div className="h-96 animate-pulse bg-muted rounded" />,
})

export function DocumentCard({ url }: { url: string }) {
  const [showPreview, setShowPreview] = useState(false)

  return (
    <div>
      <button onClick={() => setShowPreview(true)}>
        Preview document
      </button>

      {/* PDFViewer chunk only downloads when the user clicks */}
      {showPreview && <PDFViewer url={url} />}
    </div>
  )
}

The PDF viewer library — often 500KB+ — doesn't download until the user explicitly requests a preview.

Dynamic Imports for Heavy Libraries

When the heavy thing is a library rather than a component, use the dynamic import() function directly:

'use client'

import { useState } from 'react'

export function ExportButton({ data }: { data: unknown[] }) {
  const [isExporting, setIsExporting] = useState(false)

  async function handleExport() {
    setIsExporting(true)

    // xlsx only loads when the user clicks Export
    const { utils, writeFile } = await import('xlsx')

    const ws = utils.json_to_sheet(data)
    const wb = utils.book_new()
    utils.book_append_sheet(wb, ws, 'Data')
    writeFile(wb, 'export.xlsx')

    setIsExporting(false)
  }

  return (
    <button onClick={handleExport} disabled={isExporting}>
      {isExporting ? 'Exporting...' : 'Export to Excel'}
    </button>
  )
}

Preloading: Anticipate Before the User Clicks

If you know the user is likely to trigger a dynamic import (hovering over a button, scrolling near a component), preload the chunk early:

import dynamic from 'next/dynamic'

const EditModal = dynamic(() => import('@/components/edit-modal'))

// Preload the chunk when the user hovers
function EditButton() {
  return (
    <button
      onMouseEnter={() => {
        // Starts fetching the chunk — by the time they click, it's ready
        import('@/components/edit-modal')
      }}
      onClick={() => setModalOpen(true)}
    >
      Edit
    </button>
  )
}

This pattern eliminates the loading flash for fast users: the chunk starts downloading on hover and is usually ready by the time they click.

What to Dynamically Import (and What Not To)

Good candidates for dynamic imports:

Heavy third-party libraries used conditionally (chart libraries, editors, PDF viewers)
Components behind user interaction (modals, drawers, expanded sections)
Components at the bottom of long pages (below the fold)
Admin/settings pages that regular users rarely visit
Anything with window or document access

Bad candidates for dynamic imports:

Core UI components used everywhere (buttons, inputs, layout)
Components needed for initial render (hero sections, navigation)
Small utilities where the dynamic import overhead outweighs the savings
Components used immediately on every page load

The test: if the user can complete their primary action on the page without ever rendering the component, it's a candidate for lazy loading.

Measuring the Impact

Bundle analyzer — see what's in your bundles before and after:

npm install --save-dev @next/bundle-analyzer

// next.config.ts
import withBundleAnalyzer from '@next/bundle-analyzer'

const config = withBundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

export default config

ANALYZE=true npm run build

Open the visualization and look for large modules in your initial bundle that could be deferred.

Quick Reference

// Basic dynamic import with loading state
const Component = dynamic(() => import('./component'), {
  loading: () => <Skeleton />,
})

// Client-only component
const BrowserComponent = dynamic(() => import('./browser-component'), {
  ssr: false,
  loading: () => <Placeholder />,
})

// Named export
const NamedExport = dynamic(
  () => import('./module').then((m) => m.NamedExport)
)

// Conditional render (most impactful pattern)
{isOpen && <DynamicModal />}

// Preload on hover
onMouseEnter={() => import('./component')}

// Dynamic library import in a function
const { default: heavyLib } = await import('heavy-lib')

The principle is the same throughout: defer downloading JavaScript until it's actually needed. The browser does less work on initial load, the user gets an interactive page sooner, and the code that most users never see doesn't cost them anything.

Full article at stacknotice.com/blog/nextjs-dynamic-imports-lazy-loading-2026

Claude Code for Documentation: Keep Docs in Sync with Your Code (2026)

Carlos Oliva Pascual — Thu, 25 Jun 2026 15:25:16 +0000

Documentation has a specific failure mode: written once, stale within weeks, actively misleading within months. Claude Code doesn't fix the cultural problem — it fixes the effort problem.

Start with an Audit

Before generating anything, get a picture of the current state:

Read through src/ and tell me:
1. Which exported functions have zero JSDoc/TSDoc
2. Which have outdated JSDoc (types that don't match the implementation)
3. Whether README.md accurately describes the current entry points
4. What's in the codebase that isn't mentioned in any documentation

Output as a plain list, one issue per line.

JSDoc/TSDoc Generation

Take any undocumented function:

export async function createInvite(
  workspaceId: string,
  email: string,
  role: 'admin' | 'member' | 'viewer',
  expiresInDays?: number
): Promise<{ token: string; expiresAt: Date; link: string }> {
  // ...
}

Prompt:

Read src/lib/invites.ts and add TSDoc to every exported function.
Format: summary → @param → @returns → @throws → @example
Do not change any implementation code. Only add the JSDoc blocks.

Claude's output:

/**
 * Creates a pending workspace invitation and returns a tokenized invite link.
 *
 * @param workspaceId - The workspace to invite the user into
 * @param email - Email address of the person being invited
 * @param role - Permission level granted when the invite is accepted
 * @param expiresInDays - Days until the invite expires (default: 7)
 * @returns Object containing the token, expiry date, and full invite URL
 * @throws {ConflictError} If a pending invite already exists for this email
 *
 * @example
 * const invite = await createInvite('ws_abc123', 'alice@example.com', 'member')
 * // Send invite.link via email
 */
export async function createInvite(/* ... same implementation */)

Batch JSDoc for an entire directory

for file in src/lib/*.ts; do
  echo "Documenting $file..."
  cat "$file" | claude -p \
    "Add TSDoc to every exported function and type. Do not change implementation.
     Output the complete file with documentation added." \
    --output-format text > "$file.tmp" && mv "$file.tmp" "$file"
done

Always review after — Claude occasionally misinterprets ambiguous parameter names.

README Generation

Read the entire project — package.json, src/, .env.example, and any existing README.md.

Generate a README.md with:
1. What this project does (from the code's actual behavior)
2. Prerequisites (Node version, required env vars from .env.example)
3. Setup (exact commands)
4. Running locally (from package.json scripts)
5. Project structure (top-level only)
6. Environment variables (table: name, required/optional, description, example)
7. Deployment (only if Dockerfile or CI config exists)

Be accurate. If unsure about something, say so rather than guessing.

Key instruction: "accurate, not complete." A README that says "I'm not sure about the deployment step" is better than one that confidently describes the wrong process.

Pre-push hook: README staleness check

#!/bin/bash
# .git/hooks/pre-push

CHANGED=$(git diff --name-only origin/main...HEAD -- src/)

if [ -n "$CHANGED" ]; then
  NEEDS_UPDATE=$(echo "$CHANGED" | claude -p \
    "These src files changed: $CHANGED
     Read README.md. Does it reference anything that might now be inaccurate?
     Answer: YES or NO and one sentence." \
    --output-format text)

  if echo "$NEEDS_UPDATE" | grep -q "^YES"; then
    echo "⚠️  README may need updating: $NEEDS_UPDATE"
    exit 1
  fi
fi

This asks you to verify, not auto-update. Auto-updating docs without review produces confidently wrong docs.

Architectural Decision Records (ADRs)

ADRs document why a decision was made. Most valuable, least likely to be written.

We just decided: Use Drizzle ORM instead of Prisma for all new queries.

Write an ADR in this format:
# ADR-[number]: [Short title]
Date: [today]
Status: Accepted

## Context
## Decision
## Consequences (Positive / Negative / Risks)
## Alternatives Considered

Generate a draft from git history:

DIFF=$(git show "abc123")

claude -p "This commit made significant architectural changes:
$DIFF
Write a draft ADR explaining the problem it solves, decision made, and trade-offs." \
  --output-format text > docs/decisions/draft-adr-$(date +%Y%m%d).md

PostToolUse Hook: Remind on Implementation Changes

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const f = process.env.TOOL_INPUT_FILE || ''; if (f.includes('/src/') && !f.includes('.test.') && !f.includes('.md')) { console.log('📝 Check if JSDoc and README need updating for ' + f); }\""
          }
        ]
      }
    ]
  }
}

Every time Claude edits a source file, this reminder appears in context.

CLAUDE.md Documentation Rules

## Documentation rules

### When adding or changing a function:
- Add/update TSDoc on every exported function you touch
- Format: summary → @param → @returns → @throws (if applicable) → @example
- Skip private/internal functions unless non-obvious

### When the change affects:
- Environment variables → update .env.example and README env table
- CLI commands → update README setup section
- New dependencies → add to README prerequisites if they need setup

### Don't document:
- Implementation details obvious from the code
- Internal state variables
- Test setup functions

Keeping Docs Current

Periodically run:

Read docs/ and compare against the current src/.
List documentation that references code, APIs, or behaviors
that no longer exist or have changed significantly.

This surfaces outdated docs faster than a human review.

The rule of minimum viable docs: only document what changes frequently or isn't obvious from the code. Over-documented code creates maintenance overhead without proportional value.

Full article at stacknotice.com/blog/claude-code-documentation-2026

React Context vs Zustand: When Context Is Enough (and When It Isn't) (2026)

Carlos Oliva Pascual — Thu, 25 Jun 2026 14:11:44 +0000

The most common mistake with React state management isn't reaching for Zustand too early — it's reaching for Context incorrectly, then blaming Context for problems that come from misusing it.

The Re-Render Problem

Every component that calls useContext(SomeContext) re-renders whenever the context value changes — even if the part that changed is irrelevant to it.

interface AppState {
  user: User | null
  sidebarOpen: boolean
  notifications: Notification[]
}

const AppContext = createContext<AppState>(/* ... */)

function Navbar() {
  const { user } = useContext(AppContext) // subscribes to EVERYTHING
  return <nav>{user?.name}</nav>
}

When notifications updates every 30 seconds, Navbar re-renders even though it only cares about user. This is the source of most Context performance complaints.

The Actual Fix: Split the Context

One large context object is the problem. Split by update frequency:

const UserContext = createContext<User | null>(null)
const UIContext = createContext<{ sidebarOpen: boolean; toggleSidebar: () => void }>(/* ... */)
const NotificationContext = createContext<Notification[]>([])

function Navbar() {
  const user = useContext(UserContext) // only re-renders when user changes
  return <nav>{user?.name}</nav>
}

Most Context performance problems are solved by this split alone — no library needed.

When Context Is the Right Choice

Context excels for values that are stable and needed widely:

// Theme — changes once per session at most
const ThemeContext = createContext<ThemeContextValue | null>(null)

// Auth user — changes on sign in / sign out
const AuthContext = createContext<AuthContextValue | null>(null)

// Locale — changes when user switches language
const LocaleContext = createContext<LocaleContextValue | null>(null)

The common thread: stable values that don't update frequently.

Context also works well for SSR — Zustand is client-side only, but Context is readable in Server Components if you avoid state that requires useState.

When Zustand Fixes the Actual Problem

Zustand's core advantage: components subscribe to specific slices, not the whole store.

import { create } from 'zustand'

const useAppStore = create<AppStore>((set) => ({
  user: null,
  sidebarOpen: false,
  notifications: [],
  setUser: (user) => set({ user }),
  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
  addNotification: (n) => set((s) => ({ notifications: [...s.notifications, n] })),
}))

function Navbar() {
  // Only re-renders when user changes — ignores sidebarOpen and notifications
  const user = useAppStore((s) => s.user)
  return <nav>{user?.name}</nav>
}

function Sidebar() {
  // Only re-renders when sidebarOpen changes
  const { sidebarOpen, toggleSidebar } = useAppStore((s) => ({
    sidebarOpen: s.sidebarOpen,
    toggleSidebar: s.toggleSidebar,
  }))
  return <aside className={sidebarOpen ? 'w-64' : 'w-0'}>...</aside>
}

function NotificationBell() {
  // Notifications updating 30x/day doesn't touch Navbar or Sidebar
  const count = useAppStore((s) => s.notifications.length)
  return <span>{count}</span>
}

Selector-based subscription is what Context fundamentally can't do without extra infrastructure.

Combining Both (Real Production Setup)

They're not mutually exclusive:

// Context: auth and theme — stable, available server-side
const AuthContext = createContext<AuthContextValue | null>(null)
const ThemeContext = createContext<ThemeContextValue | null>(null)

// Zustand: client-side app state — complex, selective subscriptions
const useUIStore = create<UIStore>(/* ... */)
const useDataStore = create<DataStore>(/* ... */)

Use Context for values that are stable and available at render time. Use Zustand for values that change frequently and need selective subscriptions.

The Decision Framework

New state?
│
├─ Stable? (theme, auth, locale) → React Context
├─ SSR/RSC readable? → React Context
├─ Simple prop drilling? → React Context (split contexts)
│
├─ Changes frequently? → Zustand
├─ Components need different slices? → Zustand
├─ Complex logic (derived, middleware)? → Zustand
│
└─ Fetched from an API? → TanStack Query (not Context or Zustand)

That last point matters: server state (API data) is a different category. Neither Context nor Zustand handles caching, background refetching, or stale-while-revalidate correctly. TanStack Query does.

Common Mistakes

Putting everything in one context object — the split is the fix.

Using Zustand for stable values — overkill, and adds client-only constraints.

Using Context for frequently-changing values — causes unnecessary re-renders across the tree.

Using Zustand for server state — that's TanStack Query's job.

Full article at stacknotice.com/blog/react-context-vs-zustand-2026

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