DEV Community: Ish Chhabra

How to add theming to an SSR app (TanStack Start)

Ish Chhabra — Fri, 06 Mar 2026 18:38:03 +0000

Where should we persist the theme preference in an SSR app?

Implementing dark mode often seems like a trivial feature. In practice, it turns out to be surprisingly tricky in server-rendered applications.

In a purely client-side app, persisting the theme preference is straightforward: store the value somewhere in the browser like localStorage and read it again when the app loads. However, doing the same in an SSR app comes with a catch.

Storing it in localStorage

Naturally, the first step is to reach for the same approach that works in a client-side app: persist the theme in localStorage.

theme.tsx

const STORAGE_KEY = "theme";

type Theme = "light" | "dark";
const DEFAULT_THEME: Theme = "light";

interface ThemeContextValue {
  theme: Theme;
  toggleTheme: () => void;
}
const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState(
    () => (localStorage.getItem(STORAGE_KEY) as Theme) ?? DEFAULT_THEME
  );

  const toggleTheme = () => {
    const next: Theme = theme === "dark" ? "light" : "dark";
    localStorage.setItem(STORAGE_KEY, next);
    setTheme(next);
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

There's a problem though — the server has no localStorage, so this throws an error immediately.

🚨 Danger

ReferenceError: localStorage is not defined

at ThemeProvider (theme.tsx:7:30)

To fix it, we need to guard the read from localStorage with typeof window !== "undefined". This way, the server falls back to the default theme and only the browser reads from localStorage:

theme.tsx

  const [theme, setTheme] = useState<Theme>(
-   () => (localStorage.getItem(STORAGE_KEY) as Theme) ?? DEFAULT_THEME
+   () =>
+     typeof window !== "undefined"
+       ? (localStorage.getItem(STORAGE_KEY) as Theme) ?? DEFAULT_THEME
+       : DEFAULT_THEME
  );

Try it: switch to dark mode, then refresh the page.

▶ Try the interactive demo

If you refreshed, you likely saw the page flash light for a moment before switching to dark. That happens because the server sends the initial HTML before any JavaScript runs — it has no access to localStorage, so it always renders the default theme. By the time the client loads and reads your stored preference, the user has already seen the wrong one.

To fix this, the server needs to know the theme before it sends the initial HTML. Since the server can't read localStorage, we need to store it somewhere it can read — cookies.

Storing it in cookies

Cookies are sent with every HTTP request, so the server can read them before rendering anything. Here's how we can do that in TanStack Start:

theme.tsx

import { useRouteContext, useRouter } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { getCookie, setCookie } from "@tanstack/react-start/server";
import { type ReactNode, createContext, useContext } from "react";
import { z } from "zod";

const storageKey = "theme";
const themeSchema = z.enum(["light", "dark"]);
export type Theme = z.infer<typeof themeSchema>;

export const getThemeServerFn = createServerFn()
  .handler((): Theme => {
    const raw = getCookie(storageKey) ?? "dark";
    const result = themeSchema.safeParse(raw);
    return result.success ? result.data : "dark";
  });

export const setThemeServerFn = createServerFn()
  .inputValidator(themeSchema)
  .handler(async ({ data }) => {
    setCookie(storageKey, data);
  });

interface ThemeContextValue {
  theme: Theme;
  toggleTheme: () => void;
}
const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const { theme: serverTheme } = useRouteContext({ from: "__root__" });
  const router = useRouter();

  const toggleTheme = async () => {
    const next: Theme = serverTheme === "dark" ? "light" : "dark";
    await setThemeServerFn({ data: next });
    await router.invalidate();
  };

  return (
    <ThemeContext.Provider value={{ theme: serverTheme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme(): ThemeContextValue {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
  return ctx;
}

__root.tsx

export const Route = createRootRoute({
  beforeLoad: async () => ({
    theme: await getThemeServerFn(),
  }),
  // ...
});

The server reads the cookie, sets the correct class on <html>, and the first paint matches the user's preference. No flash. (Later we'll add a client cache so client-side navigations don't refetch the theme; this is the minimal version.)

Try it: toggle the theme and refresh the page. The correct theme appears on first load with no flash.

▶ Try the interactive demo

Why is the toggle slow?

If you tried toggling in the demo above, you likely noticed that it's not instant. There's a delay between when you click the toggle and when the theme changes. That's because every toggle has to wait for two server round-trips before the UI updates.

setThemeServerFn writes the new value to the cookie on the server.
router.invalidate() re-runs beforeLoad, which calls getThemeServerFn() to read the updated cookie.

To make the toggle feel instant, we can optimistically apply the new theme before the server responds.

theme.tsx

export function ThemeProvider({ children }: { children: ReactNode }) {
  const { theme: serverTheme } = useRouteContext({ from: "__root__" });
  const router = useRouter();
+  const [theme, setOptimisticTheme] = useOptimistic(serverTheme);
+  const requestRef = useRef(0);

-  const toggleTheme = async () => {
-    const next: Theme = serverTheme === "dark" ? "light" : "dark";
-    await setThemeServerFn({ data: next });
-    await router.invalidate();
-  };
+  const toggleTheme = () => {
+    const next: Theme = theme === "dark" ? "light" : "dark";
+    const id = ++requestRef.current;
+    startTransition(async () => {
+      setOptimisticTheme(next);
+      await setThemeServerFn({ data: next });
+      if (id === requestRef.current) await router.invalidate();
+    });
+  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

setOptimisticTheme(next) updates the UI immediately. The server write and invalidation happen in the background. If the server call fails, the optimistic value rolls back to serverTheme automatically. The requestRef guard ensures we only call router.invalidate() if this request is still the latest — so rapid toggles don't let an older response overwrite the theme. The toggle is instant now.

Try it: the toggle should feel instant.

▶ Try the interactive demo

But there's another problem. Try navigating.

Why is navigation slow?

In the demo above, the toggle is instant. But click between Home and About — every navigation takes about a second. The app isn't re-rendering on the server — it's waiting for a single string.

Here's why. In TanStack Start, beforeLoad runs on the server for the initial request and on the client for every subsequent navigation. When it runs on the client, getThemeServerFn() is still a server function — it makes a network request back to the server. The route can't finish loading until that request resolves. Every link click, every back button, every forward navigation pays this cost.

Think of it like hydration. On the initial page load, the server sends the theme with the HTML — the client needs that to render correctly. But after hydration, the client already knows the theme. It's right there in memory. There's no reason to ask the server for it again. After the first load, this should behave like a SPA.

To make navigation instant, cache the theme on the client and read from it in beforeLoad when we're in the browser. Store the theme in a module-level variable; have beforeLoad check typeof window: on the server, call the server function; on the client, return the cached value. No network request.

theme.tsx

const themeSchema = z.enum(["light", "dark"]);
export type Theme = z.infer<typeof themeSchema>;

+ // ── Client cache ──────────────────────────────────────
+ let clientThemeCache: Theme = "dark";
+ export function getThemeForClientNav(): Theme {
+   return clientThemeCache;
+ }
+ export function setThemeForClientNav(theme: Theme): void {
+   clientThemeCache = theme;
+ }
+
// ── Server functions ──────────────────────────────────
export const getThemeServerFn = createServerFn()
  .handler((): Theme => { ... });

export function ThemeProvider({ children }: Readonly<{ children: ReactNode }>) {
  const { theme: serverTheme } = useRouteContext({ from: "__root__" });
  const router = useRouter();
  const [theme, setOptimisticTheme] = useOptimistic(serverTheme);
  const requestRef = useRef(0);

+  useEffect(() => {
+    setThemeForClientNav(serverTheme);
+  }, [serverTheme]);

  const toggleTheme = () => {
    const next: Theme = theme === "dark" ? "light" : "dark";
    const id = ++requestRef.current;
+    setThemeForClientNav(next);
    startTransition(async () => {
      setOptimisticTheme(next);
      await setThemeServerFn({ data: next });
      if (id === requestRef.current) await router.invalidate();
    });
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

The root route's beforeLoad calls the server on the initial request and the cache on the client:

__root.tsx

beforeLoad: async () => {
  if (typeof window === "undefined") {
    return { theme: await getThemeServerFn() };
  }
  return { theme: getThemeForClientNav() };
},

The demo below uses the client cache: on the client, beforeLoad calls getThemeForClientNav() instead of the server, so navigation is instant. Click between Home and About and compare with the previous demo (cookie-optimistic).

▶ Try the interactive demo

Full implementation

Two files. The theme module with server functions, client cache, and React context:

src/lib/theme.tsx

import { useRouteContext, useRouter } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { getCookie, setCookie } from "@tanstack/react-start/server";
import {
  type ReactNode,
  createContext,
  startTransition,
  useContext,
  useEffect,
  useOptimistic,
  useRef,
} from "react";
import { z } from "zod";

const storageKey = "theme";
const themeSchema = z.enum(["light", "dark"]);
export type Theme = z.infer<typeof themeSchema>;

// ── Client cache ──────────────────────────────────────────
let clientThemeCache: Theme = "dark";
export function getThemeForClientNav(): Theme {
  return clientThemeCache;
}
export function setThemeForClientNav(theme: Theme): void {
  clientThemeCache = theme;
}

// ── Server functions ──────────────────────────────────────
export const getThemeServerFn = createServerFn()
  .handler((): Theme => {
    const raw = getCookie(storageKey) ?? "dark";
    const result = themeSchema.safeParse(raw);
    return result.success ? result.data : "dark";
  });

export const setThemeServerFn = createServerFn()
  .inputValidator(themeSchema)
  .handler(async ({ data }) => {
    setCookie(storageKey, data);
  });

// ── Provider ──────────────────────────────────────────────
interface ThemeContextValue {
  theme: Theme;
  toggleTheme: () => void;
}
const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: Readonly<{ children: ReactNode }>) {
  const { theme: serverTheme } = useRouteContext({ from: "__root__" });
  const router = useRouter();
  const [theme, setOptimisticTheme] = useOptimistic(serverTheme);
  const requestRef = useRef(0);

  useEffect(() => {
    setThemeForClientNav(serverTheme);
  }, [serverTheme]);

  const toggleTheme = () => {
    const next: Theme = theme === "dark" ? "light" : "dark";
    const id = ++requestRef.current;
    setThemeForClientNav(next);

    startTransition(async () => {
      setOptimisticTheme(next);
      await setThemeServerFn({ data: next });
      if (id === requestRef.current) {
        await router.invalidate();
      }
    });
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme(): ThemeContextValue {
  const ctx = useContext(ThemeContext);
  if (!ctx) {
    throw new Error("useTheme must be used within ThemeProvider");
  }
  return ctx;
}

And the root route:

src/routes/__root.tsx

import {
  getThemeForClientNav,
  getThemeServerFn,
  ThemeProvider,
  useTheme,
} from "../lib/theme";

export const Route = createRootRoute({
  beforeLoad: async () => {
    if (typeof window === "undefined") {
      return { theme: await getThemeServerFn() };
    }
    return { theme: getThemeForClientNav() };
  },
  // ...
});

References

TanStack Start — Execution model — how beforeLoad runs on server vs client
TanStack Start — Selective SSR — controlling what runs on the server per route
React — useOptimistic — optimistically update UI before a server response

Originally published on ishchhabra.com. Follow me there for more.

How to build a pnpm monorepo, the right way

Ish Chhabra — Fri, 06 Mar 2026 18:14:35 +0000

At some point every growing application ends up with code that needs to be shared across surfaces. Maybe you started with a web app and then needed to build a mobile app alongside it, and suddenly a whole layer of shared logic — the design system, the business logic, the API layer — needs to live somewhere both can reach. When that happens, you have two options: extract the shared code into a separate repository, or set up a monorepo.

With separate repositories, iterating on shared code becomes a slow, multi-step process: make a change, propagate it to every consumer, and then test to see if it actually works. What should be a quick tweak becomes an afternoon.

A monorepo solves this by keeping shared packages and their consumers in the same place. Changes to shared code are immediately visible to every consumer, making it easier to iterate and test. For this guide, we'll be using pnpm workspaces, which supports hard-linking dependencies (more on that later).

How to set up a pnpm workspace

A pnpm workspace is defined by a pnpm-workspace.yaml at the root that tells pnpm where to find your packages:

pnpm-workspace.yaml

packages:
  - "apps/*"
  - "packages/*"

my-monorepo/
├── pnpm-workspace.yaml
├── apps/
│   └── my-app/
│       └── package.json      # depends on @packages/ui
└── packages/
    └── ui/
        ├── package.json      # peerDependency on react
        └── src/

Run pnpm install and pnpm symlinks your workspace packages together. It feels like everything should just work — and for simple cases, it does. But add a library like React — one that assumes only one copy of itself exists in memory — and:

🚨 Danger

Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component.

🚨 Danger

Error: No QueryClient set, use QueryClientProvider to set one

The first error is React saying "I found two copies of myself." The second is TanStack Query saying "the provider exists, but I can't see it" — because it's looking in a different React instance's Context tree.

Why two copies? How Node resolves imports

When pnpm installs a workspace package, it symlinks node_modules/@packages/ui → packages/ui/. When that package runs require("react"), Node resolves from the symlink target — not from the consuming app:

📝 Note

Any library with module-level state breaks when duplicated: React (hook dispatcher, Context), event emitters, caches, registries. If it stores state in a module closure, loading it twice creates two invisible parallel universes that can't communicate.

With two apps, it gets worse

With one app, both copies might be the same version — duplicate state, but at least the same API. With two apps that need different versions, it gets worse. The shared package's devDependencies can only pin one version. Whichever app doesn't match ends up with not just two instances — but two different versions.

Injected dependencies

The resolution problem happens because Node walks from the symlink target. To fix it, we need the shared package's code to resolve from the consumer's node_modules instead. pnpm has a flag for exactly this: dependenciesMeta.injected: true.

Instead of creating a symlink to packages/ui/, pnpm creates a hard-linked copy of each file inside the consumer's node_modules. When the shared code runs require("react"), Node resolves from the consumer's directory tree — and finds the consumer's React. Not the package's.

apps/my-app/package.json

{
  "dependencies": {
    "react": "^18",
    "@packages/ui": "workspace:*"
  },
  "dependenciesMeta": {
    "@packages/ui": { "injected": true }
  }
}

Each consumer gets its own copy. Each copy resolves from the consumer's tree. App A gets React 18. App B gets React 19. One shared package, correct resolution everywhere.

The demo below runs a real workspace in-browser. A shared package returns whichever lodash version gets resolved at runtime — the package pins 4.17.20, consumers have 4.17.21.

Try it: switch between the symlink and injected tabs, then click "Compare both".

What about bundler resolution?

Another approach: configure the app's bundler so peer deps resolve from the app's node_modules. Next.js does this specifically to resolve React to its own vendored copy.

The problem: each consumer has to make the change. That means maintenance overhead — every app that uses the shared package must configure its bundler to resolve React from the app's node_modules. And each consumer might use a different bundler: Next.js uses Webpack/Turbopack, Vite uses esbuild/Rollup, React Native uses Metro. Each has its own config format and resolution rules. With pnpm injected, there's no bundler config needed — it works at the package manager level, regardless of what each consumer uses.

Making it work in practice

Injected dependencies fix the resolution problem, but they introduce DX challenges. Let's solve them one by one.

Problem 1: Manual builds on a fresh clone

You clone the repo, run pnpm install, start the app — and it fails. dist/ doesn't exist yet. You have to manually build every shared package before any consumer can import from it. And if packages depend on each other, you have to build them in the right order — leaf packages first, then their consumers, up the chain.

The prepare lifecycle hook solves this — it runs automatically on pnpm install:

packages/ui/package.json (scripts)

{
  "build": "tsc",
  "prepare": "pnpm build"
}

Now pnpm install automatically builds the package. One command, dist/ exists, consumers can import.

Problem 2: Changes don't propagate

You make a change to a component in the shared package, save the file, and nothing happens in the consuming app. With injected deps, consumers get a hard-linked copy of dist/ created at install time. When tsc rebuilds, it writes new files with new inodes — but the consumer's hard links still point to the old ones. The consumer doesn't see the new build.

This is where pnpm-sync (by TikTok) comes in. It re-copies dist/ into each consumer's node_modules after every build:

pnpm-sync prepare — writes a .pnpm-sync.json config describing which consumers need copies and where their stores are.
pnpm-sync copy — reads that config and copies dist/ into each consumer.

We wire these into the existing scripts. The prepare hook now also writes the sync config, and postbuild runs the copy after every build:

packages/ui/package.json (scripts)

{
  "build": "tsc",
  "postbuild": "pnpm-sync copy",
  "prepare": "pnpm sync:prepare && pnpm build"
}

On a fresh clone: pnpm install → prepare runs → writes sync config → builds dist/ → postbuild fires → pnpm-sync copy syncs output to consumers. One command and everything is ready.

During development, we want pnpm-sync copy to run after every successful recompilation too. tsc --watch doesn't support running a command on success, so we swap it for tsc-watch, which adds an --onSuccess hook:

packages/ui/package.json (scripts)

{
  "build:watch": "tsc-watch --onSuccess \"pnpm postbuild\""
}

The full script setup for a shared package:

packages/ui/package.json

{
  "name": "@packages/ui",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "postbuild": "pnpm-sync copy",
    "prepare": "pnpm sync:prepare && pnpm build",
    "build:watch": "tsc-watch --onSuccess \"pnpm postbuild\"",
    "sync:prepare": "pnpm sync:prepare:my-app",
    "sync:prepare:my-app": "pnpm-sync prepare -l ../../apps/my-app/pnpm-lock.yaml -s ../../apps/my-app/node_modules/.pnpm"
  },
  "peerDependencies": { "react": "^18 || ^19" },
  "devDependencies": {
    "@types/react": "^18 || ^19",
    "tsc-watch": "^7.1.1",
    "typescript": "^5"
  }
}

📝 Note

Multiple consumers? Chain the prepare scripts: "sync:prepare": "pnpm sync:prepare:app-a && pnpm sync:prepare:app-b" — each pointing to its consumer's lockfile and store path.

Problem 3: Dev server doesn't hot reload

At this point, if you inspect node_modules, the updated files are there, yet the dev server still shows the old version and the only way to see your changes is to restart it every time. By default, most bundlers ignore changes to node_modules entirely, so the files change on disk but nobody's watching.

Vite

Vite pre-bundles everything in node_modules by default, including your workspace packages. So even after pnpm-sync copy updates the files, Vite keeps serving its cached version. Exclude them from pre-bundling so Vite reads their dist/ directly. You can use @pnpm/find-workspace-packages to discover them dynamically:

vite.config.ts

import { findWorkspacePackagesNoCheck } from "@pnpm/find-workspace-packages";

const workspaceRoot = path.resolve(__dirname, "../..");

export default defineConfig(async () => {
  const workspacePackages = await findWorkspacePackagesNoCheck(workspaceRoot);
  const workspacePackageNames = workspacePackages
    .filter((p) => path.resolve(p.dir) !== path.resolve(__dirname))
    .map((p) => p.manifest.name)
    .filter((name): name is string => typeof name === "string");

  return {
    optimizeDeps: {
      // Skip pre-bundling for workspace packages so Vite picks up
      // changes from pnpm-sync without restarting the dev server.
      exclude: workspacePackageNames,
    },
  };
});

Webpack

Webpack's file watcher ignores all of node_modules by default. To pick up changes in workspace packages, you need to carve out an exception:

webpack.config.mjs

import { findWorkspacePackagesNoCheck } from "@pnpm/find-workspace-packages";

const workspaceRoot = path.resolve(__dirname, "../..");

export default async () => {
  const workspacePackages = await findWorkspacePackagesNoCheck(workspaceRoot);
  const workspacePackageNames = workspacePackages
    .filter((p) => path.resolve(p.dir) !== path.resolve(__dirname))
    .map((p) => p.manifest.name)
    .filter((name) => typeof name === "string");

  const pattern = workspacePackageNames.join("|").replace(/\//g, "\\/");

  return {
    watchOptions: {
      ignored: new RegExp("node_modules/(?!" + pattern + ")"),
    },
    snapshot: {
      managedPaths: [
        new RegExp("^(.+?[\\/]node_modules[\\/])(?!" + pattern + ")"),
      ],
    },
  };
};

Problem 4: Cmd+Click opens .d.ts, not source

Since consumers import from dist/, Cmd+Click in VSCode opens Link.d.ts instead of Link.tsx. Unlike using transpilePackages in Next.js or similar bundler-level source resolution, our approach lets each package own its build tooling. The tradeoff is that we need declaration maps to get good navigation.

Enable declarationMap: true in the package's tsconfig:

packages/ui/tsconfig.json

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

But even with declaration maps, VSCode still opens .d.ts files. There's an open bug (TypeScript #62009) where VSCode doesn't follow declaration maps when the source root is relative.

The workaround: pass an absolute sourceRoot at build time using $(pwd):

build command

tsc --sourceRoot "$(pwd)/src"

At build time, $(pwd) expands to the package's absolute path. The declaration maps embed this absolute path, so VSCode resolves to the actual source file. Add this flag to both your build and build:watch scripts.

With the fix, Cmd+Click now opens the actual source:

Why not Bun?

Bun's isolated installs provide strict dependency isolation. But even with isolated installs, workspace packages are still symlinked to their source directory. There's no dependenciesMeta.injected equivalent. No hard-linked copies. Resolution still follows from the package's directory.

Same test, same setup — package has lodash 4.17.20 as devDep, consumer has 4.17.21:

	pnpm (injected)	Bun (isolated)
Resolved version	4.17.21 (consumer's) ✓	4.17.20 (package's) ✗
Workspace packages	Hard-linked copy	Symlinked to source
Fix for peer deps	Built-in (one flag)	Requires bundler config

Without an injected equivalent, Bun can't correctly resolve peer dependencies for workspace packages. That's why I still use pnpm for monorepos.

Troubleshooting

Missing .d.ts files after pnpm install

Error: "Could not find a declaration file for module '@packages/ui'"

Why: Stale tsconfig.tsbuildinfo. The incremental build cache can cause tsc to skip recompilation or use outdated information, leading to missing or incorrect .d.ts files.

terminal
```
rm packages/ui/tsconfig.tsbuildinfo
pnpm --filter @packages/ui build
```

References

Originally published on ishchhabra.com. Follow me there for more.