fix(themes): RSC-safe initial-appearance subpath for getInitialAppearanceScript

itsprade · claude · itsprade · commit 99c254166a98 · 2026-05-15T16:37:44.000+05:30
The Next.js example's `app/layout.tsx` is a Server Component. Importing
`getInitialAppearanceScript` from the package root pulled in the full
client barrel, transitively `react-router`, which exports `useRouteError`
that doesn't exist in the React Server Components build — Turbopack RSC
bailed with "Export useRouteError doesn't exist in target module".

Fix: ship `getInitialAppearanceScript` as a leaf subpath
`@tailor-platform/app-shell/initial-appearance`. The source already has no
React / react-router imports (only `type` imports from `theme-context`
that are erased at compile time), so it's a ~1KB zero-runtime-dep entry —
safe to call from any RSC layout. Added to `vite.config.ts` build entries
and `package.json` exports. The top-level export remains for non-RSC
consumers; docs and the Next.js example use the leaf subpath.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/api/use-theme.md b/docs/api/use-theme.md
@@ -181,11 +181,11 @@ Use **`AppShell`**’s **`defaultFont`** prop for the initial value when nothing
 
 `ThemeProvider` writes **`data-theme`** / **`data-font`** to **`<html>`** from a **post-mount effect**. On SSR'd apps that creates a flash of the default palette before the stored preference is applied, plus a React hydration warning.
 
-The package exports **`getInitialAppearanceScript()`** which returns a tiny script string consumers inline in **`<head>`** so the stored preference is applied **before first paint**:
+The package exports **`getInitialAppearanceScript()`** which returns a tiny script string consumers inline in **`<head>`** so the stored preference is applied **before first paint**. Import from the leaf subpath **`@tailor-platform/app-shell/initial-appearance`** — it's a zero-React-dep entry, safe to call from Next.js Server Components / RSC.
 
 ```tsx
 // app/layout.tsx (Next.js App Router)
-import { getInitialAppearanceScript } from "@tailor-platform/app-shell";
+import { getInitialAppearanceScript } from "@tailor-platform/app-shell/initial-appearance";
 
 export default function RootLayout({ children }) {
   return (
diff --git a/examples/nextjs-app/src/app/layout.tsx b/examples/nextjs-app/src/app/layout.tsx
@@ -1,6 +1,6 @@
 import type { Metadata } from "next";
 import { Geist, Geist_Mono } from "next/font/google";
-import { getInitialAppearanceScript } from "@tailor-platform/app-shell";
+import { getInitialAppearanceScript } from "@tailor-platform/app-shell/initial-appearance";
 import "@tailor-platform/app-shell/styles";
 import "./globals.css";
 
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -33,6 +33,10 @@
       "types": "./dist/app-shell.d.ts",
       "default": "./dist/app-shell.js"
     },
+    "./initial-appearance": {
+      "types": "./dist/initial-appearance.d.ts",
+      "default": "./dist/initial-appearance.js"
+    },
     "./vite-plugin": {
       "types": "./dist/vite-plugin.d.ts",
       "default": "./dist/vite-plugin.js"
diff --git a/packages/core/vite.config.ts b/packages/core/vite.config.ts
@@ -37,6 +37,9 @@ export default defineConfig(({ mode }) => ({
       entry: {
         "app-shell": "src/index.ts",
         "vite-plugin": "src/vite-plugin.ts",
+        // Leaf entry for Server-Component-safe usage: pure, zero React / react-router
+        // imports, so Next.js RSC can call it from `app/layout.tsx`.
+        "initial-appearance": "src/lib/initial-appearance.ts",
       },
       formats: ["es"],
     },
