@codefast/theme 0.3.13 → 0.3.14-canary.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +196 -131
- package/dist/adapters/tanstack-start/server.d.mts +3 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# @codefast/theme
|
|
2
2
|
|
|
3
|
+
## 0.3.14-canary.1
|
|
4
|
+
|
|
5
|
+
## 0.3.14-canary.0
|
|
6
|
+
|
|
7
|
+
### Patch Changes
|
|
8
|
+
|
|
9
|
+
- [`b728f3e`](https://github.com/codefastlabs/codefast/commit/b728f3e74c94ce448b48b2cfd3e7a119b9649cb1) Thanks [@thevuong](https://github.com/thevuong)! - docs(theme): update README.md for clarity and structure
|
|
10
|
+
|
|
11
|
+
- [`b44597c`](https://github.com/codefastlabs/codefast/commit/b44597c9ec3a121a707aa269d7f68550ae1da72a) Thanks [@thevuong](https://github.com/thevuong)! - docs: enhance type annotations and comments for clarity across multiple files
|
|
12
|
+
|
|
13
|
+
- [`8109f4e`](https://github.com/codefastlabs/codefast/commit/8109f4e1f8186b91c296d25d640594b43493cdef) Thanks [@thevuong](https://github.com/thevuong)! - docs: update README.md files across packages for consistency and clarity
|
|
14
|
+
|
|
3
15
|
## 0.3.13
|
|
4
16
|
|
|
5
17
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @codefast/theme
|
|
2
2
|
|
|
3
|
-
Theme management for React 19
|
|
3
|
+
Theme management for React 19 — SSR-safe `system` resolution, optimistic updates, cross-tab sync, and a drop-in TanStack Start adapter.
|
|
4
4
|
|
|
5
5
|
[](https://github.com/codefastlabs/codefast/actions/workflows/release.yml)
|
|
6
6
|
[](https://www.npmjs.com/package/@codefast/theme)
|
|
@@ -8,80 +8,75 @@ Theme management for React 19 applications with optimistic updates, cross-tab sy
|
|
|
8
8
|
[](https://bundlephobia.com/package/@codefast/theme)
|
|
9
9
|
[](https://opensource.org/licenses/MIT)
|
|
10
10
|
|
|
11
|
+
---
|
|
12
|
+
|
|
11
13
|
## Table of Contents
|
|
12
14
|
|
|
13
|
-
- [
|
|
15
|
+
- [Why @codefast/theme](#why-codefasttheme)
|
|
16
|
+
- [Requirements](#requirements)
|
|
14
17
|
- [Installation](#installation)
|
|
15
18
|
- [Quick Start](#quick-start)
|
|
16
|
-
- [
|
|
19
|
+
- [Recipes](#recipes)
|
|
17
20
|
- [TanStack Start](#tanstack-start)
|
|
18
|
-
- [
|
|
19
|
-
- [Theme
|
|
20
|
-
- [SSR and FOUC
|
|
21
|
+
- [Client-only React (localStorage)](#client-only-react-localstorage)
|
|
22
|
+
- [Theme toggle](#theme-toggle)
|
|
23
|
+
- [SSR and FOUC prevention](#ssr-and-fouc-prevention)
|
|
21
24
|
- [API Reference](#api-reference)
|
|
22
|
-
- [ThemeProvider](#themeprovider)
|
|
23
|
-
- [useTheme](#usetheme)
|
|
24
|
-
- [ThemeScript](#themescript)
|
|
25
|
-
- [resolveTheme](#resolvetheme)
|
|
26
|
-
- [
|
|
25
|
+
- [`<ThemeProvider>`](#themeprovider)
|
|
26
|
+
- [`useTheme()`](#usetheme)
|
|
27
|
+
- [`<ThemeScript>`](#themescript)
|
|
28
|
+
- [`resolveTheme()`](#resolvetheme)
|
|
29
|
+
- [`getSystemTheme()` / `applyTheme()` / `disableAnimation()`](#getsystemtheme--applytheme--disableanimation)
|
|
30
|
+
- [`themes`, `themeSchema`, and defaults](#themes-themeschema-and-defaults)
|
|
31
|
+
- [TanStack Start adapter (`@codefast/theme/start`)](#tanstack-start-adapter-codefastthemestart)
|
|
32
|
+
- [Package exports](#package-exports)
|
|
27
33
|
- [Contributing](#contributing)
|
|
28
34
|
- [License](#license)
|
|
29
35
|
- [Changelog](#changelog)
|
|
30
36
|
|
|
31
|
-
|
|
37
|
+
---
|
|
32
38
|
|
|
33
|
-
|
|
39
|
+
## Why @codefast/theme
|
|
34
40
|
|
|
35
|
-
|
|
41
|
+
`@codefast/theme` is a focused theme-state primitive built around the React 19 concurrent APIs. Drop it at the root of your app, persist the user's preference however you want, and let the hook and inline script keep the DOM in sync.
|
|
36
42
|
|
|
37
|
-
- **React 19
|
|
38
|
-
- **
|
|
39
|
-
- **Cross-tab
|
|
40
|
-
- **Optimistic
|
|
41
|
-
- **
|
|
42
|
-
- **
|
|
43
|
+
- **React 19 first.** Uses `useOptimistic`, `useSyncExternalStore`, and `useEffectEvent` to keep theme changes immediate, hydration-safe, and free of needless re-renders.
|
|
44
|
+
- **SSR-friendly.** A tiny inline `<ThemeScript>` runs before first paint so `system` never flashes the wrong appearance. Works with Client Hints (`Sec-CH-Prefers-Color-Scheme`) when you have them.
|
|
45
|
+
- **Cross-tab sync.** Theme changes propagate between tabs over `BroadcastChannel`.
|
|
46
|
+
- **Optimistic setters.** `setTheme(value)` updates the UI immediately and reverts automatically if persistence fails.
|
|
47
|
+
- **TanStack Start adapter.** `@codefast/theme/start` ships cookie-based persistence plus loader/server helpers. Everything else stays vanilla.
|
|
48
|
+
- **Tree-shakeable.** Side-effect-free ESM with granular subpaths; bring in only the pieces you use.
|
|
43
49
|
|
|
44
|
-
|
|
50
|
+
---
|
|
45
51
|
|
|
46
|
-
|
|
47
|
-
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
-
| `@codefast/theme` | `ThemeProvider`, `useTheme`, `ThemeScript`, `resolveTheme`, types, `themes`, defaults |
|
|
49
|
-
| `@codefast/theme/start` | `getRootThemeServerFn`, `getThemeServerFn`, `getSsrSystemThemeServerFn`, `setThemeServerFn`, `persistThemeCookie`, `RootThemeLoaderData` |
|
|
50
|
-
| `@codefast/theme/utils` | `getSystemTheme`, `applyTheme`, `disableAnimation`, `resolveTheme` |
|
|
51
|
-
| `@codefast/theme/core` | `ThemeContext`, `ThemeProvider`, `useTheme` |
|
|
52
|
-
| `@codefast/theme/script` | `ThemeScript` |
|
|
53
|
-
| `@codefast/theme/constants` | `DEFAULT_THEME`, `DEFAULT_RESOLVED_THEME`, `THEME_STORAGE_KEY`, … |
|
|
54
|
-
| `@codefast/theme/types` | `themeSchema`, types |
|
|
52
|
+
## Requirements
|
|
55
53
|
|
|
56
|
-
|
|
54
|
+
- React `^19` (and `react-dom`)
|
|
55
|
+
- TypeScript `>= 5.9` (recommended; the published types target ES2022)
|
|
56
|
+
- TanStack Start `^1` — only if you use `@codefast/theme/start`
|
|
57
57
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
58
|
+
All peers except `react` / `react-dom` are optional.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
## Installation
|
|
63
63
|
|
|
64
64
|
```bash
|
|
65
|
+
pnpm add @codefast/theme
|
|
66
|
+
# or
|
|
65
67
|
npm install @codefast/theme
|
|
68
|
+
# or
|
|
69
|
+
yarn add @codefast/theme
|
|
66
70
|
```
|
|
67
71
|
|
|
68
|
-
|
|
72
|
+
Peer dependencies:
|
|
69
73
|
|
|
70
74
|
```bash
|
|
71
75
|
pnpm add react react-dom
|
|
76
|
+
pnpm add @tanstack/react-start # only if using @codefast/theme/start
|
|
72
77
|
```
|
|
73
78
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
pnpm add @tanstack/react-start
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
**Requirements:**
|
|
81
|
-
|
|
82
|
-
- Node.js >= 24.0.0 (LTS)
|
|
83
|
-
- React >= 19.0.0
|
|
84
|
-
- TypeScript >= 5.9.2 (recommended)
|
|
79
|
+
---
|
|
85
80
|
|
|
86
81
|
## Quick Start
|
|
87
82
|
|
|
@@ -107,19 +102,23 @@ function Page() {
|
|
|
107
102
|
}
|
|
108
103
|
```
|
|
109
104
|
|
|
110
|
-
|
|
105
|
+
`theme` accepts `"light"`, `"dark"`, or `"system"`. `resolvedTheme` from `useTheme()` always narrows to `"light" | "dark"`.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Recipes
|
|
111
110
|
|
|
112
111
|
### TanStack Start
|
|
113
112
|
|
|
114
|
-
Server persistence
|
|
113
|
+
Server-side persistence lives in `@codefast/theme/start`. The shell keeps full control over `<html>` / `<head>` / `<body>` — the adapter only provides the loader data and cookie helpers.
|
|
115
114
|
|
|
116
115
|
```tsx
|
|
117
|
-
// routes/__root.tsx (
|
|
116
|
+
// routes/__root.tsx (adjust to your router setup)
|
|
118
117
|
import { HeadContent, Scripts, createRootRouteWithContext } from "@tanstack/react-router";
|
|
119
118
|
import { getRootThemeServerFn, getThemeServerFn, persistThemeCookie } from "@codefast/theme/start";
|
|
120
119
|
import { ThemeProvider, ThemeScript, resolveTheme } from "@codefast/theme";
|
|
121
120
|
|
|
122
|
-
export const Route = createRootRouteWithContext<
|
|
121
|
+
export const Route = createRootRouteWithContext<YourRouterContext>()({
|
|
123
122
|
loader: async () => getRootThemeServerFn(),
|
|
124
123
|
shellComponent: RootShell,
|
|
125
124
|
});
|
|
@@ -150,21 +149,29 @@ function RootShell({ children }: { children: React.ReactNode }) {
|
|
|
150
149
|
}
|
|
151
150
|
```
|
|
152
151
|
|
|
153
|
-
|
|
152
|
+
To keep cached HTML honest when serving `system`, advertise the Client Hint and add the right `Vary` header:
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
Accept-CH: Sec-CH-Prefers-Color-Scheme
|
|
156
|
+
Vary: Sec-CH-Prefers-Color-Scheme, Cookie
|
|
157
|
+
```
|
|
154
158
|
|
|
155
|
-
|
|
159
|
+
`syncThemeFromServer` re-reads the cookie once after mount and covers edge cases like duplicate-tab restores where the HTML is older than the cookie.
|
|
156
160
|
|
|
157
|
-
|
|
161
|
+
### Client-only React (localStorage)
|
|
162
|
+
|
|
163
|
+
For apps without a server framework, persist the theme in `localStorage`:
|
|
158
164
|
|
|
159
165
|
```tsx
|
|
160
166
|
import { ThemeProvider } from "@codefast/theme";
|
|
161
167
|
|
|
162
168
|
function App() {
|
|
163
|
-
const
|
|
169
|
+
const saved =
|
|
170
|
+
typeof window !== "undefined" ? (localStorage.getItem("theme") ?? "system") : "system";
|
|
164
171
|
|
|
165
172
|
return (
|
|
166
173
|
<ThemeProvider
|
|
167
|
-
theme={
|
|
174
|
+
theme={saved}
|
|
168
175
|
persistTheme={async (value) => {
|
|
169
176
|
localStorage.setItem("theme", value);
|
|
170
177
|
}}
|
|
@@ -175,21 +182,23 @@ function App() {
|
|
|
175
182
|
}
|
|
176
183
|
```
|
|
177
184
|
|
|
178
|
-
### Theme
|
|
179
|
-
|
|
180
|
-
Build a theme switcher using the `useTheme` hook and the `themes` constant:
|
|
185
|
+
### Theme toggle
|
|
181
186
|
|
|
182
187
|
```tsx
|
|
183
|
-
import {
|
|
188
|
+
import { themes, useTheme } from "@codefast/theme";
|
|
184
189
|
|
|
185
|
-
function
|
|
190
|
+
export function ThemeSelect() {
|
|
186
191
|
const { theme, setTheme, isPending } = useTheme();
|
|
187
192
|
|
|
188
193
|
return (
|
|
189
|
-
<select
|
|
190
|
-
{
|
|
191
|
-
|
|
192
|
-
|
|
194
|
+
<select
|
|
195
|
+
value={theme}
|
|
196
|
+
disabled={isPending}
|
|
197
|
+
onChange={(event) => setTheme(event.target.value as (typeof themes)[number])}
|
|
198
|
+
>
|
|
199
|
+
{themes.map((value) => (
|
|
200
|
+
<option key={value} value={value}>
|
|
201
|
+
{value[0].toUpperCase() + value.slice(1)}
|
|
193
202
|
</option>
|
|
194
203
|
))}
|
|
195
204
|
</select>
|
|
@@ -197,127 +206,183 @@ function ThemeToggle() {
|
|
|
197
206
|
}
|
|
198
207
|
```
|
|
199
208
|
|
|
200
|
-
|
|
209
|
+
`isPending` is `true` while the optimistic value differs from the persisted value — useful for disabling the control until persistence settles.
|
|
201
210
|
|
|
202
|
-
|
|
211
|
+
---
|
|
203
212
|
|
|
204
|
-
|
|
205
|
-
import { ThemeScript } from "@codefast/theme";
|
|
213
|
+
## SSR and FOUC prevention
|
|
206
214
|
|
|
207
|
-
|
|
208
|
-
<ThemeScript theme="system" />;
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
For Content Security Policy (CSP) environments, pass a `nonce` to both `ThemeScript` and `ThemeProvider`:
|
|
215
|
+
`<ThemeScript>` injects a tiny synchronous `<script>` into the document head. It runs before first paint, resolves `system` via `matchMedia`, and adds the appropriate class + `color-scheme` to `<html>`:
|
|
212
216
|
|
|
213
217
|
```tsx
|
|
214
|
-
<
|
|
215
|
-
<
|
|
216
|
-
|
|
217
|
-
</ThemeProvider>
|
|
218
|
+
<head>
|
|
219
|
+
<ThemeScript theme="system" />
|
|
220
|
+
</head>
|
|
218
221
|
```
|
|
219
222
|
|
|
223
|
+
The script removes any prior `light` / `dark` / `system` class on `<html>`, so it is safe to pre-render the markup with `suppressHydrationWarning`.
|
|
224
|
+
|
|
225
|
+
> **CSP note.** `<ThemeScript>` currently does not accept a `nonce`. If your CSP forbids inline scripts, either add a specific hash for the generated snippet or serve the same logic from a hashed static file. The `disableTransitionOnChange` option on `<ThemeProvider>` _does_ accept a `nonce` because it injects inline `<style>`.
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
220
229
|
## API Reference
|
|
221
230
|
|
|
222
|
-
### ThemeProvider
|
|
231
|
+
### `<ThemeProvider>`
|
|
223
232
|
|
|
224
|
-
Root provider
|
|
233
|
+
Root provider that wires together theme state, OS subscription, optimistic updates, and cross-tab broadcast.
|
|
225
234
|
|
|
226
235
|
```tsx
|
|
227
236
|
<ThemeProvider
|
|
228
|
-
theme=
|
|
237
|
+
theme={initialTheme}
|
|
238
|
+
ssrSystemTheme="light"
|
|
229
239
|
persistTheme={async (value) => {
|
|
230
|
-
/*
|
|
240
|
+
/* … */
|
|
231
241
|
}}
|
|
232
|
-
|
|
233
|
-
|
|
242
|
+
syncThemeFromServer={getThemeServerFn}
|
|
243
|
+
disableTransitionOnChange
|
|
244
|
+
nonce={cspNonce}
|
|
234
245
|
>
|
|
235
246
|
{children}
|
|
236
247
|
</ThemeProvider>
|
|
237
248
|
```
|
|
238
249
|
|
|
239
|
-
| Prop | Type | Default | Description
|
|
240
|
-
| --------------------------- | --------------------------------- | ------- |
|
|
241
|
-
| `theme` | `Theme` |
|
|
242
|
-
| `ssrSystemTheme` | `ResolvedTheme` |
|
|
243
|
-
| `
|
|
244
|
-
| `
|
|
245
|
-
| `disableTransitionOnChange` | `boolean` | `false` |
|
|
246
|
-
| `nonce` | `string` |
|
|
247
|
-
| `children` | `
|
|
250
|
+
| Prop | Type | Default | Description |
|
|
251
|
+
| --------------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
252
|
+
| `theme` | `Theme` | — | Initial preference (`"light"` / `"dark"` / `"system"`). Required. |
|
|
253
|
+
| `ssrSystemTheme` | `ResolvedTheme` | — | `"light"` or `"dark"` from the SSR request (e.g. Client Hints). Used as the server snapshot when preference is `system`. |
|
|
254
|
+
| `persistTheme` | `(value: Theme) => Promise<void>` | — | Runs whenever the user changes the theme. Rejects → optimistic update reverts automatically. |
|
|
255
|
+
| `syncThemeFromServer` | `() => Promise<Theme>` | — | Called once after mount to reconcile with the canonical source (e.g. cookie). Useful for stale HTML / duplicate-tab scenarios. |
|
|
256
|
+
| `disableTransitionOnChange` | `boolean` | `false` | Temporarily injects a style rule that disables CSS transitions while the theme swaps. Respects `prefers-reduced-motion`. |
|
|
257
|
+
| `nonce` | `string` | — | CSP nonce attached to the inline `<style>` element when `disableTransitionOnChange` is enabled. |
|
|
258
|
+
| `children` | `ReactNode` | — | Application content. |
|
|
259
|
+
|
|
260
|
+
`<ThemeProvider>` internally:
|
|
248
261
|
|
|
249
|
-
|
|
262
|
+
1. Tracks the persisted `theme` and an `optimisticTheme` for immediate feedback.
|
|
263
|
+
2. Subscribes to `(prefers-color-scheme: dark)` through `useSyncExternalStore` with a server snapshot backed by `ssrSystemTheme`.
|
|
264
|
+
3. Applies the resolved class + `color-scheme` to `<html>` whenever it changes.
|
|
265
|
+
4. Broadcasts the new value over `BroadcastChannel("theme-sync")` so other tabs stay in sync.
|
|
250
266
|
|
|
251
|
-
|
|
267
|
+
### `useTheme()`
|
|
252
268
|
|
|
253
269
|
```tsx
|
|
254
270
|
const { theme, resolvedTheme, setTheme, isPending } = useTheme();
|
|
255
271
|
```
|
|
256
272
|
|
|
257
|
-
|
|
|
258
|
-
| --------------- | --------------------------------- |
|
|
259
|
-
| `theme` | `Theme` | Current
|
|
260
|
-
| `resolvedTheme` | `ResolvedTheme` |
|
|
261
|
-
| `setTheme` | `(value: Theme) => Promise<void>` |
|
|
262
|
-
| `isPending` | `boolean` | `true` while
|
|
273
|
+
| Field | Type | Description |
|
|
274
|
+
| --------------- | --------------------------------- | ------------------------------------------------------------------------------- |
|
|
275
|
+
| `theme` | `Theme` | Current preference (reflects the optimistic value while a change is pending). |
|
|
276
|
+
| `resolvedTheme` | `ResolvedTheme` | `"light"` or `"dark"` — the value actually applied to `<html>`. |
|
|
277
|
+
| `setTheme` | `(value: Theme) => Promise<void>` | Update + persist. Resolves once persistence settles; on failure the UI reverts. |
|
|
278
|
+
| `isPending` | `boolean` | `true` while `optimisticTheme !== theme` (i.e. a change is in flight). |
|
|
263
279
|
|
|
264
|
-
|
|
280
|
+
Throws if called outside of a `<ThemeProvider>`.
|
|
265
281
|
|
|
266
|
-
|
|
282
|
+
### `<ThemeScript>`
|
|
283
|
+
|
|
284
|
+
Inline script for the document head that prevents FOUC.
|
|
267
285
|
|
|
268
286
|
```tsx
|
|
269
|
-
<ThemeScript theme=
|
|
287
|
+
<ThemeScript theme={theme} />
|
|
270
288
|
```
|
|
271
289
|
|
|
272
|
-
| Prop | Type
|
|
273
|
-
| ------- |
|
|
274
|
-
| `theme` | `Theme`
|
|
275
|
-
| `nonce` | `string` | Optional CSP nonce |
|
|
290
|
+
| Prop | Type | Description |
|
|
291
|
+
| ------- | ------- | -------------------------------------------------------------------------------- |
|
|
292
|
+
| `theme` | `Theme` | The preference to apply on initial render. `"system"` resolves via `matchMedia`. |
|
|
276
293
|
|
|
277
|
-
|
|
294
|
+
The component only emits a `<script>` with `dangerouslySetInnerHTML`. It does not currently accept a `nonce` — see the [CSP note](#ssr-and-fouc-prevention).
|
|
278
295
|
|
|
279
|
-
|
|
296
|
+
### `resolveTheme()`
|
|
280
297
|
|
|
281
|
-
```
|
|
298
|
+
```tsx
|
|
282
299
|
import { resolveTheme } from "@codefast/theme";
|
|
283
300
|
|
|
284
|
-
|
|
285
|
-
|
|
301
|
+
resolveTheme("dark"); // → "dark"
|
|
302
|
+
resolveTheme("system"); // client: OS preference via matchMedia
|
|
303
|
+
resolveTheme("system", "light"); // server: use Client Hints fallback
|
|
286
304
|
```
|
|
287
305
|
|
|
288
|
-
|
|
306
|
+
Returns a `ResolvedTheme` (`"light" | "dark"`). On the server without an `ssrSystemTheme`, falls back to `DEFAULT_RESOLVED_THEME` (`"dark"`).
|
|
307
|
+
|
|
308
|
+
### `getSystemTheme()` / `applyTheme()` / `disableAnimation()`
|
|
289
309
|
|
|
290
|
-
|
|
310
|
+
Granular helpers from `@codefast/theme/utils/system` and `@codefast/theme/utils/dom` for custom integrations:
|
|
291
311
|
|
|
292
|
-
|
|
293
|
-
|
|
312
|
+
| Function | Summary |
|
|
313
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
314
|
+
| `getSystemTheme()` | Returns `"light"` or `"dark"` using `matchMedia("(prefers-color-scheme: dark)")`. SSR-safe. |
|
|
315
|
+
| `applyTheme(resolved)` | Toggles `light` / `dark` / `system` classes on `<html>` and sets `color-scheme`. |
|
|
316
|
+
| `disableAnimation(nonce?)` | Returns a cleanup that re-enables CSS transitions. No-op when `prefers-reduced-motion: reduce` is set. |
|
|
294
317
|
|
|
295
|
-
|
|
318
|
+
### `themes`, `themeSchema`, and defaults
|
|
319
|
+
|
|
320
|
+
```tsx
|
|
321
|
+
import {
|
|
322
|
+
DEFAULT_RESOLVED_THEME, // "dark"
|
|
323
|
+
DEFAULT_THEME, // "system"
|
|
324
|
+
THEME_STORAGE_KEY, // "ui-theme" — cookie name used by the Start adapter
|
|
325
|
+
themeSchema, // Zod: z.enum(["light", "dark", "system"])
|
|
326
|
+
themes, // readonly ["light", "dark", "system"]
|
|
327
|
+
} from "@codefast/theme";
|
|
296
328
|
```
|
|
297
329
|
|
|
298
|
-
|
|
330
|
+
### TanStack Start adapter (`@codefast/theme/start`)
|
|
299
331
|
|
|
300
|
-
|
|
332
|
+
Server functions and helpers for cookie-backed persistence. All helpers are safe to import from both server and client module graphs — but only run from the appropriate context.
|
|
301
333
|
|
|
302
|
-
|
|
334
|
+
| Export | Kind | Purpose |
|
|
335
|
+
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
|
|
336
|
+
| `getRootThemeServerFn` | Server fn | Reads `{ theme, ssrSystemTheme }` from cookie + Client Hints. Use in your root route loader. |
|
|
337
|
+
| `getThemeServerFn` | Server fn | Reads only the stored theme. Stable reference — pass directly to `<ThemeProvider syncThemeFromServer>`. |
|
|
338
|
+
| `getSsrSystemThemeServerFn` | Server fn | Reads only the SSR system hint (Client-Hint value). |
|
|
339
|
+
| `setThemeServerFn` | Server fn | Writes the theme cookie from a server action. |
|
|
340
|
+
| `persistThemeCookie` | Helper | Drop-in `persistTheme` prop for `<ThemeProvider>`; wraps `setThemeServerFn`. |
|
|
341
|
+
| `RootThemeLoaderData` | Type | Shape of the loader payload returned by `getRootThemeServerFn`. |
|
|
303
342
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
## Package exports
|
|
346
|
+
|
|
347
|
+
The root `@codefast/theme` entry re-exports the common surface. Granular subpaths are available for bundler-aware tree-shaking.
|
|
348
|
+
|
|
349
|
+
| Subpath | Contents |
|
|
350
|
+
| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
351
|
+
| `@codefast/theme` | `ThemeProvider`, `useTheme`, `ThemeScript`, `resolveTheme`, types, `themes`, defaults |
|
|
352
|
+
| `@codefast/theme/start` | TanStack Start server functions + `persistThemeCookie`, `RootThemeLoaderData` |
|
|
353
|
+
| `@codefast/theme/adapters/tanstack-start/server` | Same exports as `/start`, reached via the full adapter path |
|
|
354
|
+
| `@codefast/theme/core/provider` | `ThemeProvider` |
|
|
355
|
+
| `@codefast/theme/core/use-theme` | `useTheme` |
|
|
356
|
+
| `@codefast/theme/core/context` | Raw `ThemeContext` for custom providers |
|
|
357
|
+
| `@codefast/theme/script/theme-script` | `ThemeScript` |
|
|
358
|
+
| `@codefast/theme/utils/system` | `getSystemTheme`, `resolveTheme` |
|
|
359
|
+
| `@codefast/theme/utils/dom` | `applyTheme`, `disableAnimation` |
|
|
360
|
+
| `@codefast/theme/constants` | `DEFAULT_THEME`, `DEFAULT_RESOLVED_THEME`, `THEME_STORAGE_KEY` |
|
|
361
|
+
| `@codefast/theme/types` | `Theme`, `ResolvedTheme`, `ThemeContextType`, `themes`, `themeSchema` |
|
|
362
|
+
|
|
363
|
+
See `package.json → exports` for the authoritative list.
|
|
307
364
|
|
|
308
|
-
|
|
309
|
-
pnpm test --filter=@codefast/theme
|
|
365
|
+
---
|
|
310
366
|
|
|
311
|
-
|
|
312
|
-
|
|
367
|
+
## Contributing
|
|
368
|
+
|
|
369
|
+
This package lives in the [Codefast monorepo](https://github.com/codefastlabs/codefast). From the repo root:
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
pnpm --filter @codefast/theme build
|
|
373
|
+
pnpm --filter @codefast/theme test
|
|
374
|
+
pnpm --filter @codefast/theme check-types
|
|
375
|
+
pnpm --filter @codefast/theme dev # watch-mode build
|
|
313
376
|
```
|
|
314
377
|
|
|
315
|
-
|
|
378
|
+
---
|
|
316
379
|
|
|
317
380
|
## License
|
|
318
381
|
|
|
319
|
-
|
|
382
|
+
[MIT](https://opensource.org/licenses/MIT) — see [`package.json`](./package.json).
|
|
383
|
+
|
|
384
|
+
---
|
|
320
385
|
|
|
321
386
|
## Changelog
|
|
322
387
|
|
|
323
|
-
See [CHANGELOG.md](./CHANGELOG.md) for
|
|
388
|
+
See [CHANGELOG.md](./CHANGELOG.md) for the full version history. Releases are also published on [npm](https://www.npmjs.com/package/@codefast/theme?activeTab=versions).
|
|
@@ -14,7 +14,9 @@ interface RootThemeLoaderData {
|
|
|
14
14
|
* {@link DEFAULT_RESOLVED_THEME}.
|
|
15
15
|
*/
|
|
16
16
|
ssrSystemTheme: ResolvedTheme;
|
|
17
|
-
/**
|
|
17
|
+
/**
|
|
18
|
+
* User preference from the httpOnly cookie: `light`, `dark`, or `system`.
|
|
19
|
+
*/
|
|
18
20
|
theme: Theme;
|
|
19
21
|
}
|
|
20
22
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codefast/theme",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.14-canary.1",
|
|
4
4
|
"description": "Theme management with React 19 features - optimistic updates, cross-tab sync, and SSR support",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dark-mode",
|
|
@@ -108,7 +108,7 @@
|
|
|
108
108
|
"jsdom": "^29.0.2",
|
|
109
109
|
"typescript": "^6.0.2",
|
|
110
110
|
"vitest": "^4.1.4",
|
|
111
|
-
"@codefast/typescript-config": "0.3.
|
|
111
|
+
"@codefast/typescript-config": "0.3.14-canary.1"
|
|
112
112
|
},
|
|
113
113
|
"peerDependencies": {
|
|
114
114
|
"@tanstack/react-start": "^1.0",
|