docs(dark-mode): add tanstack start guide#10396
Merged
shadcn merged 4 commits intoshadcn-ui:mainfrom Apr 21, 2026
Merged
Conversation
Contributor
|
@ramonclaudio is attempting to deploy a commit to the shadcn-pro Team on Vercel. A member of the Team first needs to authorize it. |
ramonclaudio
added a commit
to ramonclaudio/ramonclaudio.com
that referenced
this pull request
Apr 20, 2026
- document the canonical ScriptOnce + Context pattern for dark mode in TanStack Start - compare against the three open shadcn/ui PRs (#7173, #7490, #9096) and the Vite guide's open PRs - link to shadcn-ui/ui#10396 (the PR), ramonclaudio/tanstack-cn (starter repo), tanstack-cn + create-tanstack-cn (npm), and tanstack-cn.vercel.app (live demo)
ramonclaudio
added a commit
to ramonclaudio/patches
that referenced
this pull request
Apr 20, 2026
source patch for shadcn-ui/ui#10396 adding TanStack Start as a fifth dark mode guide alongside Next.js, Vite, Astro, and Remix. ScriptOnce + Context pattern with SSR-safe useState, suppressHydrationWarning, colorScheme, and OS preference listener. Three files: new MDX guide, index card, meta.json entry. Apply with git apply in a shadcn-ui/ui clone. Companion starter at ramonclaudio/tanstack-cn. Walkthrough at ramonclaudio.com/posts/tanstack-start-dark-mode.
Collaborator
|
I added Thank @ramonclaudio |
shadcn
added
the
area: roadmap
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Author
|
Yup, hardcoding |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a dark mode guide for TanStack Start, the only shadcn-CLI-supported framework without one.
This is the official TanStack pattern. Their
document-head-managementguide says:That guide ships with a
ThemeProviderexample wrapping<ScriptOnce>{themeScript}</ScriptOnce>around{children}, with alocalStorage+matchMediascript. tanstack.com runs the same pattern in production: an inline pre-hydration script that readslocalStorage, falls back tomatchMedia('(prefers-color-scheme: dark)'), and applies the class todocumentElement(tanstack.com/__root.tsxL107-L113).This PR is that recipe with three production additions:
useState(defaultTheme)instead of readinglocalStoragedirectly (so SSR and client match),document.documentElement.style.colorScheme(so native UI respects the theme), and aprefers-color-schemelistener for"system"mode.Same three-step shape as the Vite guide: provider, root layout, toggle. No server functions, no cookies, no third-party deps. Just
ScriptOnce+ React Context +localStorage.Note: TanStack's other doc,
integrate-shadcn-ui, is out of date. ItsThemeProviderinitializesuseStatefromlocalStoragedirectly (L441-L443), which throws under SSR. This PR aligns shadcn's docs with the canonicaldocument-head-managementrecipe instead.Why not adapt one of the existing guides?
localStorageinuseState, throws under SSR. Also missingcolorScheme, the system preference listener, and FOUC prevention (open PRs Update vite.mdx to fix dark mode toggle code #7599, docs(dark-mode-vite): add localStorage checks to prevent errors in Ta… #8969, docs(vite): add FOUC prevention script to dark mode guide #10132 try to patch these in the Vite guide itself).next-themesworks in any React app, but pulling a Next-named runtime dep into a non-Next guide is misleading when the framework's own primitive (ScriptOnce) already exists.remix-themesis bound to Remix's session loader and<PreventFlashOnWrongTheme>, doesn't transfer to Start.MutationObserveron<html>), no React provider lifecycle to mirror.What's been tried
@shadcn commented on #7173 and #7490 asking how they compare. All four, verified against the file diffs (and the
tanstack-theme-kitsource for #9096):ScriptOncetheme === 'system'<script>)prefers-color-schemelistenercolorSchemesuppressHydrationWarningcreateServerFncreateServerFnlocalStoragevia librarylocalStoragetanstack-theme-kitapps/v4/apps/www/)apps/www/)#7173 and #7490 use cookies plus a
createServerFn, so the server renders the class directly on<html>(nosuppressHydrationWarningneeded). #7173 has no system mode (cookie defaults to"light"). #7490 adds system mode but only firesScriptOncewhen the stored value is"system". Neither setscolorSchemeor listens for OS changes.#9096 wraps
tanstack-theme-kit, which does most of the right things at the cost of a runtime dep and a custom inline<script>rather thanScriptOnce.#7055 (March 2025) closed with "use next-themes" after a commenter hit
localStorage is not definedusing the Vite guide.Sources
ScriptOncesource:packages/react-router/src/ScriptOnce.tsx(21 lines: server-only at L9, CSP nonce at L15, self-removal at L17)document-head-management.mdL234-L324tanstack.com/__root.tsxL107-L113integrate-shadcn-ui.mdL410-L484examples/react/start-basic/src/routes/__root.tsx