@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.
- package/README.md +153 -0
- 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.
|
|
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.
|
|
30
|
+
"@42-central/ui-react": "0.18.0"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
33
|
"@42/tsconfig": "workspace:*",
|