windrunner 1.0.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/LICENSE +15 -0
- package/README.md +233 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.esm.js +3534 -0
- package/dist/index.js +3563 -0
- package/dist/index.min.js +40 -0
- package/package.json +57 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bigetion
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
10
|
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
11
|
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
12
|
+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
13
|
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
14
|
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
15
|
+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
# windrunner
|
|
2
|
+
|
|
3
|
+
Zero-config Tailwind v4 runtime for the browser. Compile utility classes on-demand — no build step, no PostCSS, no config file.
|
|
4
|
+
|
|
5
|
+
Drop a `<script>` tag and start using Tailwind classes anywhere.
|
|
6
|
+
|
|
7
|
+
## How it works
|
|
8
|
+
|
|
9
|
+
Instead of generating a full CSS bundle upfront, `windrunner` scans the DOM for class names and compiles only the CSS rules actually used — then injects them into a `<style>` tag in `<head>`. A `MutationObserver` watches for DOM changes and compiles new classes as they appear.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
Page loads → scan DOM → compile used classes → inject <style>
|
|
13
|
+
↑ |
|
|
14
|
+
MutationObserver detects new classes ←─────────────┘
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install windrunner
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Usage
|
|
24
|
+
|
|
25
|
+
### Drop-in script (zero config)
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
<script type="module">
|
|
29
|
+
import { windrunner } from "windrunner";
|
|
30
|
+
windrunner({ autoStart: true });
|
|
31
|
+
</script>
|
|
32
|
+
|
|
33
|
+
<div class="flex items-center gap-4 p-6 bg-blue-50 rounded-xl">
|
|
34
|
+
<h1 class="text-2xl font-bold text-slate-900">Hello</h1>
|
|
35
|
+
<button class="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 transition-colors duration-200">
|
|
36
|
+
Click me
|
|
37
|
+
</button>
|
|
38
|
+
</div>
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### CDN
|
|
42
|
+
|
|
43
|
+
```html
|
|
44
|
+
<script type="module">
|
|
45
|
+
import { windrunner } from "https://cdn.jsdelivr.net/npm/windrunner@1.0.0/dist/index.min.js";
|
|
46
|
+
windrunner({ autoStart: true });
|
|
47
|
+
</script>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### React / Vue
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
import { useEffect } from "react";
|
|
54
|
+
import { windrunner } from "windrunner";
|
|
55
|
+
|
|
56
|
+
export default function App() {
|
|
57
|
+
useEffect(() => {
|
|
58
|
+
const wind = windrunner({ id: "my-app", autoStart: true });
|
|
59
|
+
return () => wind.disconnect();
|
|
60
|
+
}, []);
|
|
61
|
+
|
|
62
|
+
return (
|
|
63
|
+
<main className="min-h-screen bg-slate-50 p-8">
|
|
64
|
+
<h1 className="text-3xl font-bold text-slate-900">React + Windrunner</h1>
|
|
65
|
+
</main>
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Manual control
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
import { createWindrunner, compileClass } from "windrunner";
|
|
74
|
+
|
|
75
|
+
// Compile a single class to a CSS rule string
|
|
76
|
+
const css = compileClass("md:hover:bg-blue-500");
|
|
77
|
+
// → '@media (min-width: 768px) { .md\\:hover\\:bg-blue-500:hover { background-color: oklch(...); } }'
|
|
78
|
+
|
|
79
|
+
// Create an instance with full control
|
|
80
|
+
const wind = createWindrunner({ id: "my-app" });
|
|
81
|
+
wind.processClassList("flex items-center justify-between gap-4");
|
|
82
|
+
wind.scan(); // scan entire document
|
|
83
|
+
wind.observe(); // start watching DOM mutations
|
|
84
|
+
wind.disconnect(); // stop watching
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## API
|
|
88
|
+
|
|
89
|
+
### `windrunner(options?)`
|
|
90
|
+
|
|
91
|
+
Auto-start mode. Scans DOM and begins observing immediately.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
windrunner({
|
|
95
|
+
id?: string, // style tag id, default: "tailwind-runtime-css"
|
|
96
|
+
autoStart?: boolean, // default: true
|
|
97
|
+
theme?: { // override/extend theme values
|
|
98
|
+
extend: {
|
|
99
|
+
colors: { brand: "#ff6b6b" }
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
})
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### `createWindrunner(options?)`
|
|
106
|
+
|
|
107
|
+
Returns a runtime instance with manual control methods:
|
|
108
|
+
|
|
109
|
+
| Method | Description |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `start()` | Scan DOM + start observer (waits for DOMContentLoaded) |
|
|
112
|
+
| `scan(root?)` | One-time scan of all `[class]` elements |
|
|
113
|
+
| `observe(root?)` | Start MutationObserver |
|
|
114
|
+
| `processClassName(cls)` | Compile + inject one class |
|
|
115
|
+
| `processClassList(str)` | Compile + inject space-separated classes |
|
|
116
|
+
| `processElement(el)` | Compile all classes on a DOM element |
|
|
117
|
+
| `flush()` | Force-flush pending element queue |
|
|
118
|
+
| `disconnect()` | Stop observer, cleanup |
|
|
119
|
+
| `getCacheSize()` | Number of compiled classes in cache |
|
|
120
|
+
| `getInsertedRuleCount()` | Number of CSS rules injected |
|
|
121
|
+
|
|
122
|
+
### `compileClass(className, options?)`
|
|
123
|
+
|
|
124
|
+
Compile a single class name to a CSS rule string. Works in Node.js too.
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
compileClass("hover:text-blue-500")
|
|
128
|
+
// → '.hover\\:text-blue-500:hover { color: oklch(0.623 0.214 259.8); }'
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### `parseClass(className, screens?, containers?)`
|
|
132
|
+
|
|
133
|
+
Parse a class name into its parts:
|
|
134
|
+
|
|
135
|
+
```js
|
|
136
|
+
parseClass("md:hover:mt-4", { md: "768px" })
|
|
137
|
+
// → { original: "md:hover:mt-4", baseToken: "mt-4", variants: ["hover"],
|
|
138
|
+
// breakpoint: "md", containerBreakpoint: null, important: false, starting: false }
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Supported utilities
|
|
142
|
+
|
|
143
|
+
Full Tailwind v4 coverage including:
|
|
144
|
+
|
|
145
|
+
- **Layout** — display, position, overflow, z-index, visibility, float, clear, aspect-ratio, columns, isolation, object-fit/position
|
|
146
|
+
- **Spacing** — margin, padding, gap, space (with negative values)
|
|
147
|
+
- **Sizing** — width, height, min/max-w/h, size-*
|
|
148
|
+
- **Flexbox** — flex, grow, shrink, basis, direction, wrap, align, justify, place
|
|
149
|
+
- **Grid** — grid-cols/rows, col/row-span, grid-flow, auto-cols/rows, place-*
|
|
150
|
+
- **Typography** — font-size, font-weight, line-height, letter-spacing, text-align, text-color, text-decoration, text-transform, text-overflow, whitespace, word-break, list-style
|
|
151
|
+
- **Colors** — all OKLCH P3 Tailwind v4 palette + mauve/olive/mist/taupe, opacity modifier (`bg-blue-500/50`)
|
|
152
|
+
- **Backgrounds** — bg-color, bg-linear-to-* (v4), gradient stops (from/via/to), bg-size/position/repeat/attachment/clip/origin
|
|
153
|
+
- **Borders** — border-width/style/color/radius (all sides + logical)
|
|
154
|
+
- **Effects** — shadow, opacity, inset-shadow-* (v4), ring, inset-ring-* (v4)
|
|
155
|
+
- **Transforms** — rotate, scale, translate (2D + 3D), skew, origin, perspective, backface, transform-style
|
|
156
|
+
- **Filters** — blur, brightness, contrast, grayscale, hue-rotate, invert, saturate, sepia, drop-shadow, all backdrop-* variants
|
|
157
|
+
- **Transitions** — transition, duration, delay, ease
|
|
158
|
+
- **Animations** — animate-spin/ping/pulse/bounce
|
|
159
|
+
- **Interactivity** — cursor, select, resize, outline, pointer-events, appearance, touch-action, scroll-behavior, scroll-margin/padding, will-change
|
|
160
|
+
- **v4 New** — field-sizing-*, mask-*, @container, @container breakpoints (@sm: @md: etc.)
|
|
161
|
+
- **Variants** — hover, focus, focus-visible, active, visited, disabled, dark, group-hover/focus, peer-*, not-hover/focus/disabled, in-hover, starting: (@starting-style), first/last/odd/even, before/after, placeholder
|
|
162
|
+
|
|
163
|
+
## Custom theme
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
windrunner({
|
|
167
|
+
autoStart: true,
|
|
168
|
+
theme: {
|
|
169
|
+
extend: {
|
|
170
|
+
colors: {
|
|
171
|
+
brand: {
|
|
172
|
+
50: "oklch(0.97 0.01 200)",
|
|
173
|
+
500: "oklch(0.55 0.18 200)",
|
|
174
|
+
900: "oklch(0.25 0.10 200)",
|
|
175
|
+
}
|
|
176
|
+
},
|
|
177
|
+
spacing: {
|
|
178
|
+
18: "4.5rem",
|
|
179
|
+
128: "32rem",
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
});
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Preventing FOUC
|
|
187
|
+
|
|
188
|
+
Because windrunner compiles CSS at runtime, browsers may briefly render unstyled content before styles are injected (Flash of Unstyled Content). The recommended fix:
|
|
189
|
+
|
|
190
|
+
```html
|
|
191
|
+
<head>
|
|
192
|
+
<!-- 1. Hide the page before styles are ready -->
|
|
193
|
+
<style>html { opacity: 0; transition: opacity 0.2s ease; }</style>
|
|
194
|
+
|
|
195
|
+
<!-- 2. Reveal after windrunner finishes its first scan -->
|
|
196
|
+
<script type="module">
|
|
197
|
+
import { windrunner } from "windrunner";
|
|
198
|
+
windrunner({
|
|
199
|
+
autoStart: true,
|
|
200
|
+
onReady: () => document.documentElement.style.opacity = "1",
|
|
201
|
+
});
|
|
202
|
+
</script>
|
|
203
|
+
</head>
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The `onReady` callback fires after the initial DOM scan completes and CSS rules are injected, ensuring the page is fully styled before it becomes visible. The `transition` gives a smooth 200ms fade-in instead of an abrupt pop.
|
|
207
|
+
|
|
208
|
+
## Preflight
|
|
209
|
+
|
|
210
|
+
windrunner injects a CSS reset (based on Tailwind's preflight) automatically. To opt out:
|
|
211
|
+
|
|
212
|
+
```js
|
|
213
|
+
windrunner({ autoStart: true, preflight: false });
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## vs Tailwind Play CDN
|
|
217
|
+
|
|
218
|
+
| | windrunner | Tailwind Play CDN |
|
|
219
|
+
|---|---|---|
|
|
220
|
+
| Size | ~78 KB min | ~350 KB |
|
|
221
|
+
| Dependencies | 0 | 0 |
|
|
222
|
+
| Tailwind version | v4 | v4 |
|
|
223
|
+
| Works in Node.js | ✓ (compile only) | ✗ |
|
|
224
|
+
| Custom theme | ✓ | ✓ |
|
|
225
|
+
| Arbitrary values | ✓ | ✓ |
|
|
226
|
+
| Preflight | ✓ | ✓ |
|
|
227
|
+
| FOUC prevention | ✓ (onReady) | ✗ |
|
|
228
|
+
| Plugins | ✗ | ✓ |
|
|
229
|
+
| Full utility coverage | ✓ | ✓ |
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
ISC
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
export interface WindrunnerOptions {
|
|
2
|
+
id?: string;
|
|
3
|
+
autoStart?: boolean;
|
|
4
|
+
preflight?: boolean;
|
|
5
|
+
compatMode?: "none" | "full";
|
|
6
|
+
compatStyleId?: string;
|
|
7
|
+
compatGenerateCss?: (options: Record<string, any>) => string;
|
|
8
|
+
theme?: Record<string, any>;
|
|
9
|
+
onReady?: () => void;
|
|
10
|
+
[key: string]: any;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export interface Runtime {
|
|
14
|
+
processClassName(className: string): string | undefined;
|
|
15
|
+
processClassList(classList: string | string[] | ArrayLike<string>): string[];
|
|
16
|
+
processElement(el: Element | null): void;
|
|
17
|
+
scan(root?: Document | Element): void;
|
|
18
|
+
observe(root?: Element): void;
|
|
19
|
+
flush(): void;
|
|
20
|
+
start(): void;
|
|
21
|
+
disconnect(): void;
|
|
22
|
+
isCompatLoaded(): boolean;
|
|
23
|
+
getCacheSize(): number;
|
|
24
|
+
getInsertedRuleCount(): number;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function createWindrunner(options?: WindrunnerOptions): Runtime;
|
|
28
|
+
export function compileRuntimeClassNameWithContext(className: string, context: any): string;
|
|
29
|
+
export function compileClass(className: string, options?: any): string;
|
|
30
|
+
export function parseClass(className: string, screens?: Record<string,string>, containers?: Record<string,string>): { original: string; baseToken: string; variants: string[]; breakpoint: string | null; containerBreakpoint: string | null; important: boolean; starting: boolean } | null;
|
|
31
|
+
|
|
32
|
+
declare function windrunner(options?: WindrunnerOptions): Runtime;
|
|
33
|
+
export default windrunner;
|