@42-central/vite-plugin-theme 0.17.0 → 0.18.0

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.
Files changed (2) hide show
  1. package/README.md +153 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,153 @@
1
+ <p align="center">
2
+ <img alt="@42-central/vite-plugin-theme" src="https://shieldcn.dev/header/dots.svg?title=Vite+Plugin+Theme&subtitle=Flash-free+theme+init+for+Vite&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAMgAAADIBAMAAABfdrOtAAAAMFBMVEUAAAD%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F87TQQwAAAAD3RSTlMAAw4fKzNGVm%2BMn73c6vz7344aAAACqklEQVR42u3ZMWsUQRjG8ed9jaA2N5fWQswnEMVG1I9gpXZKvsGdnVZ3VpdClBQi2KlgI5b2fgobI3baOXOI3mJgx5Bb8Hb21tkwN2%2BMef%2BQIrs7PPyyaY6DpmmapmmapmmHnUH%2BiDbCMG89vH4xvHC%2BM%2BTqp6APNL%2FxOLzxKLzwlQBGPPr%2BaiPoeQ%2F7hcSzjScNuo30rpzz1ju4%2Bc9es22Hee7Pde%2B929p7cvGa9egWnfhs%2FWKl3zTYzzyxtRsFrvt65YwA7gQxWGxavHBY1nTLYFnc4Y28nGIxbx70sCx%2F%2BiFiI90h222QXnwkHeJaRgQgYAEIWAACFoCABSBgAQhYAAIWgIAFIGABCFgAAhaAgAUgYAEIWAACFoCABSDgdMiZGAScDnkWg4DTIfdcdEQAAhaAgBMh1AECToOgCwScBkEIMS0jKZDdEOLQMXOt9LXsjLC8C%2BHRgQ2O%2FqCun0eGBp2ik7Z5NBUSZu42jirkH4P8lIBsKkQhhwwpJCBjhShEIX%2BDWAHIN4Xov9YRfiMSEF9QP1IKpGqIlUFMC6T8dflWpJvV0Rvh3%2BBLACGqnhyFkNLH2qXgm6Aq%2Bz6ETKjtIzYiebRFrv7rbAiAkbXefWQfodmoGskOAeeFjF01khPiTe4RKsZT5B7pTbzJPULFcA4BC0DAAhCwAAQsAAHng1iTe4SKASEYyQBxJhjJCwELQMACELAABCwAAQtAwAIQcDZIOOJtrCQI1gCgv1rIaGrQkHx8E%2ButPxDEoDHiXt%2BOdedAb2QKNCXUj7SOJAg4%2Bb3HIWCsuGKA7CN%2B4gzC1rDSzKkhsOIR9%2FQd6pFHvdInS3Z20CFGUtSPZZAs8VZAAuiIjuiIjuiIjuiIjhyfEVvLIUN8KQxHtX6QgaZpmqZpmqZpmvbf9xsJbA7rTAka4wAAAABJRU5ErkJggg%3D%3D&mode=dark&font=fira-code">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@42-central/vite-plugin-theme"><img src="https://shieldcn.dev/npm/v/@42-central/vite-plugin-theme.svg" alt="npm version" /></a>
7
+ <a href="https://vite.dev"><img src="https://shieldcn.dev/badge/Vite-7_%7C_8-9135ff.svg?logo=vite" alt="Vite 7 | 8" /></a>
8
+ <img src="https://shieldcn.dev/badge/module-ESM--only-F7DF1E.svg" alt="ESM only" />
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="#install">Install</a> ·
13
+ <a href="#usage">Usage</a> ·
14
+ <a href="#options">Options</a> ·
15
+ <a href="https://42kit.dev/docs/theming"><strong>Theming docs ↗</strong></a>
16
+ </p>
17
+
18
+ ---
19
+
20
+ A Vite plugin that stops
21
+ [`@42-central/ui-react`](https://www.npmjs.com/package/@42-central/ui-react)
22
+ apps from flashing the wrong theme on load. It puts the kit's theme-init script
23
+ at the top of `<head>` in `index.html`, in both `vite dev` and `vite build`.
24
+
25
+ ## Why
26
+
27
+ `useTheme()` stores the visitor's `"light" | "dark" | "system"` choice and
28
+ keeps `data-theme` on `<html>` in sync. React only runs after first paint,
29
+ though. So without help, a dark-mode visitor sees one light frame before the
30
+ hook catches up.
31
+
32
+ In Next.js, `<ThemeScript />` covers that gap from the server render. A Vite
33
+ SPA has no server render, so the script has to sit in `index.html` and block
34
+ parsing. It also can't be `type="module"`, because Vite defers module
35
+ scripts, and the flash comes back. This plugin injects a classic inline
36
+ `<script>` through Vite's `transformIndexHtml` hook, so you never edit the
37
+ HTML by hand.
38
+
39
+ ## Install
40
+
41
+ Install it as a dev dependency, next to the kit:
42
+
43
+ ```bash
44
+ npm install -D @42-central/vite-plugin-theme
45
+ pnpm add -D @42-central/vite-plugin-theme
46
+ yarn add --dev @42-central/vite-plugin-theme
47
+ bun add --dev @42-central/vite-plugin-theme
48
+ ```
49
+
50
+ `vite` 7 or 8 is a peer dependency. The plugin builds its script with
51
+ `@42-central/ui-react`, which it lists as its own dependency. Keep both
52
+ packages on the same version: they are released together.
53
+
54
+ ## Usage
55
+
56
+ ```ts
57
+ // vite.config.ts
58
+ import { defineConfig } from "vite";
59
+ import react from "@vitejs/plugin-react";
60
+ import { themeInitPlugin } from "@42-central/vite-plugin-theme";
61
+
62
+ export default defineConfig({
63
+ plugins: [react(), themeInitPlugin()],
64
+ });
65
+ ```
66
+
67
+ Then read and change the theme from any component with the kit's hook:
68
+
69
+ ```tsx
70
+ import { useTheme } from "@42-central/ui-react";
71
+
72
+ export function ThemeToggle() {
73
+ const { resolvedTheme, setMode } = useTheme();
74
+ return (
75
+ <button onClick={() => setMode(resolvedTheme === "dark" ? "light" : "dark")}>
76
+ Toggle theme
77
+ </button>
78
+ );
79
+ }
80
+ ```
81
+
82
+ ## Options
83
+
84
+ `themeInitPlugin(options?)` takes the same options as the kit's
85
+ `buildThemeInitScript()`, plus `nonce`:
86
+
87
+ | Option | Type | Default | What it does |
88
+ | -------------------- | ---------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------- |
89
+ | `storageKey` | `string` | `"ui-theme"` | `localStorage` key that holds the stored mode. |
90
+ | `defaultColorScheme` | `"light" \| "dark" \| "system"` | `"system"` | Mode used when nothing is stored yet. |
91
+ | `forceColorScheme` | `"light" \| "dark"` | – | Pins the theme and ignores both storage and the OS preference. |
92
+ | `attribute` | `"data-theme" \| "class"`, or an array of them | `"data-theme"` | What to write on `<html>`: the `data-theme` attribute, a `.dark` class, or both. |
93
+ | `nonce` | `string` | – | CSP nonce added to the injected `<script>`. |
94
+
95
+ ### Keep it in sync with `useTheme()`
96
+
97
+ There is no provider holding this configuration, so the script and the hook
98
+ can't share it. Pass `storageKey`, `defaultColorScheme`, `forceColorScheme`
99
+ and `attribute` with the **same values** to the plugin and to every
100
+ `useTheme()` call. If they differ, the script and the hook disagree on first
101
+ load.
102
+
103
+ ```ts
104
+ // vite.config.ts
105
+ themeInitPlugin({ forceColorScheme: "dark", attribute: ["class", "data-theme"] });
106
+ ```
107
+
108
+ ```tsx
109
+ // anywhere in the app
110
+ useTheme({ forceColorScheme: "dark", attribute: ["class", "data-theme"] });
111
+ ```
112
+
113
+ A shared `const THEME_OPTIONS = { … }` imported by both files is the easiest
114
+ way to keep them aligned.
115
+
116
+ ### Content Security Policy
117
+
118
+ If your CSP blocks inline scripts, pass the nonce your server puts in the
119
+ `script-src` directive:
120
+
121
+ ```ts
122
+ themeInitPlugin({ nonce: "{{CSP_NONCE}}" });
123
+ ```
124
+
125
+ The value goes into the built `index.html` verbatim. Use whatever placeholder
126
+ your server or edge function replaces per request.
127
+
128
+ ## What it injects
129
+
130
+ One tag, first in `<head>`:
131
+
132
+ ```html
133
+ <head>
134
+ <script>/* ~600 bytes: read localStorage, resolve "system", set data-theme */</script>
135
+ <!-- the rest of your head -->
136
+ </head>
137
+ ```
138
+
139
+ The script runs once and registers no listeners. Following the OS preference
140
+ live after load is `useTheme()`'s job.
141
+
142
+ ## Not using Vite?
143
+
144
+ The [ui-react README](https://github.com/42staff/kit/blob/main/packages/react/README.md#vite-client-only-spa)
145
+ covers the alternatives: a prebuilt `theme-init.js` you copy into `public/`,
146
+ or pasting the output of `buildThemeInitScript()` by hand. Next.js apps use
147
+ `<ThemeScript />` instead.
148
+
149
+ ## Links
150
+
151
+ - [Theming docs](https://42kit.dev/docs/theming)
152
+ - [`@42-central/ui-react`](https://www.npmjs.com/package/@42-central/ui-react)
153
+ - [Source on GitHub](https://github.com/42staff/kit/tree/main/packages/vite-plugin-theme)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@42-central/vite-plugin-theme",
3
- "version": "0.17.0",
3
+ "version": "0.18.0",
4
4
  "description": "Vite plugin that injects @42/ui-react's anti-FOUC theme init script into index.html",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -27,7 +27,7 @@
27
27
  "vite": "^7.0.0 || ^8.0.0"
28
28
  },
29
29
  "dependencies": {
30
- "@42-central/ui-react": "0.17.0"
30
+ "@42-central/ui-react": "0.18.0"
31
31
  },
32
32
  "devDependencies": {
33
33
  "@42/tsconfig": "workspace:*",