DEV Community: Krishna Adhikari

How we engineered a better Next.js theme library

Krishna Adhikari — Mon, 18 May 2026 10:49:37 +0000

How we engineered a better Next.js theme library

There are three serious theme libraries for Next.js and React in 2026:

next-themes by paco — the OG. ~3 million weekly downloads. Battle-tested but unmaintained for React 19.
@wrksz/themes by jakubwarkusz — a clean-slate rewrite from March 2026. ~10k weekly downloads. Aims to be a near drop-in replacement for next-themes with the bugs fixed.
@teispace/next-themes — what my team ships. ~3.5k weekly downloads. Same goal as @wrksz/themes, different engineering choices.

I spent the last week doing a code-level audit of all three. Not just reading READMEs and comparing feature tables, but cloning the repos, reading every source file, and writing failing tests against each. This post is what I found.

The short version: every one of these libraries has real bugs that ship to production. Most of them are subtle — they don't crash, they don't error in dev, they just make your app worse in ways your users notice and your monitoring doesn't catch. The kind of stuff where someone files a GitHub issue like "sometimes the page flashes dark for half a second on load" and the maintainer says "can't reproduce" and closes it.

That's the kind of bug I want to walk you through. With line numbers. From the real code.

I'll cover five specific issues, then explain the architectural choice underneath each one. If you only read one section, make it #3 (the XSS in the inline script), because if you've shipped a next-themes competitor, you probably have it too.

Why the inline anti-FOUC script is the heart of everything

Before the bugs, you need to understand the constraint. A theme library has exactly one hard job:

Apply the right theme to <html> before any pixels paint, even though the theme value lives in a cookie or localStorage that React doesn't read until after the document has streamed.

Every other feature — the React hook, the toggle button, the SSR helper — is decoration. If the inline script is wrong, the user sees a flash of the wrong theme on every page load, and no amount of clever React code fixes it.

The pattern every library uses is the same:

<head>
  <script>
    // ...read cookie or localStorage, compute theme, set class on <html>...
  </script>
</head>

The script runs synchronously, before the browser parses any body content, before React hydrates, before anything else happens. The whole library exists to generate that script correctly and to keep the React state in sync with what the script did.

Now the bugs.

Bug #1: `next-themes` and the React 19 inline script warning

If you upgrade next-themes to a React 19 project, you get this in your dev console:

Warning: A dangerouslySetInnerHTML was passed to a script element. This will trigger a Content Security Policy violation in development.

The root cause is in next-themes/src/index.tsx — the script is rendered as a literal <script dangerouslySetInnerHTML={{__html: ...}}> inside a React tree that hydrates on the client. React 19 tightened how it handles inline scripts during hydration because of an Edge-case bug where the script could re-execute. The library was never updated.

@wrksz/themes fixed this by using useServerInsertedHTML from next/navigation, which inserts the script as part of the SSR stream rather than as a hydrating React element:

// @wrksz/themes/src/providers/client-next-provider.tsx
useServerInsertedHTML(() => {
  if (inserted.current) return null;
  inserted.current = true;
  return (
    <script
      dangerouslySetInnerHTML={{ __html: getScript({...}) }}
      nonce={nonce}
    />
  );
});

Ours uses the same primitive, but with one extra prop: noScript. The default behavior is what you'd expect — the provider injects the script via useServerInsertedHTML. But there's a subtle problem with that placement: useServerInsertedHTML inserts at the next React flush boundary, which on streamed responses is usually inside <body>, after some pixels may have already painted.

So we also export a getThemeScript() helper from /server that lets you render the script directly in <head> of your root layout, then tell the provider to skip its own injection:

// app/layout.tsx
import { ThemeProvider } from '@teispace/next-themes';
import { getTheme, getThemeScript } from '@teispace/next-themes/server';

export default async function RootLayout({ children }) {
  const initialTheme = await getTheme();
  const themeScript = getThemeScript({ attribute: 'class', initialTheme });

  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: themeScript }} />
      </head>
      <body>
        <ThemeProvider attribute="class" initialTheme={initialTheme ?? undefined} noScript>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

This guarantees the inline script runs before the browser paints any body pixels, regardless of how Next.js streams the response. The library handles both placements; we just believe the head placement is strictly better when you can do it.

Bug #2: `__name(...)` wrappers crashing the inline script

This one is genuinely sneaky.

When you write a named function in TypeScript and compile with esbuild or swc with keepNames: true (the default in most setups), the compiler injects a wrapper like this:

function themeScript(storageKey, attribute, ...) { ... }
// becomes:
var themeScript = __name(function(storageKey, attribute, ...) { ... }, "themeScript");

__name is a runtime helper esbuild injects at the top of the bundle. It just sets Object.defineProperty(fn, 'name', { value: 'themeScript' }). Harmless — except if you take that function and call .toString() on it, you get back source like:

__name(function(storageKey, attribute, ...) { ... }, "themeScript")

Now __name is a bundle-local identifier. It doesn't exist on window. When you inject this string into an inline <script> tag, the browser sees ReferenceError: __name is not defined, the script throws, the theme is never applied, and your user sees the wrong-theme flash on every page load.

next-themes had this bug for months. So did @wrksz/themes — they have an explicit workaround in packages/themes/src/core/script.ts:145:

const fn = themeScript.toString().replace(/\s*__name\s*\([^)]*\)\s*;?\s*/g, "");

A regex that strips __name(...) calls from the serialized function source. It works today, but it's fragile by design: it only handles this exact wrapper pattern. If esbuild ever changes the wrapper format, or if swc starts emitting something different, or if the user has a custom Babel plugin that renames the helper — the script silently breaks again, and they ship FOUC to production.

Ours sidesteps the entire class of problem. From src/core/script.ts:55-67:

The script body is a raw string literal — NOT a serialized function. This is intentional: bundlers (esbuild, swc) inject __name(fn,"name") wrappers around named functions when keepNames is on, which crashes any deserialized function body that lacks a global __name. Storing the body as data means no bundler ever rewrites it.

The actual script is hand-written JavaScript stored as a const string. We pass the config in via a JSON object that's interpolated at serialization time. No Function.toString() anywhere in the codebase. No regex strip. The bundler treats it as opaque data and can never touch it.

Here's the cost: the script can't reference imported helpers, so it's a single ~100-line string with no type checking. We compensate with a dedicated test file (__tests__/script.test.ts) that compiles and executes the script in jsdom against every config permutation we care about.

The benefit: the entire class of "bundler ate my inline script" bugs is structurally impossible.

Bug #3: The XSS surface every theme library leaves open

This one made me sit up. I'd missed it on my first read.

Every theme library serializes user-controlled config into the inline script. The themeColor prop, the value map, the forcedTheme prop — any of these can be passed by your app code and end up inside the <script> tag as a JSON-stringified value.

Standard practice is JSON.stringify. But JSON.stringify does not escape sequences that would prematurely close an inline script tag. So if your app does this:

<ThemeProvider themeColor={{ light: userInputColor }}>

…and userInputColor somehow contains </script><script>alert(1)</script>, then the inline script serializes to:

<script>
  !function(){var c={"tc":{"light":"</script><script>alert(1)</script>"},...};
</script>

The browser doesn't know about JavaScript string semantics. It looks for </script> and terminates the tag on the first match. Everything after that becomes live HTML, including the injected <script>alert(1)</script> — and you've just shipped XSS via your theme prop.

@wrksz/themes has this surface open right now. Their core/script.ts:144-164 just JSON.stringifys each config value directly. There's no escaping. I tested it — pass a malicious themeColor and it pops.

This is the same class of bug as upstream next-themes issue #213, which was reported in 2022 and stayed open. The reporter understood the problem; the fix never landed.

Ours fixes it in src/core/script.ts:92-109:

function safeJson(value: unknown): string {
  return JSON.stringify(value)
    .replace(/</g, '\\u003c')        // prevents </script> breakout
    .replace(//g, '\\u2028')   // line separator: valid JSON, invalid JS
    .replace(//g, '\\u2029');  // paragraph separator: same
}

Three tiny escapes that prevent three real attack vectors:

< — every < becomes <, so </script> becomes </script>. The browser never sees a closing tag in the script body; the JS string content is unchanged.
/ — these are valid JSON whitespace but invalid in JS string literals. They'd crash the script at runtime. Escape them, and the runtime sees the same character it would have.

The escapes are semantically equivalent for legitimate input (the string the runtime produces is identical), so we lose nothing by being defensive.

We have a test for it. From __tests__/script.test.ts:240-258:

it('escapes </script> in user-supplied config (XSS via #213 surface)', () => {
  const evil = '</script><script>window.__pwn=1;</script>';
  const s = buildScript({
    forcedTheme: evil,
    themes: ['light', 'dark', evil],
    themeColor: { light: evil, dark: '#000' },
  });
  expect(s).not.toContain('</script>');
  expect(s).toContain('\\u003c/script>');
  runScript(s);
  expect((window as { __pwn?: unknown }).__pwn).toBeUndefined();
});

If you're shipping a theme library — any theme library that inlines user-controllable config into a <script> tag — go check your code right now. This bug is invisible until someone exploits it.

Bug #4: The disable-transition `<style>` that re-flickers on every set

This is the subtle one. Watch closely.

A theme library that swaps class="light" for class="dark" on <html> will trigger every CSS transition that touches a color, background, border, shadow — anything. If the user has transition: background-color 200ms on <body>, the whole page does a 200ms fade between themes. That's usually unwanted on the initial swap (people want the theme to just snap into place) but desired afterward (so the toggle feels smooth).

The pattern every library uses to suppress this is the same:

Inject <style>*{ transition: none !important; }</style> into <head>.
Swap the class.
Wait for the browser to flush the paint (requestAnimationFrame(() => requestAnimationFrame(...))).
Remove the style.

Look at how @wrksz/themes does it, in packages/themes/src/providers/client-provider.tsx:142-153:

if (disableTransitionOnChange) {
  const transitionValue =
    typeof disableTransitionOnChange === "string"
      ? disableTransitionOnChange
      : "none";
  const style = document.createElement("style");
  style.textContent = `*,*::before,*::after{transition:${transitionValue}!important}`;
  document.head.appendChild(style);
  requestAnimationFrame(() =>
    requestAnimationFrame(() => document.head.removeChild(style)),
  );
}

This runs in applyToDom, which is called from a useEffect that depends on the resolved theme. Every time the resolved theme changes — or every time React re-runs the effect for any other reason — it injects the style, paints, removes it.

The bug: it runs even when the theme didn't actually change. If you call setTheme('dark') when the theme is already 'dark', the effect re-fires, a <style> tag gets injected and removed, the browser does a layout flush, and the page flickers for one paint frame. Worst case: your component re-renders during a route transition while theme === 'dark', the effect fires, the user sees a 16ms flash for no reason.

This is the kind of bug that's invisible in dev (16ms is below the threshold of human perception) but accumulates. Across a session, your users feel a slightly less stable UI without being able to point at what.

Ours handles it in src/core/store.ts:147-183. The relevant lines:

const applied =
  value && value[next.resolvedTheme] != null ? value[next.resolvedTheme] : next.resolvedTheme;

// Compare against current DOM state so a no-op apply does not inject
// the disable-transition <style> needlessly. This is the silent flicker
// source — every re-apply was inserting + removing a style tag, even
// when the resolved theme had not changed.
const domUnchanged =
  previousApplied === applied && isAttributeAlreadyApplied(el, attribute, applied);

let restore: (() => void) | null = null;
if (!skipTransitionDisable && disableTransitionOnChange && !domUnchanged) {
  restore = disableTransition(...);
}

if (!domUnchanged) {
  applyAttribute(...);
}

Two checks: did the resolved theme produce the same DOM string as last time we applied? And does the DOM already match that string? If both, no-op. Don't inject the style, don't write to the DOM, don't trigger anything.

We have a test that pins this behavior in __tests__/store-transition.test.ts:

it('does not inject a disable-transition <style> when setTheme is a no-op', () => {
  const store = createStore({ ...defaults(), disableTransitionOnChange: true });
  store.mount();
  store.setTheme('dark');
  const beforeCount = document.head.querySelectorAll('style').length;
  store.setTheme('dark'); // identical theme
  store.setTheme('dark'); // and again
  expect(document.head.querySelectorAll('style').length).toBe(beforeCount);
  store.unmount();
});

If we ever regress, the test catches it.

Bug #5: The god-component provider

This isn't a runtime bug. It's an architectural one that becomes a maintenance bug.

@wrksz/themes has a 332-line ClientThemeProvider component (packages/themes/src/providers/client-provider.tsx). Inside that one component:

DOM apply logic (attribute setting, class toggling, color-scheme style)
All five storage backends (cookie / localStorage / sessionStorage / hybrid / none reads + writes)
System preference (prefers-color-scheme) subscription
storage event handler (for cross-tab sync)
pageshow event handler (for bfcache restore)
popstate event handler (for back/forward navigation)
Cookie serialization
Meta theme-color element creation and update
disableTransitionOnChange style injection

All wrapped in useEffect hooks, all conditional on overlapping deps, all in render-phase code where you can't unit-test any piece in isolation.

Their __tests__/client-provider.test.tsx is 622 lines because every behavior needs a full React render setup. Want to test that cookies are read on mount? Render the provider. Want to test that the storage event fires? Render the provider. Want to verify the theme-color meta tag updates? Render the provider.

The core store is 59 lines (packages/themes/src/core/store.ts):

export function createThemeStore(): ThemeStore {
  let state: ThemeState = { theme: undefined, systemTheme: undefined };
  const listeners = new Set<() => void>();
  function emit(): void { for (const listener of listeners) listener(); }
  function setState(nextState: ThemeState): void { ... }
  return { subscribe, getSnapshot, getServerSnapshot, setState, setTheme, setSystemTheme };
}

That's the entire store. Just a state holder. All the actual work happens in the provider.

Ours splits it differently. The store (src/core/store.ts) is 362 lines and owns:

State and lifecycle (mount() / unmount() are public methods)
DOM apply with no-op short-circuit
View Transitions API integration
System + storage + pageshow subscriptions
Runtime-mutable props via update()

The provider component (src/providers/client.tsx, 142 lines) is essentially:

export function ClientThemeProvider(props) {
  const storeRef = useRef(/* ... */);
  if (!storeRef.current) storeRef.current = createStore(buildOptions(props));
  const store = storeRef.current;

  const state = useSyncExternalStore(store.subscribe, store.getState, getServerState);

  useEffect(() => { store.mount(); return () => store.unmount(); }, []);
  useEffect(() => { store.update(updatableProps(props)); }, [/* mutable props */]);

  return <Context.Provider value={...}>{children}</Context.Provider>;
}

The component is presentational. All the actual logic lives in the store, which is plain TypeScript and can be unit-tested without React.

Our test files reflect this. We have separate test files for store.test.ts, dom.test.ts, resolve.test.ts, view-transition.test.ts, adapters.test.ts, script.test.ts, etc. Each one covers a single concern. The provider test is small because the provider is small.

This isn't theory — it's why we caught the no-op transition bug in the first place. The store's apply function is callable in isolation, so we could write a direct test. In a god-component design, the same test requires a full React render, two effect cycles, and you might never notice the bug because it's hiding under the noise of normal rendering.

What we built that the others don't have

So far this post has been about bugs. Let me close with what's possible when you have a clean architecture.

Storage adapters as a public interface

In @wrksz/themes, storage is a closed string union: "localStorage" | "sessionStorage" | "cookie" | "hybrid" | "none". Want to read the theme from a Redis-backed cookie service? An OS API in Tauri? An IndexedDB store? You can't — fork the library.

Ours exposes the StorageAdapter interface directly:

export interface StorageAdapter {
  get(): string | null;
  set(value: string): void;
  subscribe?(listener: (value: string | null) => void): () => void;
}

// app/my-adapter.ts
export const tauriAdapter: AdapterFactory = () => ({
  get: () => window.__TAURI__.invoke('get_theme'),
  set: (v) => window.__TAURI__.invoke('set_theme', { theme: v }),
});

Pass it via storage="custom" and a customStorage adapter prop. The store doesn't care where the bytes come from.

View Transitions API integration

document.startViewTransition() is the browser's built-in animation API for cross-state DOM changes. It's perfect for theme swaps. None of the other libraries support it.

Ours has it in src/core/view-transition.ts. Two modes:

fade — a 200ms cross-fade between the old and new themes.
circular — a circular reveal originating from the click coordinates. The library tracks the user's last pointer event so the animation starts from the toggle button.

<ThemeProvider transition="circular">
  <App />
</ThemeProvider>

// or per-call:
setTheme('dark', { transition: 'circular' });

Respects prefers-reduced-motion. Falls back to a direct apply if the browser doesn't support the API.

`Sec-CH-Prefers-Color-Scheme` client hint

First-time visitors with no cookie still get a FOUC unless you can guess their preference server-side. Modern browsers will send a Sec-CH-Prefers-Color-Scheme: light|dark header on every request — but only after the server asks for it with Accept-CH.

We expose both halves:

// middleware.ts
import { acceptClientHintsHeader } from '@teispace/next-themes/server';

export function middleware() {
  const res = NextResponse.next();
  res.headers.set('Accept-CH', acceptClientHintsHeader());
  return res;
}

After the first navigation, subsequent requests include the hint, and getTheme() picks it up automatically. Zero-flash SSR even on first visit. None of the other libraries support this.

Sync `getTheme(Request)` for middleware

We shipped this last week, in v0.5.0. @wrksz/themes has had it; we did not. Now we both do:

// middleware.ts
import { getTheme } from '@teispace/next-themes/server';

export function middleware(request: NextRequest) {
  const theme = getTheme(request, { defaultTheme: 'dark' });
  // sync — no await, no next/headers
}

The dispatch is structural — it recognizes a Request by the combination of a Headers instance and a string url, so polyfilled and framework-specific Request subclasses work too.

Codemod from `next-themes`

If you're already on next-themes and want to migrate:

npx jscodeshift -t node_modules/@teispace/next-themes/codemod/from-next-themes.cjs src/

One command, all your imports rewritten. We use jscodeshift directly so the codemod ships as a .cjs file — no extra runtime, no setup.

Published with SLSA provenance

Every release of @teispace/next-themes is built and signed in GitHub Actions with npm provenance. The npm page shows a "Built and signed on GitHub Actions" badge linking back to the exact workflow run that built the tarball.

You can verify it yourself:

npm view @teispace/next-themes dist.attestations
# { url: '...', provenance: { predicateType: 'https://slsa.dev/provenance/v1' } }

next-themes and @wrksz/themes don't sign their releases yet. If you care about supply chain security — and you should — this is a real differentiator.

A fair tally

	`next-themes`	`@wrksz/themes`	`@teispace/next-themes`
React 19 inline script warning	❌	✅	✅
`__name` bundler-stripping bug	❌	✅ (regex workaround)	✅ (raw string, structurally immune)
XSS escaping in inline script	❌	❌	✅
No-op transition `<style>` injection	❌	❌	✅
Per-instance store (nested providers)	❌	✅	✅
Hybrid cookie + localStorage storage	❌	✅	✅
`sessionStorage` storage	❌	✅	✅
`Sec-CH-Prefers-Color-Scheme` hint	❌	❌	✅
View Transitions API	❌	❌	✅
Pluggable storage adapters	❌	❌	✅
Tailwind v4 preset	❌	❌	✅
Codemod from `next-themes`	—	❌	✅
Sync `getTheme(Request)` overload	❌	✅	✅
`createThemes()` typed factory	❌	✅	✅
`useServerInsertedHTML` script injection	❌	✅	✅
Published with SLSA provenance	❌	❌	✅

I tried to be honest where the others are ahead. @wrksz/themes ships a tighter bundle (77 KB vs our 242 KB) because they don't have view transitions, scoped themes, themed icons, the codemod, or the Tailwind preset. If you don't want those features, you save bytes. The runtime cost is roughly equivalent though — both libraries are tree-shakable, and importing only the parts you use gives you a similar working set.

They also have ~3× our weekly download count, which is real. Adoption matters; popular libraries get more eyes on bugs. We're new (April 2026) and they're slightly less new (March 2026); both of us are dwarfed by next-themes.

What I'd want you to take from this

If you're shipping anything that injects a <script> tag with user-controllable config, check your XSS escaping today. JSON.stringify is not enough. <, ,. Three escapes, ten seconds to add, prevents real exploits.

If you're using next-themes on React 19, you have at least three of the bugs in this post. Migrate. Either to ours or to @wrksz/themes — both are better than what you have.

If you're building a similar library, separate the store from the provider. The 332-line god component will catch up with you in six months. The 60-line store will not.

If you're choosing between ours and @wrksz/themes: read both READMEs, check both repos, pick the one whose architecture you trust more after looking at the code. I'm biased, obviously. But the answer is in the source, not in the marketing.

Try it

npm install @teispace/next-themes
# or
yarn add @teispace/next-themes
# or
pnpm add @teispace/next-themes

Repo: github.com/teispace/npm-packages/tree/main/packages/next-themes
npm: npmjs.com/package/@teispace/next-themes

Issues, PRs, and counter-examples welcome. If I got something wrong about @wrksz/themes or next-themes, file an issue and I'll correct it.

I Rebuilt My Next.js Starter From Scratch on Next 16 — Here's Every Decision I Made (and Why)

Krishna Adhikari — Mon, 18 May 2026 10:43:54 +0000

I Rebuilt My Next.js Starter From Scratch on Next 16 — Here's Every Decision I Made (and Why)

TL;DR — I rebuilt my Next.js starter on Next 16 + React 19 with one rule: every default should be the one I'd pick on day 90, not day 1. The result has dual HTTP clients (fetch + axios) on a shared foundation with a universal/server entry split, a typed Socket.IO layer with a hard SSR boundary, a per-request Redux store that hydrates from Server Components, zod-validated env that fails fast, Biome instead of ESLint + Prettier, and a 'use client' regression sentinel that fails the build if next/headers ever leaks into the client bundle. This article walks through every load-bearing decision and the trap each one avoids.

If you've been doing Next.js for a while, you know the feeling. You spin up create-next-app, and within a week you've added the same eight things you always add: a logger, env validation, an HTTP client that doesn't throw, a state store, i18n, a theme provider, secure storage, and a CI pipeline. Then the project ships, six months pass, and you discover the HTTP client silently broke when you moved a component to a Server Component. Or your env vars failed validation at runtime instead of at boot. Or your Redux store gave the same instance to two concurrent requests in SSR.

I rebuilt my starter from scratch on Next.js 16 with one goal: bake the day-90 defaults into day 1. This isn't a "10 must-have Next.js libraries" listicle. It's the design rationale for every load-bearing choice — and the specific trap each choice avoids.

The code is at github.com/teispace/nextjs-starter. The package lives at @teispace/next-themes for the theme story; the starter itself is a template. A separate CLI (@teispace/next-maker) scaffolds applications from it.

The "not the Next.js you know" preamble
Why Biome replaced ESLint + Prettier
Env validation: zod, cached, fail-fast
The HTTP layer: the hardest decision in the repo
The build-time tripwire that catches the bug you can't reproduce
Either + ApiException: errors as values
The WebSocket layer: same pattern, stricter rules
Per-request Redux store with SSR-safe persistence
i18n with next-intl: static rendering that actually works
Logger, secure storage, and the small things that compound
Quality gates: three Husky hooks, one CI workflow, a custom deprecated-API scanner
What I deliberately left out
Lessons that generalize beyond this starter

1. The "not the Next.js you know" preamble

The first line of the project's AGENTS.md is a warning:

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Two things changed in Next 16 that bite anyone whose mental model was set in 13/14/15:

middleware.ts is gone. It's proxy.ts now. Same idea — edge interception of requests — but the file name, the exported function name, and the matcher syntax all changed. If you blindly copy the middleware from your last project, the build silently won't pick it up.

// src/proxy.ts
import type { NextRequest } from 'next/server';
import createMiddleware from 'next-intl/middleware';

import { routing } from './i18n/routing';

export function proxy(request: NextRequest) {
  const handleI18nRouting = createMiddleware(routing);
  return handleI18nRouting(request);
}

export const config = {
  matcher: [
    '/((?!api|trpc|_next/static|_next/image|_vercel|favicon.ico|robots.txt|sitemap.xml|manifest.webmanifest|sw.js|opengraph-image\\.[^/]+|twitter-image\\.[^/]+|apple-icon\\.[^/]+|icon\\.[^/]+|.*\\.(?:js|css|map|json|svg|png|jpg|jpeg|gif|webp|avif|ico|woff|woff2|ttf|otf|eot|mp4|webm)).*)',
  ],
};

That matcher looks ugly because it has to be: it excludes API routes, Next internals, every public/static asset Next emits, and every common static extension. Get any of those wrong and you'll see the locale-routing middleware trying to handle requests for favicon.ico or og-image.png. Painful to debug, trivial to copy-paste.

React Compiler is on by default in the config. next.config.ts enables reactCompiler: true. Most code is unaffected; code that depended on referential stability of inline callbacks (e.g. memoization tricks that relied on the same function identity across renders) may behave differently. Worth knowing before you blame your useEffect.

2. Why Biome replaced ESLint + Prettier

This was the easiest call in the rebuild.

For years the standard React/Next.js stack has been ESLint + Prettier + prettier-plugin-tailwindcss + an import-sort plugin. Four configs to maintain, four versions to keep aligned, four sources of pre-commit slowness. Half the configuration work in any new project was getting them to stop fighting each other.

Biome replaces all of that with one binary. Lint, format, and import sort run in a single pass. The config is one file.

{
  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "jsxQuoteStyle": "double",
      "semicolons": "always",
      "trailingCommas": "all"
    }
  },
  "linter": {
    "domains": {
      "next": "recommended",
      "react": "recommended",
      "test": "recommended"
    },
    "rules": {
      "suspicious": {
        "noConsole": { "level": "error", "options": { "allow": ["warn", "error"] } }
      }
    }
  },
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              ["react", "react-dom", "react/**", "react-dom/**"],
              ":BLANK_LINE:",
              ["next", "next/**", "next-intl", "next-intl/**"],
              ":BLANK_LINE:",
              [":PACKAGE:", "!@/**"],
              ":BLANK_LINE:",
              ["@/**"],
              ":BLANK_LINE:",
              [":PATH:", "!**/*.css", "!**/*.scss"],
              ":BLANK_LINE:",
              ["**/*.css", "**/*.scss"]
            ]
          }
        }
      }
    }
  }
}

What I want to highlight is the organizeImports.groups block. This codifies a convention I used to enforce in code review and never quite got right: imports go in semantic groups separated by blank lines — React first, then Next/next-intl, then third-party packages, then @/* aliases, then relative paths, then CSS. The result is that every file in the codebase has the same import shape. New contributors don't have to learn it; the formatter just makes it true.

CI runs biome ci — a single command that checks lint + format + import sort in one pass. The whole quality gate took 4-6 seconds on this project; the old ESLint+Prettier setup on a comparable repo took 25-40s. The Husky pre-commit hook runs biome check --write via lint-staged on only the staged files. Pre-commit is fast enough that no one tries to skip it.

If you're still on ESLint + Prettier, the migration is genuinely a one-evening job and you'll wonder why you waited.

3. Env validation: zod, cached, fail-fast

The default Next.js story for environment variables is process.env.NEXT_PUBLIC_FOO. The typings say string | undefined. So every read is either a non-null assertion (which lies) or a runtime check (which propagates everywhere).

The starter inverts this. There's exactly one place env vars are read, and they're validated against a zod schema at module load.

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

export const emptyStringToUndefined = (value: unknown): unknown =>
  typeof value === 'string' && value.trim() === '' ? undefined : value;

export const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),

  NEXT_PUBLIC_API_URL: z
    .preprocess(emptyStringToUndefined, z.url().optional())
    .describe('Bare origin of the backing API. The /api/v{n} prefix is appended internally.'),

  NEXT_PUBLIC_APP_URL: z
    .preprocess(emptyStringToUndefined, z.url().default('http://localhost:3000')),

  DEFAULT_TIMEZONE: z
    .preprocess(emptyStringToUndefined, z.string().default('UTC')),

  DEFAULT_LOCALE: z
    .preprocess(emptyStringToUndefined, z.string().default('en')),
});

export type Env = z.infer<typeof envSchema>;

// src/lib/env/index.ts
let cached: Env | null = null;

function readRawEnv(): Record<string, unknown> {
  return {
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
    DEFAULT_TIMEZONE: process.env.DEFAULT_TIMEZONE,
    DEFAULT_LOCALE: process.env.DEFAULT_LOCALE,
  };
}

export const env: Env = (() => {
  if (!cached) cached = validateConfig(envSchema, readRawEnv(), 'environment variables');
  return cached;
})();

The trick is the emptyStringToUndefined preprocessor. .env files have a nasty quirk: FOO= parses as the empty string "", not undefined. If you write z.string().default('UTC'), the default fires only on undefined — the empty string sails through and breaks downstream. The preprocessor normalizes empty/whitespace-only strings to undefined so defaults work the way humans expect.

The shared validator throws with a formatted multi-bullet error:

// src/lib/env/validate.ts
export function validateConfig<T>(schema, config, label = 'environment variables'): T {
  const parsed = schema.safeParse(config);
  if (!parsed.success) {
    throw new Error(
      `Invalid ${label}:\n${formatIssues(parsed.error.issues)}\n\n` +
        `Fix .env (or the relevant source) and retry.`,
    );
  }
  return parsed.data;
}

What this gets you in practice: a misconfigured deploy fails on the very first request with a readable error listing every invalid field. No more "the page is blank and the console says Cannot read properties of undefined."

There's a small companion script (scripts/sync-env.ts) wired into the pre-commit hook. It reads your .env and writes a sanitized .env.example — preserving keys and structure but stripping values from non-public entries. Lines tagged with # -public keep their values; everything else is reduced to KEY=. The pre-commit hook runs yarn env:sync --check and fails if the two are out of sync, so contributors can't accidentally commit a secret to .env.example.

NEXT_PUBLIC_API_URL=
NEXT_PUBLIC_APP_URL=

DEFAULT_TIMEZONE=
DEFAULT_LOCALE=

PORT=3000 # -public

CONTAINER_NAME=next-app # -public
IMAGE_NAME=nextjs-starter # -public
IMAGE_TAG=latest # -public

The convention: when you add a new env var, you touch three places — schema.ts, readRawEnv() in index.ts, and .env.example. The pre-commit hook catches the third one if you forget.

4. The HTTP layer: the hardest decision in the repo

This is the piece I spent the most time on, broke twice, and finally got right on the third design. I'll spare you the dead ends and just describe the live design.

The contract

Every HTTP call returns ResultAsync<T> = Promise<Either<ApiException, T>> and never throws. Network errors, 5xx, 4xx, validation errors — everything lands on the left side of an Either. You destructure it at the call site:

import { fetchClient } from '@/lib/utils/http';

const result = await fetchClient.get<User>('/users/123');

if (result.isLeft()) {
  // result.value is an ApiException — typed
  return showError(result.value);
}

const user = result.value; // typed as User

Why "never throws"? Because every team I've worked on eventually ends up with try/catch boilerplate around every API call, and half of those try/catches leak (someone forgets one, the exception bubbles up to a generic error boundary, and you lose the field-level validation errors the API returned). Making the failure visible in the type signature forces the call site to deal with it — and once you've done that, the boilerplate disappears.

Two clients, same surface

The starter ships both a fetchClient and an axiosClient. Same method signatures, same return type, same options shape. Why both?

fetchClient is the default. Zero KB on top of the native Fetch API, works in the Edge runtime, RSC, Server Actions, Route Handlers, and the browser. This is what you should reach for first.
axiosClient is there for the cases where you actually need axios features — request cancellation tokens, advanced transforms, or just because a third-party SDK expects an axios interceptor. About 30 KB of bundle. Not available in the Edge runtime.

Both clients pass through the same shared/ foundation: the same request-ID generator, the same parseApiError pipeline, the same toSearchParams serializer. The point of having both is that you can mix runtimes without rewriting your call sites — and you can swap one for the other without changing anything except the import.

The universal/server split (this is the load-bearing bit)

Cookie-mode auth is the default: the server sets HttpOnly access and refresh cookies on login, and reads them back on every request. In the browser, the cookie jar handles it automatically when you set credentials: 'include'. In a Server Component, there is no cookie jar — you have to read the request cookies with next/headers and forward them explicitly.

So far so standard. Here's the trap.

next/headers is a server-only module. If you import it from a file that's reachable by the client bundle, Next.js fails the build with a clear error. Fine, you think — I'll guard the import behind a runtime check:

if (typeof window === 'undefined') {
  const { cookies } = await import('next/headers');
  // ...
}

This does not work. The bundler statically resolves the import graph. The dynamic import() still counts as a reference. Build fails. You discover this the first time you try to use a "shared" HTTP client from a 'use client' component.

The fix that actually works is to expose two entry points:

src/lib/utils/http/
├── shared/                ← Universal foundation
├── fetch-client/          ← Fetch adapter
├── axios-client/          ← Axios adapter
├── __bundle-sentinel__/   ← Build-time tripwire (more on this in §5)
├── client-utils.ts        ← TokenRefreshManager
├── token-store.ts         ← secureStorageTokenStore
├── index.ts               ← Universal entry: '@/lib/utils/http'
└── server.ts              ← Server-only entry: '@/lib/utils/http/server'

The universal entry never touches next/headers. Safe to import from anywhere — client components, Server Components, Edge, isomorphic utils.

The server entry imports next/headers and wires up a cookieResolver that reads the request cookies on every call:

// src/lib/utils/http/server.ts
import 'server-only';
import { cookies } from 'next/headers';
// ...

async function readServerCookieHeader(): Promise<string | undefined> {
  const all = (await cookies()).getAll();
  if (all.length === 0) return undefined;
  return all.map((c) => `${c.name}=${c.value}`).join('; ');
}

export const fetchClient = createFetchClient({
  tokenStore: secureStorageTokenStore,
  onUnauthorized: handleUnauthorizedRedirect,
  cache: 'no-store',
  cookieResolver: readServerCookieHeader,
});

The 'server-only' import at the top is the kill switch: if a 'use client' file ever imports from @/lib/utils/http/server, the build fails with a clear error from the server-only package. The split is the entire design — you can't get it wrong because the type system and the bundler both enforce it.

Call sites become trivially correct:

// app/[locale]/profile/page.tsx (Server Component)
import { fetchClient } from '@/lib/utils/http/server';

export default async function ProfilePage() {
  const result = await fetchClient.get<User>('/auth/me');  // cookies forwarded
  if (result.isLeft()) return <SignedOut />;
  return <Profile user={result.value} />;
}

// any client component
'use client';
import { fetchClient } from '@/lib/utils/http';

export function Profile() {
  // Browser cookie jar carries the session cookie automatically.
  const result = await fetchClient.get<User>('/auth/me');
  // ...
}

Token refresh that doesn't thunder-herd

Every team I've worked on has, at some point, accidentally built a token-refresh path that fires N concurrent refresh requests when N concurrent calls hit a 401 at the same time. Then the server's refresh-rate-limiter trips and everyone gets logged out.

The fix is a small debounced manager. While a refresh is in flight, subsequent 401s wait in a queue:

// src/lib/utils/http/client-utils.ts
export class TokenRefreshManager {
  private state = { isRefreshing: false, queue: [], attempts: 0, lastAttempt: 0 };

  async handleRefresh(refreshFn: () => Promise<string | null>): Promise<string | null> {
    if (this.state.isRefreshing) {
      return new Promise((resolve) => this.state.queue.push(resolve));
    }

    const now = Date.now();
    if (now - this.state.lastAttempt < TOKEN_REFRESH_CONFIG.COOLDOWN_MS) {
      this.state.attempts++;
      if (this.state.attempts >= TOKEN_REFRESH_CONFIG.MAX_ATTEMPTS) {
        logger.error('Max refresh attempts reached. Stopping to prevent infinite loop.');
        this.state.attempts = 0;
        return null;
      }
    } else {
      this.state.attempts = 0;
    }
    this.state.lastAttempt = now;
    this.state.isRefreshing = true;

    const drainQueue = (token: string | null) => {
      const waiters = this.state.queue;
      this.state.queue = [];
      for (const resolve of waiters) resolve(token);
    };

    try {
      const token = await refreshFn();
      drainQueue(token);
      return token;
    } catch (err) {
      logger.error({ err }, 'Unexpected error in token refresh');
      drainQueue(null);
      return null;
    } finally {
      this.state.isRefreshing = false;
    }
  }
}

MAX_ATTEMPTS = 3 within COOLDOWN_MS = 1000. Past that, the manager clears local state and calls onUnauthorized() — defaulted to redirect to /login?redirectTo=<current>. Both clients share the same manager class. Both pass it the same refreshAuthToken function. The behavior is identical regardless of which client made the original call.

X-Request-Id correlation, end-to-end

Every outgoing request gets stamped with a fresh UUID matching ^[A-Za-z0-9_-]{1,128}$. A well-behaved server-side correlation layer echoes client-supplied IDs that match the pattern, generates its own otherwise, and stamps every response with X-Request-Id (both as a header and as a requestId field in error envelopes).

The client reads the value, stashes it on ApiException.requestId, and your error handler can log it:

const result = await fetchClient.get('/users/123');
if (result.isLeft()) {
  logger.error({ requestId: result.value.requestId }, 'lookup failed');
  // Now grep browser logs AND server logs for the same requestId.
}

The five minutes you spend correlating a production incident pays this back the first time it happens.

Typed queries and pagination, built in

The starter ships base query types for both offset- and cursor-based pagination:

export interface BaseQueryParams {
  page?: number;
  size?: number;
  search?: string;
  sort?: string;
  order?: 'asc' | 'desc';
}

export interface BaseCursorQueryParams {
  cursor?: string;
  size?: number;
  search?: string;
  sort?: string;
  order?: 'asc' | 'desc';
}

You extend these per endpoint:

interface UsersQuery extends BaseQueryParams {
  status?: 'active' | 'invited' | 'disabled';
  roleId?: string;
}

await fetchClient.get<PaginatedApiResponse<User>>('/users', {
  params: { page: 2, size: 20, status: 'active' } satisfies UsersQuery,
});

The shared toSearchParams serializer skips undefined/null/'' so server defaults stay implicit, and repeats array values for ?tag=a&tag=b style queries. Both clients use the same serializer — query strings are byte-identical regardless of which one made the call. (Axios's default serializer is replaced for exactly this reason.)

5. The build-time tripwire that catches the bug you can't reproduce

Here's the regression I was most afraid of: someone, six months from now, refactors a util in the universal HTTP entry. They innocently import a helper that, three transitive imports later, lands on next/headers. The build still passes — because the helper was only added to a code path that isn't reached by the bundler today. Six weeks later, someone uses that code path from a 'use client' file and prod breaks.

I wanted a tripwire that fails the build the moment the import graph is contaminated, regardless of whether anyone is using the contaminated path yet.

That's the __bundle-sentinel__ file:

// src/lib/utils/http/__bundle-sentinel__/client-bundle-sentinel.tsx
'use client';

import {
  axiosClient,
  createAxiosClient,
  createFetchClient,
  fetchClient,
  toSearchParams,
} from '@/lib/utils/http';

const __sentinel__ = {
  axiosClient,
  createAxiosClient,
  createFetchClient,
  fetchClient,
  toSearchParams,
};

export function HttpClientBundleSentinel(): null {
  if (typeof window !== 'undefined') {
    (window as unknown as { __http_sentinel__: unknown }).__http_sentinel__ = __sentinel__;
  }
  return null;
}

Three properties hold this together:

The file is marked 'use client', so its entire transitive import graph must be valid for the client bundle.
It imports every public symbol from @/lib/utils/http. If any of them ever pull a server-only module into the client graph, the build fails immediately.
It's referenced from app/[locale]/layout.tsx, so the route tree pulls it into a real production build. Next.js prunes unreferenced files, so a dangling import wouldn't be a regression test.

The component renders null — its only purpose is to exist in the bundle graph. The window assignment exists so tree-shaking can't elide the import references.

It looks weird. It is weird. It's also the cheapest insurance I know how to write against a class of bugs that's expensive to debug in production. Don't delete it.

6. Either + ApiException: errors as values

The Either<L, R> type is a hand-rolled tagged union with Left and Right constructors:

export class Left<L> {
  readonly tag = 'left' as const;
  readonly value: L;

  isLeft(): this is Left<L> { return true; }
  isRight(): this is Right<never> { return false; }
  map<R>(_fn: (r: never) => R): Left<L> { return this; }
  mapLeft<NL>(fn: (l: L) => NL): Left<NL> { return Left.of(fn(this.value)); }
  fold<T>(onLeft: (l: L) => T, _onRight: (r: never) => T): T { return onLeft(this.value); }
}

export class Right<R> {
  readonly tag = 'right' as const;
  readonly value: R;

  isLeft(): this is Left<never> { return false; }
  isRight(): this is Right<R> { return true; }
  map<NR>(fn: (r: R) => NR): Right<NR> { return Right.of(fn(this.value)); }
  fold<T>(_onLeft: (l: never) => T, onRight: (r: R) => T): T { return onRight(this.value); }
}

export type Either<L, R> = Left<L> | Right<R>;

Three patterns at the call site, all valid:

const result = await fetchClient.get<User>('/users/123');

// 1. Guard + value
if (result.isLeft()) return handleError(result.value);
const user = result.value;

// 2. fold
const greeting = result.fold(
  (err) => `Error: ${err.message}`,
  (user) => `Hello, ${user.name}`,
);

// 3. isRight when you only care about the happy path
if (result.isRight()) setUser(result.value);

I went back and forth on whether to use a library (fp-ts, neverthrow, purify-ts). The reasons I landed on a hand-rolled version:

The starter is consumed by other projects via the @teispace/next-maker CLI. Every dep is a future "why do I have this in my bundle" question. A 70-line file with no transitive deps is easier to defend.
The surface I actually use is tiny: isLeft/isRight/value/map/mapLeft/fold. The libraries add a hundred other operators that are great for FP-curious teams and noise for everyone else.
It composes cleanly with ApiException, which is the only shape of error that ever lands on the left.

ApiException itself is opinionated. It exposes everything the API can plausibly send and adds form-friendly helpers:

export class ApiException extends Error {
  status: number;
  code?: string;
  errors?: Record<string, string>[];
  data?: Record<string, unknown>;
  path?: string;
  requestId?: string;

  containsKey(key: string): boolean { /* ... */ }
  getErrorMessage(key: string): string | undefined { /* ... */ }
  getErrorMessageIfExists(key: string): string { /* ... */ }
  getFieldErrors(): Record<string, string> { /* ... */ }
}

The one-liner for form validation is setFieldErrors(result.value.getFieldErrors()). That's the kind of API I want to write once and never think about again.

7. The WebSocket layer: same pattern, stricter rules

Real apps need WebSockets for at least three things: presence ("user X is online"), live updates ("a new message arrived"), and force-disconnect signals ("your session was revoked, sign out").

The WS layer mirrors the HTTP layer's design philosophy with one important difference: it throws on SSR misuse rather than silently no-op-ing.

// src/lib/utils/ws/shared/runtime.ts
export class WsSsrError extends Error {
  readonly code = WS_LOCAL_ERROR_CODES.SSR_BLOCKED;

  constructor(method: string) {
    super(
      `[ws] ${method}() was called in a server context. ` +
        `WebSocket clients run in the browser only. ` +
        `Move the call into a "use client" component, or guard it with typeof window !== 'undefined'.`,
    );
    this.name = 'WsSsrError';
  }
}

export function ensureBrowser(method: string): void {
  if (isServer()) throw new WsSsrError(method);
}

Opening a WebSocket from a Server Component is always a bug. Surfacing it immediately is far kinder than letting it reach production as "the socket mysteriously never connects."

Lazy connect, Proxy-backed singleton

The default wsClient is a Proxy that lazily constructs the underlying instance on the first method call:

let _wsClient: WsClient | null = null;

function getWsClient(): WsClient {
  if (!_wsClient) _wsClient = new WsClient();
  return _wsClient;
}

export const wsClient = new Proxy({} as WsClient, {
  get(_target, prop, receiver) {
    const client = getWsClient();
    const value = Reflect.get(client, prop, receiver);
    return typeof value === 'function' ? value.bind(client) : value;
  },
});

Why a Proxy? Because the WS module is sometimes imported by isomorphic files. With a normal singleton, instantiating at module load would trigger ensureBrowser() in places it shouldn't fire. The Proxy defers the instantiation until you actually call a method — by which time you're either in a 'use client' file or you've hit WsSsrError and you know exactly why.

The three hooks, and what lazy connect actually means

useWsStatus()           // reads connection state from Redux
useWsEvent(name, fn)    // subscribes to a server event; lazy-connects on first call
useWsEmit()             // returns a typed emit function

The contract that makes this nice: feature code never calls wsClient.connect() explicitly. The first useWsEvent mount in the entire app triggers the connection. No subscribers means no socket — the transport doesn't open at module load just because you imported the module.

'use client';
import { useEffect } from 'react';
import { useWsEvent, useWsEmit, useWsStatus } from '@/lib/utils/ws';

export function PresenceWidget({ userId }: { userId: string }) {
  const { isConnected } = useWsStatus();
  const emit = useWsEmit();

  useEffect(() => {
    if (!isConnected) return;
    emit('presence:subscribe', { userId });
    return () => { emit('presence:unsubscribe', { userId }); };
  }, [isConnected, userId, emit]);

  useWsEvent('presence:online', ({ userId: uid }) => {
    if (uid === userId) console.log(`${userId} is online`);
  });

  return <span>{isConnected ? '🟢' : '⚪'}</span>;
}

Typed events via declaration merging

ClientToServerEvents and ServerToClientEvents are the contract:

export interface ClientToServerEvents {
  ping: (ack?: () => void) => void;
  'auth:token:renew': (
    payload: { refreshToken: string },
    ack?: (result: { success: boolean; error?: WsErrorPayload }) => void,
  ) => void;
  'presence:subscribe': (payload: { userId: string }) => void;
  'presence:unsubscribe': (payload: { userId: string }) => void;
}

export interface ServerToClientEvents {
  pong: (payload: WsPongPayload) => void;
  error: (payload: WsErrorPayload) => void;
  'auth:error': (payload: WsErrorPayload) => void;
  'auth:token:renewed': (payload: WsTokenRenewedPayload) => void;
  'auth:force:disconnect': (payload: WsForceDisconnectPayload) => void;
  'presence:online': (payload: WsPresencePayload) => void;
  'presence:offline': (payload: WsPresencePayload) => void;
  'presence:status': (payload: WsPresenceStatusPayload) => void;
}

Features extend them via TypeScript declaration merging:

// src/features/chat/types/ws-events.ts
import '@/lib/utils/ws';

declare module '@/lib/utils/ws' {
  interface ClientToServerEvents {
    'message:send': (payload: { roomId: string; content: string }) => void;
  }
  interface ServerToClientEvents {
    'message:new': (payload: {
      id: string;
      roomId: string;
      authorId: string;
      content: string;
      createdAt: string;
    }) => void;
  }
}

After that, emit('message:send', { roomId, content }) and useWsEvent('message:new', (msg) => ...) are both fully typed at the call site. No casts, no any.

`auth:force:disconnect` — branch on `reconnectable`, not `reason`

This is a contract I've seen teams get wrong twice. The server can disconnect a socket for many reasons (session revoked, max connections, rate limited, server shutting down, roles changed, max age). Some of those should auto-reconnect; some should not. The client must always branch on the reconnectable: boolean flag, never on the reason string.

const WS_DISCONNECT_REASON = {
  SESSION_REVOKED: 'session_revoked',     // reconnectable: false
  MAX_CONNECTIONS: 'max_connections',     // reconnectable: false
  RATE_LIMITED: 'rate_limited',           // reconnectable: false
  ROLES_CHANGED: 'roles_changed',         // reconnectable: true
  SERVER_SHUTDOWN: 'server_shutdown',     // reconnectable: true
  MAX_AGE: 'max_age',                     // reconnectable: true
} as const;

The reason is for logs and UX ("you were signed out because…"). The boolean is the contract: if it's false, the client sets a fatalDisconnect latch and disables reconnection on the underlying Manager. Reasons can be added or renamed server-side without coordinating a client release; the boolean is what your code branches on.

State flows through Redux, but only via the bridge

The wsClient has a typed lifecycle emitter (statusChange, error, forceDisconnect, socketIdChange, pong). attachWsBridge subscribes to those and dispatches into the ws Redux slice. The bridge is the only code path that ever dispatches WS slice actions. Feature code reads via selectors and never dispatches into this slice directly.

// src/lib/utils/ws/redux/bridge.ts
export function attachWsBridge(client: WsClient, dispatch: AppDispatch): () => void {
  const offStatus = client.on('statusChange', (status, socketId) => {
    dispatch(wsStatusChanged({ status, socketId }));
  });
  const offError = client.on('error', (payload) => dispatch(wsErrored(payload)));
  const offForce = client.on('forceDisconnect', ({ reason, reconnectable }) => {
    dispatch(wsForceDisconnected({ reason, reconnectable }));
  });
  // ...
  return () => { offStatus(); offError(); offForce(); /* ... */ };
}

The bridge is mounted once, from StoreProvider:

useEffect(() => {
  const store = storeRef.current;
  if (!store) return;
  return attachWsBridge(wsClient, store.dispatch);
}, []);

And critically — the ws slice is intentionally NOT wrapped in persistReducer:

// src/store/rootReducer.ts
export const rootReducer = combineReducers({
  count: persistReducer(countPersistConfig, countReducer),
  ws: wsReducer, // ephemeral — connection state across reloads is meaningless
});

Persisting "connected: true" would lie about the actual transport on first paint. The bridge dispatches the real status as soon as the WS client mounts. Don't add it to persistence.

8. Per-request Redux store with SSR-safe persistence

The default Redux setup tutorials configure the store at module top-level:

// DON'T do this in SSR
export const store = configureStore({ reducer });

This works for a SPA. It breaks for SSR: two concurrent requests share the same store instance, and one request's state can leak into another's render. You also can't pre-populate the store from a Server Component because the store was built at boot, before any request existed.

The fix is a fresh store per request, built inside the provider with useRef:

// src/providers/StoreProvider.tsx
'use client';
import { useEffect, useRef } from 'react';
import { Provider } from 'react-redux';
import type { Persistor } from 'redux-persist';
import { PersistGate } from 'redux-persist/integration/react';
import { attachWsBridge, wsClient } from '@/lib/utils/ws';
import { type AppState, type AppStore, makeStore } from '@/store';
import { createPersistor } from '@/store/persistor';

type StoreProviderProps = {
  children: React.ReactNode;
  preloadedState?: Partial<AppState>;
};

export const StoreProvider = ({ children, preloadedState }: StoreProviderProps) => {
  const storeRef = useRef<AppStore | null>(null);
  const persistorRef = useRef<Persistor | null>(null);

  if (!storeRef.current) {
    storeRef.current = makeStore(preloadedState);
    persistorRef.current = createPersistor(storeRef.current);
  }

  useEffect(() => {
    const store = storeRef.current;
    if (!store) return;
    return attachWsBridge(wsClient, store.dispatch);
  }, []);

  return (
    <Provider store={storeRef.current}>
      <PersistGate persistor={persistorRef.current as Persistor} loading={children}>
        {children}
      </PersistGate>
    </Provider>
  );
};

Three things to notice:

useRef instead of useState. useState's lazy initializer would also work, but useRef is the convention for "make this once per mount, stable forever."
makeStore(preloadedState) accepts an initial slice. A Server Component can fetch user/session data and pass it down to the store via RootProvider. The client store starts with that data already in place — no hydration round-trip, no loading flicker.
PersistGate with loading={children} instead of loading={<Spinner />}. This is a non-blocking SSR pattern: the children render immediately with the in-memory state, and rehydrated state lands as soon as the persistor loads it. The alternative (showing a spinner during rehydrate) blanks the screen on every cold load and looks awful.

The SSR-safe storage adapter is the other piece. redux-persist's default localStorage adapter complains loudly when imported in a Node environment ("failed to create sync storage, falling back to noop"). The fix is a tiny shim:

// src/store/storage.ts
import type { WebStorage } from 'redux-persist';
import createWebStorage from 'redux-persist/lib/storage/createWebStorage';

const createNoopStorage = (): WebStorage => ({
  getItem: (_key) => Promise.resolve(null),
  setItem: (_key, _value) => Promise.resolve(),
  removeItem: (_key) => Promise.resolve(),
});

const storage: WebStorage =
  typeof window !== 'undefined' ? createWebStorage('local') : createNoopStorage();

export default storage;

Real localStorage in the browser, typed no-op on the server. The warning disappears and the typings stay honest.

Per-feature persist configs

A subtle convention: persistence config lives with the feature, not in a central place:

// src/features/counter/store/persist.ts
const COUNT_PERSIST_VERSION = 1;

const migrations = {
  // 2: (state) => ({ ...state, newField: defaultValue }),
} satisfies Record<number, (state: PersistedState) => PersistedState>;

export const countPersistConfig: PersistConfig<CounterState> = {
  key: 'count',
  storage,
  version: COUNT_PERSIST_VERSION,
  whitelist: ['value'],
  migrate: createMigrate(migrations, { debug: false }),
};

rootReducer.ts composes them:

export const rootReducer = combineReducers({
  count: persistReducer(countPersistConfig, countReducer),
  ws: wsReducer,
});

When a feature is deleted, its persistence config goes with it. When a feature's state shape changes, the migration is in the same folder as the slice. The cognitive overhead of "where's the persist config for X" drops to zero.

9. i18n with next-intl: static rendering that actually works

The starter uses next-intl with a [locale] route group. The setup is conventional, but two specific knobs make a meaningful difference.

localePrefix: 'never' in src/i18n/routing.ts keeps URLs free of the locale segment by default. This is the right default for most apps — users get /about instead of /en/about, the canonical SEO URL is clean, and you can flip it to 'always' or 'as-needed' if your locale strategy requires visible prefixes later.

getTimeZone() from the env keeps SSR deterministic:

// src/i18n/request.ts
export default getRequestConfig(async ({ requestLocale }) => {
  const requested = await requestLocale;
  const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale;

  return {
    locale,
    timeZone: env.DEFAULT_TIMEZONE,
    messages: (await import(`./translations/${locale}.json`)).default,
  };
});

Without an explicit timeZone, next-intl falls back to the environment's local time zone and logs an ENVIRONMENT_FALLBACK warning on every render. Worse, server and client may end up with different time zones, causing hydration mismatches on dates. Setting it explicitly silences the warning and keeps the SSR output deterministic.

The RootLayout reads both messages and time zone on the server, then passes them down through RootProvider:

const [messages, timeZone] = await Promise.all([getMessages(), getTimeZone()]);

return (
  <html lang={locale} dir={getLocaleDirection(locale)} suppressHydrationWarning>
    <body className={`${livvic.variable} bg-light antialiased dark:bg-dark`}>
      <RootProvider locale={locale} messages={messages} timeZone={timeZone}>
        <HttpClientBundleSentinel />
        {children}
      </RootProvider>
    </body>
  </html>
);

suppressHydrationWarning is on the <html> element because the theme provider toggles a class on it before React hydrates — the only legitimate case for that prop.

The locale list is data, in src/lib/config/app-locales.ts. The routing.ts config reads from it. Adding a locale is three or four edits (translation file, type widening, list update). The README walks through it.

10. Logger, secure storage, and the small things that compound

Logger

The default Node.js logger story is console.log. It's fine in dev. It's a disaster in production: no structure, no levels, no redaction, no log aggregator support.

The starter uses pino with environment-aware transport:

function buildServerLogger(): Logger {
  if (isTest) return pino({ ...baseOptions, level: LogLevel.SILENT });

  if (isProd) {
    return pino(baseOptions, pino.destination({ sync: false }));
  }

  return pino({
    ...baseOptions,
    transport: {
      target: 'pino-pretty',
      options: {
        colorize: true,
        singleLine: true,
        translateTime: 'yyyy-mm-dd HH:MM:ss.l',
        ignore: 'pid,hostname',
      },
    },
  });
}

Three behaviors:

test: silent. No IO, no worker threads. Keeps CI output clean.
dev: pino-pretty, single-line, colorized, with readable timestamps.
prod: raw JSON to stdout via pino.destination({ sync: false }). Async writes, no transport overhead, drops straight into Datadog/CloudWatch/etc.

Redaction paths are declared centrally:

export const SENSITIVE_KEYS = [
  'password', 'passwordConfirmation', 'token',
  'accessToken', 'refreshToken', 'secret', 'apiKey', 'creditCard',
];

export const SENSITIVE_HEADERS = ['authorization', 'cookie', 'set-cookie'];

export const SENSITIVE_REDACTION_PATHS = [
  ...SENSITIVE_KEYS.map((key) => `*.${key}`),
  ...SENSITIVE_HEADERS.map((header) => `req.headers["${header}"]`),
  ...SENSITIVE_KEYS.map((key) => `req.body.${key}`),
  ...SENSITIVE_KEYS.map((key) => `req.body.*.${key}`),
];

Anything that matches gets [REDACTED]. You can log a whole request object — including headers and body — without leaking tokens. The Biome noConsole rule errors on console.log so nobody accidentally bypasses the logger.

Secure storage

react-secure-storage is wrapped in src/services/storage/secure-storage.service.ts. The wrapper exists for two reasons:

It centralizes the storage keys (access_token, refresh_token) so they aren't string-typed across the codebase.
It wraps every read in a try/catch — the underlying library throws if its encryption fingerprint changes (e.g. after a browser data clear), and the right behavior is to return null, not crash.

In default cookie-mode (SAVE_AUTH_TOKENS = false), this whole wrapper is inert — the cookies are HttpOnly and never touch JS. Flip the constant and the bearer-token plumbing wakes up. No code changes needed.

The test setup stubs the library globally because react-secure-storage constructs an EncryptionService at module load that calls <canvas>.getContext for browser fingerprinting, and jsdom doesn't implement canvas:

// test/setup.ts
vi.mock('react-secure-storage', () => {
  const store = new Map<string, unknown>();
  return {
    default: {
      setItem: (k: string, v: unknown) => store.set(k, v),
      getItem: (k: string) => store.get(k) ?? null,
      removeItem: (k: string) => store.delete(k),
      clear: () => store.clear(),
    },
  };
});

vi.mock('server-only', () => ({}));

The server-only stub is necessary too: that package throws at module load outside a Next.js server bundle (the bundler is supposed to redirect it to a no-op). Vitest doesn't do that redirect, so we stub it manually for tests. Production builds are unaffected.

11. Quality gates: three Husky hooks, one CI workflow, a custom deprecated-API scanner

The hooks layer is what makes the day-90 defaults stick.

pre-commit:

yarn env:sync --check         # is .env.example in sync with .env?
yarn lint-staged              # Biome on staged files only
STAGED_TS_FILES=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(ts|tsx)$' || true)
[ -n "$STAGED_TS_FILES" ] && yarn type-check

Fast (under 5s most commits). Type-check is conditional on staged TS files. Lint-staged only touches changed files.

pre-push:

yarn ci:check                 # Biome lint + format + import sort (single pass)
yarn type-check
yarn check:deprecated
yarn test                     # Vitest, full run

Build is deliberately left to CI — pre-push should be fast enough that contributors don't try to --no-verify around it. Build takes 30-60s; lint + tests take 10-15s.

commit-msg: commitlint with @commitlint/config-conventional. yarn commit runs commitizen for a guided prompt if you want it.

CI runs the same five steps in sequence (ci:check → type-check → check:deprecated → test → build). Single job, same Node version as local development, cached yarn.

The most novel piece is check:deprecated. TypeScript flags @deprecated usage at the "suggestion" severity level, which means tsc --noEmit happily passes a codebase full of deprecated API calls. Biome doesn't catch this either. So the starter ships a small compiler-API script that walks every identifier and fails if any resolved symbol carries the @deprecated tag:

// scripts/check-deprecated.ts
import ts from 'typescript';
import path from 'node:path';

const cwd = process.cwd();
const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, 'tsconfig.json');
const raw = ts.readConfigFile(configPath!, ts.sys.readFile).config;
const parsed = ts.parseJsonConfigFileContent(raw, ts.sys, path.dirname(configPath!));

const program = ts.createProgram({ rootNames: parsed.fileNames, options: parsed.options });
const checker = program.getTypeChecker();

function isDeprecated(sym: ts.Symbol | undefined): boolean {
  if (!sym) return false;
  return sym.getJsDocTags(checker).some((tag) => tag.name === 'deprecated');
}

let hits = 0;
for (const sourceFile of program.getSourceFiles()) {
  if (sourceFile.fileName.includes('node_modules')) continue;
  if (!sourceFile.fileName.startsWith(cwd)) continue;

  const visit = (node: ts.Node): void => {
    if (ts.isIdentifier(node)) {
      const sym = checker.getSymbolAtLocation(node);
      if (isDeprecated(sym)) {
        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
        console.log(
          `${path.relative(cwd, sourceFile.fileName)}:${line + 1}:${character + 1}  ${node.text}  (@deprecated)`,
        );
        hits++;
      }
    }
    ts.forEachChild(node, visit);
  };
  visit(sourceFile);
}

process.exit(hits === 0 ? 0 : 1);

About 50 lines. Runs in ~3s on a project of this size. Catches every deprecated React API, every deprecated Next API, every deprecated method in your own code with /** @deprecated */ on it. Wired into validate, pre-push, and CI.

This is the kind of script you write once and forget about; six months later it pays for itself by flagging the deprecation you didn't see in the release notes.

12. What I deliberately left out

Just as important as what's in the starter is what isn't. Restraint is the harder discipline.

No auth feature. Only the contract types (AuthUser, AuthTokens, AuthResponse, RefreshTokensResponse) and the endpoint paths (AppApis.auth.*). The CHANGELOG notes that empty features/auth/, features/dashboard/, app/[locale]/auth/, and services/api/ directories existed in an earlier version and were deleted: "they had no real code and were drifting away from what the docs described." Empty scaffolding rots fast — better to have a clean slate.
No shared UI components. components/index.ts is empty. There's no Button, no Input, no Card. Bring your own design system; the starter shouldn't impose one.
No form library. Pick TanStack Form, React Hook Form, or native FormData. The HTTP layer's getFieldErrors() integrates with any of them.
No data-fetching cache. No SWR, no TanStack Query. The HTTP clients return raw ResultAsync<T>. Caching is a downstream choice, and the wrong default here costs you a lot of bundle.
No analytics, no error tracking. ApiException.requestId is the hook point for Sentry/Datadog/etc. — wire in what you use.
No payment, email, file upload. Pure transport + state + i18n shell.

The model is: the template provides the frame; features ship separately. This is what the @teispace/next-maker CLI is for — it composes the template with feature packs to generate end products. The split keeps the template stable across many projects.

13. Lessons that generalize beyond this starter

Stepping back from the specific code, four principles shaped almost every decision:

1. Encode boundaries in the type system or the build, not in convention.

The universal/server HTTP entry split would have been "be careful where you import from" as a convention. As a structural split with 'server-only' and a bundle sentinel, it's a compile-time error if you get it wrong. Conventions degrade as teams grow; type-level and build-level enforcement does not.

2. Fail fast at the boundary; trust internal invariants.

Env vars validated at module load. WS connect throws on SSR. HTTP returns Either instead of throwing. The pattern is the same: catch the bad case where it enters the system, surface it loudly, and let the rest of the code assume things are well-formed.

3. Make the day-1 defaults match the day-90 needs.

Pre-request Redux store, PersistGate with loading={children}, env-aware logger transport, X-Request-Id correlation, sensitive-key redaction. None of these matter on day 1. All of them matter the first time you ship to production and start debugging. Bake them in early; the marginal cost on day 1 is zero, and the savings on day 90 are real.

4. The cost of one wrong default compounds across every project that copies the template.

This is why the starter is unusually opinionated about things like "no console.log" or "always log the requestId on failures." A template gets copied into N projects. A bad default in the template becomes N projects with the same bad default. Holding the line on small things — single quotes, no ESLint, never process.env.NEXT_PUBLIC_* directly — pays off N times over.

Try it

If any of this resonated:

The starter repo: github.com/teispace/nextjs-starter
The CLI that scaffolds applications from it: @teispace/next-maker
The theme package referenced throughout: @teispace/next-themes

Clone it. Read the comments — the codebase practices what it preaches about "comments explain WHY, not WHAT," and the rationale for every non-obvious choice is in the code where the choice was made.

If you find a design decision you disagree with, open an issue. Half the value of writing this article is having my own assumptions stress-tested by people who've hit different production traps than I have.

If you found this useful, follow me for more deep-dives on production Next.js, TypeScript, and the boring infrastructure choices that make or break a project.

DEV Community: Krishna Adhikari

How we engineered a better Next.js theme library

How we engineered a better Next.js theme library

Why the inline anti-FOUC script is the heart of everything

Bug #1: next-themes and the React 19 inline script warning

Bug #2: __name(...) wrappers crashing the inline script

Bug #3: The XSS surface every theme library leaves open

Bug #4: The disable-transition <style> that re-flickers on every set

Bug #5: The god-component provider

What we built that the others don't have

Storage adapters as a public interface

View Transitions API integration

Sec-CH-Prefers-Color-Scheme client hint

Sync getTheme(Request) for middleware

Codemod from next-themes

Published with SLSA provenance

A fair tally

What I'd want you to take from this

Try it

I Rebuilt My Next.js Starter From Scratch on Next 16 — Here's Every Decision I Made (and Why)

I Rebuilt My Next.js Starter From Scratch on Next 16 — Here's Every Decision I Made (and Why)

Table of contents

1. The "not the Next.js you know" preamble

2. Why Biome replaced ESLint + Prettier

3. Env validation: zod, cached, fail-fast

4. The HTTP layer: the hardest decision in the repo

The contract

Two clients, same surface

The universal/server split (this is the load-bearing bit)

Token refresh that doesn't thunder-herd

X-Request-Id correlation, end-to-end

Typed queries and pagination, built in

5. The build-time tripwire that catches the bug you can't reproduce

6. Either + ApiException: errors as values

7. The WebSocket layer: same pattern, stricter rules

Lazy connect, Proxy-backed singleton

The three hooks, and what lazy connect actually means

Typed events via declaration merging

auth:force:disconnect — branch on reconnectable, not reason

State flows through Redux, but only via the bridge

8. Per-request Redux store with SSR-safe persistence

Per-feature persist configs

9. i18n with next-intl: static rendering that actually works

10. Logger, secure storage, and the small things that compound

Logger

Secure storage

11. Quality gates: three Husky hooks, one CI workflow, a custom deprecated-API scanner

12. What I deliberately left out

13. Lessons that generalize beyond this starter

Try it

Bug #1: `next-themes` and the React 19 inline script warning

Bug #2: `__name(...)` wrappers crashing the inline script

Bug #4: The disable-transition `<style>` that re-flickers on every set

`Sec-CH-Prefers-Color-Scheme` client hint

Sync `getTheme(Request)` for middleware

Codemod from `next-themes`

`auth:force:disconnect` — branch on `reconnectable`, not `reason`