Software Frontend

Frontend Engineering

Production-ready patterns for modern web applications.

Modern Best Practices (January 2026): Next.js 16 + Turbopack, React 19.x + Server Components, TypeScript 5.9+ (strict), Tailwind CSS v4, TanStack Query, Zustand, Vitest (browser mode).

Breaking Changes: Next.js 16 Upgrade Guide

Shared release gates: ../software-clean-code-standard/assets/checklists/frontend-performance-a11y-checklist.md

If you use React Server Components (RSC), treat security advisories as blocking: see data/sources.json (React RSC advisories).

Quick Reference

Workflow

1. Pick a framework using the decision tree.
2. Start from a matching template in assets/.
3. Implement feature-specific patterns from references/.
4. Treat accessibility and performance as release gates (shared checklist above).

Framework Decision Tree

Project needs:
|-- React ecosystem?
|   |-- Full-stack + SEO -> Next.js 16
|   |-- Progressive enhancement -> Remix
|   `-- Client-side SPA -> Vite + React
|
|-- Vue ecosystem?
|   |-- Full-stack -> Nuxt 4
|   `-- SPA -> Vite + Vue 3.5+
|
|-- State management?
|   |-- Server data -> TanStack Query
|   |-- Global client -> Zustand
|   `-- WARNING: DECLINING: Redux
|
`-- Styling?
    |-- Utility-first -> Tailwind CSS v4
    `-- WARNING: DECLINING: CSS-in-JS

Next.js 16 Changes

middleware.ts -> proxy.ts

# Run codemod
npx @next/codemod@canary upgrade latest

# Or manually rename
mv middleware.ts proxy.ts

// After (Next.js 16)
export function proxy(request: Request) {
  // ... logic
}

Cache Components ("use cache")

export default async function Page() {
  "use cache";
  const data = await fetchData();
  return <ProductList data={data} />;
}

React Compiler

// next.config.ts
const nextConfig: NextConfig = {
  experimental: {
    reactCompiler: true,
  },
};

Performance Budgets

Deployment Checklist

Pre-Deployment

• npm run build - no errors
• npm run lint - zero ESLint errors
• vitest run - all tests passing
• Bundle size within budget
• Environment variables set

Accessibility

• axe DevTools - zero critical issues
• Keyboard navigation works
• Color contrast >= 4.5:1
• Screen reader tested

SEO

• Metadata configured
• sitemap.xml generated
• robots.txt configured

Resources

Templates

Related Skills

React 19 + Frontend Ops Addendum (Feb 2026)

Frequent Lint/Type Pitfalls (Operational)

Treat these as first-class fix targets during frontend work:

• react-hooks/set-state-in-effect
• react-hooks/purity
• react-hooks/rules-of-hooks
• react/no-unescaped-entities

Frontend Verification Order

1. Lint edited files only.
2. Type-check edited feature surface.
3. Run full project lint/type/build once before handoff.

Avoid repeated full builds while known local lint/type failures remain.

CLI Drift Guard (ESLint/Vitest)

Do not assume flags from older setups.

Use:

npx eslint --help
npx vitest --help

Then run commands compatible with the detected CLI mode.

Frontend Handoff Requirements

Include in final output:

• exact files changed,
• lint/type/build commands run,
• whether failures are new or baseline,
• one prevention note for any repeated class of issue.

Route Deletion Link Audit

After deleting or renaming any page/route/component file:

1. Grep the codebase for the old path/import (e.g., rg "from.*old-module", rg "href.*old-route").
2. Update or remove all references (imports, <Link> hrefs, redirects, sitemap entries).
3. Check navigation components, breadcrumbs, and cross-link cards for stale references.

Skipping this creates runtime 404s and broken imports that surface only in production.

Architecture Pre-Check Before New Infrastructure

Before adding new infrastructure (new context providers, new API routes, new state stores):

1. Search for existing patterns that already solve the problem (rg "createContext", rg "useQuery").
2. Prefer extending existing infrastructure over creating parallel systems.
3. If new infrastructure is truly needed, document why the existing pattern is insufficient.

Route Migration Checklist

When consolidating or restructuring routes (e.g., many pages → tabbed architecture):

1. Map all existing routes to their new destinations.
2. Add redirects for removed routes (Next.js redirects in config or middleware).
3. Update all internal <Link> components, router.push() calls, and shared navigation configs.
4. Update sitemap, robots.txt, and any SEO metadata referencing old routes.
5. Run a full-app link audit: rg "href=" --glob "*.tsx" to verify no stale paths remain.

React 19 + Next.js 16 Production Gotchas (Feb 2026)

Seven patterns learned from real production sessions.

1. Hydration Safety Pattern

In Next.js 16 + React 19 SSR, server components run in Node.js (UTC, no window) while client components hydrate in the browser. Every new Date(), localStorage, and browser API call is a potential mismatch.

// PASS: useState(null) + useEffect — server renders skeleton, client fills real value
const [moonPhase, setMoonPhase] = useState<string | null>(null);
useEffect(() => {
  setMoonPhase(calculateMoonPhase(new Date()));
}, []);
if (!moonPhase) return <Skeleton />;

// FAIL: useMemo with Date() — server (UTC midnight) !== client (user timezone)
const moonPhase = useMemo(() => calculateMoonPhase(new Date()), []);
// Causes React Error #418 (hydration mismatch), 53 occurrences in production

Rule: Use useState(null) + useEffect for ANY computation depending on:

• new Date() (timezone-dependent)
• localStorage / sessionStorage (not available on server)
• window.* properties (navigator, screen, location)
• Any browser-only API

2. Safe Storage Access (String Discriminator Pattern)

JavaScript evaluates function arguments BEFORE the function body executes. Passing localStorage to a safe wrapper defeats the try/catch:

// FAIL: localStorage is evaluated at the CALL SITE, before try/catch
function safeGet(storage: Storage, key: string) {
  try { return storage.getItem(key); } // too late — already threw
  catch { return null; }
}
safeGet(localStorage, 'theme'); // SecurityError in Firefox (cookies disabled)

// PASS: String discriminator — storage access inside try/catch
function safeGet(type: 'local' | 'session', key: string) {
  try {
    const storage = type === 'local' ? window.localStorage : window.sessionStorage;
    return storage.getItem(key);
  } catch { return null; }
}
safeGet('local', 'theme'); // Safe — never throws

3. React Three Fiber (R3F) Prop Spreading

Never rest-spread props onto R3F/Three.js elements. Unknown props corrupt Three.js internal state silently:

// FAIL: Spreads isHovered, color, etc. onto <mesh> — breaks click handlers
<mesh {...handlers} position={pos}>

// PASS: Destructure and pass only known R3F event props
const { onClick, onPointerOver, onPointerOut } = handlers;
<mesh position={pos}>

4. Defensive Response Parsing

Dev servers, CDNs, and proxies can return HTML error pages. Never call .json() without guards:

// FAIL: Throws SyntaxError when server returns HTML error page
const data = await response.json();

// PASS: Check response.ok + try/catch json()
if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}
let data;
try {
  data = await response.json();
} catch {
  throw new Error('Invalid JSON response — server may have returned an error page');
}

5. The Truthy || Fallback Trap

data.field || [] does NOT protect against truthy non-array objects:

// FAIL: { __gated: true, teaser: "..." } is truthy — passes through as "the array"
const items = data.transits || [];
items.sort(); // TypeError: items.sort is not a function

// PASS: Array.isArray() at system boundaries
const items = Array.isArray(data.transits) ? data.transits : [];

6. Turbopack + macOS File Descriptor Limit

macOS default ulimit (~256) is too low for Turbopack in large Next.js projects. Causes:

• EMFILE: too many open files errors
• build-manifest.json ENOENT panics
• Stale chunk loading failures in browser

Fix:

# Add to ~/.zshrc or ~/.bashrc
ulimit -n 10240

# Emergency recovery when .next is corrupted
# 1. Kill dev server
# 2. rm -rf .next
# 3. npm run dev

7. Procedural Generation over External Assets (WebGL)

For WebGL/Three.js visuals, procedural generation (GLSL shaders) is more robust than external texture files:

• No 404 errors from missing textures
• No sandbox/CORS issues
• No loading states or error cascades
• Zero external file dependencies
• Often more visually striking (simplex noise patterns)

Ops Runbook: SEO-Safe UI and Copy Refresh

Use this for redesigns, pricing-copy updates, and landing refreshes that must not break indexed routes.

Command Checklist

# 1) Verify route/link impact
rg -n "href=|router\.push\(|redirect\(" src app

# 2) Verify metadata/sitemap/robots touchpoints
rg -n "metadata|sitemap|robots|canonical|hreflang|alternates" src app

# 3) Sweep for stale phrases (pricing/trial/campaign copy)
rg -n "free trial|7-day|old-price|legacy-plan-name" src/messages src/components

# 4) Build to catch route/import regressions
npm run build

No-Regressions Rules

• Do not remove or rename indexed routes without explicit redirect mapping.
• Keep locale routes and metadata aligned; no mixed-language metadata.
• Update copy and analytics labels together when pricing language changes.
• Run link audit after deleting/renaming components used by navigation cards.