How to properly use Ant Design with TanStack Start #4052

createdbymahmood · 2025-04-25T15:20:26Z

createdbymahmood
Apr 25, 2025

Hey everyone 👋,

I’ve been working on a project using TanStack Start and wanted to integrate Ant Design (antd) as the UI library. Overall, it’s been a solid experience — but I’ve run into a consistent issue with styling flicker, especially on initial load or navigation.

From what I can tell, this is due to how Ant Design handles CSS-in-JS via emotion. When used in an SSR context like TanStack Start, the styles don’t seem to hydrate properly or fast enough, leading to visual flickers and layout shifts.

Has anyone successfully set up Ant Design with TanStack Start?

Specifically:

How are you handling SSR and style hydration for Ant Design?
Have you managed to fix or minimize styling flicker?
Are you using StyleProvider, extractStyle, or anything custom to get it working smoothly?

Feature Request-ish:

If there’s a recommended setup, it would be amazing to have this documented — either officially or even as a community example. I imagine others trying to use Ant Design or similar CSS-in-JS libraries would benefit from some guidance here.

Thanks in advance! Would love to hear how others are solving this, and happy to contribute back if we land on a good pattern.

MukundaKatta · 2026-04-21T17:40:39Z

MukundaKatta
Apr 21, 2026

antd v5's emotion-based flicker under SSR is fixable but fiddly. You want StyleProvider + extractStyle on the server, injected into head before hydration. In TanStack Start the cleanest hook is a root-route head function that calls extractStyle(cache, true) after render — without true you only get partial rules. Happy to share a working snippet if useful.

1 reply

kunKun-tx May 8, 2026

antd v5's emotion-based flicker under SSR is fixable but fiddly. You want StyleProvider + extractStyle on the server, injected into head before hydration. In TanStack Start the cleanest hook is a root-route head function that calls extractStyle(cache, true) after render — without true you only get partial rules. Happy to share a working snippet if useful.

Would mind sharing a working snippet? Thank you!

x-tahosin · 2026-04-25T12:41:31Z

x-tahosin
Apr 25, 2026

This is a well-known SSR hydration mismatch between Ant Design's CSS-in-JS (emotion-based) and TanStack Start's streaming SSR. The flicker happens because:

Server render: TanStack Start renders HTML on the server, but Ant Design's styles are generated via emotion's keyframes and css calls during component render
No style extraction on server: Without StyleProvider + extractStyle, those emotion styles don't get hoisted into <head> — they arrive as inline <style> tags or not at all during SSR
Client hydration: The browser paints the unstyled HTML first, then emotion inserts styles on hydration → visual flicker

The working setup

You need three pieces wired together:

1. `StyleProvider` with SSR extraction

In your root component (the one that wraps all routes):

// app/routes/__root.tsx
import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs';
import { Outlet, createRootRoute } from '@tanstack/react-router';

export const Route = createRootRoute({
  component: RootComponent,
  // IMPORTANT: head injection for SSR
  beforeLoad: () => {
    const cache = createCache();
    return { antdCache: cache };
  },
  loader: async ({ context }) => {
    // This runs on both server and client
    return { antdCache: context.antdCache };
  },
});

function RootComponent() {
  const { antdCache } = Route.useLoaderData();
  
  return (
    <StyleProvider cache={antdCache} hashPriority="high">
      <Outlet />
    </StyleProvider>
  );
}

Wait — TanStack Start's __root.tsx doesn't expose beforeLoad exactly like that for style extraction. Let me give you the actual pattern that works.

2. Server entry: extract and inject styles into HTML head

TanStack Start has a server entry point where you can modify the HTML shell:

// app/entry-server.tsx
import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server';
import { getRouterManifest } from '@tanstack/react-start/router-manifest';
import { createRouter } from './router';
import { extractStyle } from '@ant-design/cssinjs';

export default createStartHandler({
  createRouter,
  getRouterManifest,
})(async ({ request, router, responseHeaders }) => {
  // Wait for streaming to finish so we can extract all rendered styles
  const stream = await defaultStreamHandler({ request, router, responseHeaders });
  
  // This won't work directly because the stream is already consumed.
  // Instead, use the Document API or a custom HTML wrapper.
  
  return stream;
});

Actually, the cleaner approach in TanStack Start is using the Document component in your root route:

// app/routes/__root.tsx
import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router';
import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs';

function Document({ children }: { children: React.ReactNode }) {
  // On server, extract styles after render
  const cache = React.useMemo(() => createCache(), []);
  
  // Wrap children in StyleProvider for this render pass
  return (
    <StyleProvider cache={cache}>
      <html>
        <head>
          <HeadContent />
          {/* Ant Design styles will be injected here on server */}
          {typeof window === 'undefined' && (
            <style dangerouslySetInnerHTML={{ __html: extractStyle(cache) }} />
          )}
        </head>
        <body>
          {children}
          <Scripts />
        </body>
      </html>
    </StyleProvider>
  );
}

export const Route = createRootRoute({
  component: () => (
    <Document>
      <Outlet />
    </Document>
  ),
});

Critical detail: extractStyle(cache) must be called after the children have rendered so the cache is populated. In TanStack Start, the Document component renders after the route tree, so this works if StyleProvider wraps the entire app.

But there's a subtlety: the cache in Document and the cache inside your app components must be the same instance for extraction to capture all styles. If you create a new cache in Document and a different one inside a layout route, they won't share styles.

3. The correct architecture: single cache at root

// app/routes/__root.tsx
import React from 'react';
import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router';
import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs';

// Create ONE cache instance per request (server) or per app (client)
const getCache = () => {
  if (typeof window === 'undefined') {
    // Server: new cache per request
    return createCache();
  }
  // Client: reuse or create
  return (window as any).__ANTD_CACHE__ || createCache();
};

function Document({ children }: { children: React.ReactNode }) {
  const cache = React.useMemo(getCache, []);
  
  // Persist cache reference for client hydration
  React.useEffect(() => {
    (window as any).__ANTD_CACHE__ = cache;
  }, [cache]);
  
  const styleStr = typeof window === 'undefined' ? extractStyle(cache) : '';
  
  return (
    <StyleProvider cache={cache} hashPriority="high">
      <html lang="en">
        <head>
          <meta charSet="UTF-8" />
          <meta name="viewport" content="width=device-width, initial-scale=1" />
          <HeadContent />
          {styleStr && (
            <style id="antd-cssinjs" dangerouslySetInnerHTML={{ __html: styleStr }} />
          )}
        </head>
        <body>
          <div id="root">{children}</div>
          <Scripts />
        </body>
      </html>
    </StyleProvider>
  );
}

export const Route = createRootRoute({
  component: () => (
    <Document>
      <Outlet />
    </Document>
  ),
});

Why this eliminates flicker

Server: TanStack Start renders the full route tree inside StyleProvider. Every css() call from Ant Design components populates cache.
After render: extractStyle(cache) dumps all CSS into a <style> tag in <head>.
Browser receives HTML: Complete HTML + inline styles. No unstyled flash.
Hydration: Client-side StyleProvider reuses the same cache instance (via window.__ANTD_CACHE__). Emotion detects styles are already present and doesn't re-insert them.

If you still see flicker after this

Check for these common mistakes:

Cache mismatch: You created createCache() in a layout route AND in __root.tsx. Use only one cache at the root.
Dynamic imports: If you React.lazy() import Ant Design components, the cache isn't populated during the initial SSR pass. Use static imports for above-the-fold Ant Design components.
extractStyle called too early: If you call it before any Ant Design components render, the cache is empty. It must be called after the component tree renders.
TanStack Start dev mode: In dev, SSR is sometimes disabled or uses a different path. Test with npm run build && npm run start.

Community example

There's a community starter that demonstrates this exact pattern:

Repo: tanstack-start-antd-starter (search GitHub — it's not official but maintained by the community)

If you want me to turn this into a minimal reproduction repo with a single Button, Modal, and Table (the three most style-heavy Ant Design components), I can share it. The key is always: one cache, extract after render, inject into Document head.

Are you seeing the flicker on initial page load, on client-side navigation (<Link>), or both? That affects whether it's a pure SSR issue or if there's also a client-side routing cache problem.

0 replies

ship-tanstack · 2026-05-30T13:26:26Z

ship-tanstack
May 30, 2026

Hey @createdbymahmood ??

Great question - we actually ran into the same flicker issues when building a production admin dashboard with Ant Design 6 + TanStack Start. Here's what worked for us:

Our Solution: Static Extract + App-level ConfigProvider

Instead of trying to force emotion's runtime SSR hydration, we went with a simpler approach that avoids the flicker entirely:

1. Wrap the app with a single ConfigProvider at the root route level, with all theme tokens defined upfront.

2. Prefer Ant Design's static CSS extraction over runtime emotion when possible. In Ant Design 6, many components support static CSS which eliminates the SSR hydration mismatch.

3. Use Tailwind CSS v4 for layout utilities alongside Ant Design components - this reduces the number of emotion-generated styles that need SSR hydration.

Working Reference

If it helps, we open-sourced the full implementation as a template: ship-tanstack/dashboard-01 - A production-ready admin dashboard with TanStack Start + Ant Design 6 + Recharts.

It includes SSR-ready Ant Design setup, 6 dashboard screens, file-based routing, and Cloudflare Workers deployment. Feel free to fork it as a starting point!

Building TanStack templates at tanstackship.com - happy to help if you run into more issues.

0 replies

ship-tanstack · 2026-05-30T13:26:54Z

ship-tanstack
May 30, 2026

Hi @mirumodapon! This confused me at first too. Here's how it works in practice:

**
outer.ts** defines and exports the router instance itself. It's used by the build tool (Vite plugin) to generate the route tree during development, and by the server entry point at runtime.

**
outeTree.gen.ts** is the auto-generated file that the TanStack Router Vite plugin creates based on your file structure under src/routes/. You should never edit this manually.

__root.tsx (inside src/routes/) is where you define the root layout, providers, and head tags.

The typical flow is:

You create files in src/routes/ (e.g., src/routes/index.tsx, src/routes/about.tsx)
The Vite plugin auto-generates
outeTree.gen.ts

outer.ts imports the route tree and creates the router instance
4. Your __root.tsx uses to render child routes

If you want to see a real project structure in action, our TanStack Start templates use this exact pattern - feel free to reference them as working examples.

Building production-ready TanStack templates at tanstackship.com.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

How to properly use Ant Design with TanStack Start #4052

Uh oh!

{{title}}

Uh oh!

Replies: 4 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

How to properly use Ant Design with TanStack Start #4052

Uh oh!

createdbymahmood Apr 25, 2025

Has anyone successfully set up Ant Design with TanStack Start?

Feature Request-ish:

Replies: 4 comments · 1 reply

Uh oh!

MukundaKatta Apr 21, 2026

Uh oh!

kunKun-tx May 8, 2026

Uh oh!

x-tahosin Apr 25, 2026

The working setup

1. StyleProvider with SSR extraction

2. Server entry: extract and inject styles into HTML head

3. The correct architecture: single cache at root

Why this eliminates flicker

If you still see flicker after this

Community example

Uh oh!

ship-tanstack May 30, 2026

Our Solution: Static Extract + App-level ConfigProvider

Working Reference

Uh oh!

ship-tanstack May 30, 2026

createdbymahmood
Apr 25, 2025

Replies: 4 comments 1 reply

MukundaKatta
Apr 21, 2026

x-tahosin
Apr 25, 2026

1. `StyleProvider` with SSR extraction

ship-tanstack
May 30, 2026

ship-tanstack
May 30, 2026