tailwind.com 0.4.0 → 0.6.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 CHANGED
@@ -1,16 +1,19 @@
1
1
  # tailwind.com
2
2
 
3
3
  Tailwind CSS 4 in one executable file, with no Node.js. The same file
4
- runs on Linux, macOS, Windows, FreeBSD, NetBSD and OpenBSD, on x86_64 and
5
- aarch64.
4
+ runs on Linux, macOS, Windows, FreeBSD, NetBSD and OpenBSD, on x86_64
5
+ and aarch64 (ARM64).
6
6
 
7
7
  `tailwind.com` is a Tailwind CSS compiler in Rust, as one
8
8
  [Actually Portable Executable](https://justine.lol/ape.html) made with
9
9
  [Cosmopolitan Libc](https://github.com/jart/cosmopolitan), in the way of
10
- [BEAM.com](https://github.com/sntran/BEAM.com). It takes the place of:
10
+ [BEAM.com](https://github.com/sntran/BEAM.com). The build uses the
11
+ `cosmocc` of [sntran/cosmopolitan](https://github.com/sntran/cosmopolitan):
12
+ the official `cosmocc` 4.0.2 with the patches of BEAM.com, for Windows
13
+ on ARM64, macOS on arm64 and Linux on Rosetta. It takes the place of:
11
14
 
12
15
  - **The official `tailwindcss` program**: the same options, the same
13
- output, in one file of about 20 MB for all the systems and both CPUs.
16
+ output, in one file of about 23 MB for all the systems and both CPUs.
14
17
  - **The Hex package `tailwind`** in a Phoenix project: this repository
15
18
  is also an Erlang and Elixir project with the application name
16
19
  `tailwind`, the module `Tailwind`, and the tasks `mix tailwind` and
@@ -60,7 +63,7 @@ tailwind.com [--input input.css] [--output output.css] [--watch] [--poll=ms] [op
60
63
  In `mix.exs`, replace the Hex package `tailwind`:
61
64
 
62
65
  ```elixir
63
- {:tailwind, github: "sntran/tailwind.com", tag: "v0.4.0", runtime: Mix.env() == :dev}
66
+ {:tailwind, github: "sntran/tailwind.com", tag: "v0.6.0", runtime: Mix.env() == :dev}
64
67
  ```
65
68
 
66
69
  The modules of a release download the `tailwind.com` of that release.
@@ -158,7 +161,93 @@ const { status, stdout, stderr } = await runWasm(['-i', 'app.css'], { cwd: 'proj
158
161
  ```
159
162
 
160
163
  `import wasm from 'tailwind.com/tailwind.wasm'` gives the module itself,
161
- for another WASI host.
164
+ for another WASI host. In a bundler for the browser, the condition
165
+ `browser` gives `tailwind-browser.wasm` in its place.
166
+
167
+ ### In the browser
168
+
169
+ From 0.5.0, on a page, the package works as the Play CDN of Tailwind CSS: it builds
170
+ the CSS of the page from its classes, and builds again when they change.
171
+ The input CSS can be a file, as for a build on the disk:
172
+
173
+ ```html
174
+ <link rel="stylesheet" type="text/tailwindcss" href="/assets/app.css">
175
+ <script src="https://cdn.jsdelivr.net/npm/tailwind.com@0.6"></script>
176
+ ```
177
+
178
+ - The browser does not apply a stylesheet with the type
179
+ `text/tailwindcss`. The script gets the file, and the files of its
180
+ `@import`, `@reference`, `@plugin` and `@config` with a path (`./`,
181
+ `../` or `/`). It also gets the files that the JavaScript or
182
+ TypeScript of a plugin imports with a path. A path with no extension
183
+ finds the file as Node.js does (`./plugin` gives `./plugin.js`). The
184
+ CSS goes after the `<link>`, so it has the same place in the cascade as
185
+ the output of a build.
186
+ - The CSS is the same as the output of a build of the same files on the
187
+ disk, for the classes of the page. A test in CI compares the two.
188
+ - To build on the disk later, remove the `<script>`, remove `type`, and
189
+ set `href` to the output of the build:
190
+ `<link rel="stylesheet" href="/assets/app.out.css">`.
191
+ - Each second, while the page is visible, the script gets the files of
192
+ the site again, and builds again when one changes. A server with ETag
193
+ or Last-Modified answers 304, so this is small. A change of `href` (a
194
+ live reload) gets the files at once.
195
+
196
+ The input CSS can also be in the page, as for the Play CDN:
197
+
198
+ ```html
199
+ <script src="https://cdn.jsdelivr.net/npm/tailwind.com@0.6"></script>
200
+ <style type="text/tailwindcss">
201
+ @plugin "@tailwindcss/typography";
202
+ @theme { --color-brand: #0d9488; }
203
+ </style>
204
+ ```
205
+
206
+ - A path in the `<style>` (`@import "./extra.css"`) finds the file from
207
+ the URL of the page.
208
+ - With no `@import`, `@import "tailwindcss";` comes first. The CSS is
209
+ the same as the CSS of the browser build of Tailwind CSS
210
+ (`@tailwindcss/browser`). A test in CI compares the two.
211
+ - The plugins in the program work with `@plugin`:
212
+ `@tailwindcss/typography`, `@tailwindcss/forms` and
213
+ `@tailwindcss/aspect-ratio`.
214
+ - After each build, the document gets the event `tailwind.com:build`.
215
+ - The program for a browser (`tailwind-browser.wasm`) has no Lightning
216
+ CSS and no JavaScript engine: about 0.8 MB with compression. It lowers
217
+ the new CSS of the input (`@function`, `@mixin`, `if()`, `@when`,
218
+ `sibling-index()`, `round()`, ...) for the browsers of Tailwind CSS, as
219
+ `--optimize` does ([`docs/MIXINS.md`](docs/MIXINS.md)). The plugins
220
+ of `@plugin` and `@config` run in the JavaScript engine of the browser,
221
+ with JS Promise Integration: also ES modules and TypeScript files, but
222
+ not a module with a top-level `await`. The plugin layer of Tailwind CSS
223
+ adds about 45 KB.
224
+ - The first build waits for the end of the HTML, and the page stays
225
+ hidden until its first CSS (at most 3 seconds), so it does not show
226
+ with no style. The last CSS of each page stays in `localStorage`: the
227
+ next load is styled at once, and the build replaces it.
228
+ - In Chromium, with a network of 20 Mbps, the first visit shows the
229
+ styled page in about 0.6 s (0.8 s with the typography plugin), and a
230
+ reload in about 50 ms. A build after
231
+ a change takes about 15 ms. Use it for development, prototypes and
232
+ editors, not for a production site.
233
+
234
+ In a bundler (Vite, webpack, esbuild) and in a Web Worker, the condition
235
+ `browser` of the package gives `runWasm` with the files in memory:
236
+
237
+ ```js
238
+ import { runWasm } from 'tailwind.com';
239
+
240
+ const { status, stdout } = await runWasm(['-i', 'app.css'], {
241
+ files: { 'app.css': '@import "tailwindcss";', 'index.html': html },
242
+ });
243
+ ```
244
+
245
+ With no `-o`, the CSS is in `stdout`. Vite and webpack copy
246
+ `tailwind-browser.wasm` and the JavaScript files of the plugins with the
247
+ files of the site. For a bundler that does not copy them (esbuild), copy
248
+ `runtime/` of the package to the site, and give its URL in the option
249
+ `runtime`. For `--minify` and the command `canonicalize`, give the URL
250
+ of `tailwind.wasm` in the option `wasm`.
162
251
 
163
252
  Each release also publishes the package to GitHub Packages, with the
164
253
  name `@sntran/tailwind.com` (registry `https://npm.pkg.github.com`), and
@@ -220,10 +309,30 @@ expects the same text, byte for byte:
220
309
  | The official command line program on small projects, also the warnings of the optimizer and of `@utility` | 20 projects |
221
310
  | The source maps of the official compiler and of its optimizer | 317 stylesheets |
222
311
  | The official command line program with `--map`, also with a JavaScript plugin and config | 29 projects |
312
+ | The command `canonicalize`: each call of the unit tests of the official code, and the official program on 400 random lists (4.3.5, 4.3.4 and 4.3.2) | 1,914 calls, 13 projects |
223
313
  | The official command line program on projects with JavaScript and TypeScript plugins and configs (daisyUI, heroicons, `@tailwindcss/typography`, `@tailwindcss/forms`, two Phoenix projects) | 100 projects |
224
314
  | The `compile` calls of the unit tests of Tailwind CSS that load a JavaScript plugin or config | 296 calls |
225
315
  | Node.js 22 for the parts of Node.js that a plugin gets (`Buffer`, `URL`, timers, `fs`, `util`, ...), and for the files that `require` and `import` find | 124 values, 160 questions |
226
316
 
317
+ The second command of the official program, `canonicalize`, is also
318
+ there, with the same options and the same output:
319
+
320
+ ```sh
321
+ $ tailwind.com canonicalize "py-3 p-1 px-3" "w-[16px] h-[16px] bg-[#FFF]"
322
+ p-3
323
+ size-[16px] bg-white
324
+ ```
325
+
326
+ It gives the canonical form of each list of classes: one class for more
327
+ classes when the CSS is the same, the bare value of an arbitrary value,
328
+ the new names of old classes, and the sort of the official Prettier
329
+ plugin. `--css app.css` uses the theme and the plugins of the project,
330
+ and `--stream` reads one list from each line of the standard input. It
331
+ runs in about 0.6 s with 135 MB of memory, and the official program in
332
+ about 3.1 s with 560 MB: the first list makes an index of all the
333
+ classes. `cargo test` replays each call
334
+ of the unit tests of the official code (1,914 calls).
335
+
227
336
  See [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) for the results and
228
337
  the known differences, and [`docs/TESTING.md`](docs/TESTING.md) for the
229
338
  other tests: unit tests from the test files of Tailwind CSS, property
@@ -236,11 +345,12 @@ program. For example, the Phoenix project: 12 ms with `tailwind.com`,
236
345
  project with daisyUI: 182 ms, 310 ms and 251 ms, with 13 MB of memory in
237
346
  place of 103 MB and 89 MB.
238
347
 
239
- CI runs `tailwind.com` on Linux (x86_64 and aarch64), macOS (arm64 and
240
- x86_64), Windows (x86_64), FreeBSD, NetBSD and OpenBSD 7.3 (x86_64, in
241
- a VM): the projects of the official program, and the watch with the
242
- file events of each system (inotify, kqueue, `ReadDirectoryChangesW`)
243
- and with the poll.
348
+ CI runs `tailwind.com` on Linux (x86_64 and aarch64), macOS (26 and 27
349
+ on arm64, and x86_64), Windows (x86_64 and ARM64), FreeBSD, NetBSD and
350
+ OpenBSD 7.3 (x86_64, in a VM): the projects of the official program,
351
+ and the watch with the file events of each system (inotify, kqueue,
352
+ `ReadDirectoryChangesW`) and with the poll. A test checks that each
353
+ system runs the code for its CPU.
244
354
 
245
355
  A differential fuzzer also compares the two compilers live on new random
246
356
  stylesheets, classes and projects, in CI for each change of the compiler
@@ -302,12 +412,24 @@ differences.
302
412
  path `/$tailwindcss/NAME.css`. With `node_modules/tailwindcss` in the
303
413
  project, the path is the path of the file, as with the official
304
414
  program.
415
+ - **Windows on ARM64**: the PE header of an APE file is for AMD64, so
416
+ Windows starts the x86_64 half in its x64 emulation. That half writes
417
+ the loader of the aarch64 half (`.ape-arm64-HASH.exe`, 7 KB) to the
418
+ directory of the temporary files, and starts the aarch64 half with
419
+ it. This costs about 44 ms for each start, and a build is faster:
420
+ 116 ms in place of 189 ms for a small project, and 479 ms in place of
421
+ 726 ms for the Phoenix project with daisyUI. When Windows does not
422
+ let the loader run there (for example, a policy that blocks programs
423
+ in the directory of the temporary files), the file runs in the x64
424
+ emulation.
305
425
  - **NetBSD and OpenBSD**: the `sh` of NetBSD cannot read an APE file.
306
426
  Start the file there with the APE loader of cosmocc
307
427
  (`ape-x86_64.elf tailwind.com`). Cosmopolitan supports OpenBSD 7.3 or
308
428
  earlier.
309
- - `canonicalize`, the second command of the official program, is not
310
- there.
429
+ - **`canonicalize`** has one algorithm, the one of Tailwind CSS 4.3.5,
430
+ for each version of Tailwind CSS: see
431
+ [`docs/VERSIONS.md`](docs/VERSIONS.md). For 4.2.2 to 4.3.0, the result
432
+ can be better than the result of the official command of that version.
311
433
  - **Tailwind CSS 3** (a project with only `tailwind.config.js` and
312
434
  `@tailwind` rules, and `version: "3.x"`) does not work: it is another
313
435
  program. Use the official Hex package or program for it.
@@ -329,7 +451,16 @@ The release job publishes it to crates.io.
329
451
  WASI file system. It has the same JavaScript engine for `@plugin` and
330
452
  `@config`, with TypeScript and the three plugins in the file. The site
331
453
  runs it in the browser, with a small WASI host in JavaScript
332
- (`site/wasi.mjs`, [`docs/SITE.md`](docs/SITE.md)).
454
+ (`js/wasi.mjs`, [`docs/SITE.md`](docs/SITE.md)).
455
+
456
+ `tailwind-browser.wasm` of each release is the program for a browser,
457
+ for builds: no Lightning CSS, no JavaScript engine and no command
458
+ `canonicalize`, about 0.8 MB with compression, and `tailwind.wasm` is
459
+ about 1.9 MB. Its plugins run in the JavaScript engine of the host, with
460
+ JS Promise Integration (`js/engine.mjs`): a browser, or Node.js 24 or
461
+ later. `--optimize` only lowers the new CSS functions and mixins, and
462
+ `--minify` and `canonicalize` give an error.
463
+ The condition `browser` of the npm package gives it.
333
464
 
334
465
  ## Documentation
335
466
 
package/js/browser.mjs ADDED
@@ -0,0 +1,187 @@
1
+ // The API of the npm package tailwind.com in a browser: the condition
2
+ // "browser" of package.json gives this file in place of js/node.mjs. It
3
+ // runs the program for a browser, tailwind-browser.wasm, with a file
4
+ // system in memory (js/wasi.mjs).
5
+ //
6
+ // import { runWasm } from 'tailwind.com';
7
+ //
8
+ // const { status, stdout, stderr } = await runWasm(['-i', 'app.css'], {
9
+ // files: { 'app.css': '@import "tailwindcss";', 'index.html': '<div class="flex p-4">' },
10
+ // });
11
+ //
12
+ // tailwind-browser.wasm is for builds. It has no Lightning CSS, no
13
+ // JavaScript engine and no command canonicalize: --optimize only lowers
14
+ // the new CSS (functions, mixins, if(), @when, the sibling functions, the
15
+ // math functions), --minify and canonicalize give an error, and the
16
+ // plugins run in the JavaScript engine of the browser (js/engine.mjs). For
17
+ // --minify and canonicalize, give the URL of tailwind.wasm in
18
+ // options.wasm (about 1.8 MB with compression).
19
+ //
20
+ // It also runs in a Web Worker, and in Deno and Node.js with no file
21
+ // system. Vite and webpack copy tailwind-browser.wasm and the JavaScript
22
+ // files of runtime/ with the files of the site: each one has the pattern
23
+ // `new URL('../runtime/NAME', import.meta.url)`. For a bundler that does
24
+ // not copy them (esbuild), copy runtime/ of the package to the site, and
25
+ // give its URL in options.runtime.
26
+ import { createEngine, hasPromiseIntegration, needsEngine } from './engine.mjs';
27
+ import { Files, run } from './wasi.mjs';
28
+
29
+ // The package root in the URL of a file of the package on a CDN:
30
+ // "https://cdn.jsdelivr.net/npm/tailwind.com@0.6.0/+esm",
31
+ // "https://esm.sh/tailwind.com@0.6.0/es2022/tailwind.com.mjs", or only the
32
+ // root for the default file, "https://cdn.jsdelivr.net/npm/tailwind.com@0.6".
33
+ function packageRoot(from) {
34
+ const url = new URL(from);
35
+ const found = url.pathname.match(/^(.*\/tailwind\.com(?:@[^/]*)?)(?:\/|$)/);
36
+ return found ? new URL(`${found[1]}/`, url).href : null;
37
+ }
38
+
39
+ // The files of runtime/ when this file is not on a CDN. A bundler finds
40
+ // each pattern `new URL('…', import.meta.url)`: the text of each one must
41
+ // stay as it is.
42
+ const LOCAL = {
43
+ 'tailwind-browser.wasm': () => new URL('../runtime/tailwind-browser.wasm', import.meta.url),
44
+ 'compat.js': () => new URL('../runtime/compat.js', import.meta.url),
45
+ 'typescript.js': () => new URL('../runtime/typescript.js', import.meta.url),
46
+ 'plugins/forms.js': () => new URL('../runtime/plugins/forms.js', import.meta.url),
47
+ 'plugins/typography.js': () => new URL('../runtime/plugins/typography.js', import.meta.url),
48
+ 'plugins/aspect-ratio.js': () => new URL('../runtime/plugins/aspect-ratio.js', import.meta.url),
49
+ };
50
+
51
+ // The URL of a file of runtime/: in the directory `runtime`, else from the
52
+ // package root of a CDN, else the copy of a bundler.
53
+ function runtimeUrl(name, runtime) {
54
+ if (runtime) return new URL(name, new URL(String(runtime).replace(/\/?$/, '/'), globalThis.location?.href ?? import.meta.url)).href;
55
+ const root = packageRoot(import.meta.url);
56
+ return root ? new URL(`runtime/${name}`, root).href : LOCAL[name]().href;
57
+ }
58
+
59
+ // The URL of tailwind-browser.wasm, from the URL of a file of the package
60
+ // (default: this file).
61
+ export function wasmUrl(from = import.meta.url) {
62
+ if (from === import.meta.url) return runtimeUrl('tailwind-browser.wasm');
63
+ const root = packageRoot(from);
64
+ return root ? new URL('runtime/tailwind-browser.wasm', root).href : new URL('../runtime/tailwind-browser.wasm', from).href;
65
+ }
66
+
67
+ // The compiled module of each URL. A failed download can be tried again.
68
+ const modules = new Map();
69
+
70
+ function compile(url) {
71
+ if (!modules.has(url)) {
72
+ const compiled = fetch(url).then(async (response) => {
73
+ if (!response.ok) throw new Error(`${url}: ${response.status} ${response.statusText}`);
74
+ // A server that does not send "application/wasm" cannot stream.
75
+ if (response.headers.get('content-type')?.startsWith('application/wasm')) {
76
+ return WebAssembly.compileStreaming(response);
77
+ }
78
+ return WebAssembly.compile(await response.arrayBuffer());
79
+ });
80
+ compiled.catch(() => modules.delete(url));
81
+ modules.set(url, compiled);
82
+ }
83
+ return modules.get(url);
84
+ }
85
+
86
+ // The JavaScript files of the program, by URL.
87
+ const texts = new Map();
88
+
89
+ function text(url) {
90
+ if (!texts.has(url)) {
91
+ const loading = fetch(url).then((response) => {
92
+ if (!response.ok) throw new Error(`${url}: ${response.status} ${response.statusText}`);
93
+ return response.text();
94
+ });
95
+ loading.catch(() => texts.delete(url));
96
+ texts.set(url, loading);
97
+ }
98
+ return texts.get(url);
99
+ }
100
+
101
+ // The plugins in the program, as in the standalone program of Tailwind CSS.
102
+ const PLUGINS = ['@tailwindcss/forms', '@tailwindcss/typography', '@tailwindcss/aspect-ratio'];
103
+
104
+ // The JavaScript files that a build of `input` and `files` needs: none
105
+ // with no @plugin and no @config.
106
+ async function assets(runtime, input, files) {
107
+ const all = [input, ...Object.values(files).filter((value) => typeof value === 'string')].join('\n');
108
+ if (!/@(?:plugin|config)\b/.test(all)) return {};
109
+ const names = { compat: 'compat.js' };
110
+ // An ES module or a TypeScript file becomes CommonJS with Sucrase.
111
+ if (Object.keys(files).some((name) => /\.[cm]?[jt]s$/.test(name))) names.typescript = 'typescript.js';
112
+ for (const plugin of PLUGINS) {
113
+ if (all.includes(plugin)) names[`plugin:${plugin}`] = `plugins/${plugin.slice('@tailwindcss/'.length)}.js`;
114
+ }
115
+ const entries = await Promise.all(Object.entries(names).map(async ([name, file]) => [name, await text(runtimeUrl(file, runtime))]));
116
+ return Object.fromEntries(entries);
117
+ }
118
+
119
+ // Run the program with the arguments of the command line program, as
120
+ // runWasm of js/node.mjs. The files are in memory: options.files is an
121
+ // object { path: text or Uint8Array }, with paths from the root "/" of the
122
+ // program. The program sees no other file.
123
+ //
124
+ // options: files, env (default: empty), input (the text of stdin), wasm
125
+ // (the URL of the program, default: wasmUrl(), tailwind-browser.wasm),
126
+ // runtime (the URL of a copy of runtime/ of the package: the default
127
+ // program and the JavaScript files come from there).
128
+ //
129
+ // tailwind-browser.wasm has no JavaScript engine: for @plugin and
130
+ // @config, it runs the plugins in the JavaScript engine of the browser
131
+ // (js/engine.mjs). That needs a page (not a worker) and JS Promise
132
+ // Integration. The JavaScript files come from runtime/ of the package.
133
+ // The result is { status, stdout, stderr } with the output as text. With
134
+ // no -o, the CSS is in stdout. --watch does not end: do not give it.
135
+ export async function runWasm(args = [], options = {}) {
136
+ // A relative URL is relative to the page.
137
+ const url = new URL(String(options.wasm ?? (options.runtime ? runtimeUrl('tailwind-browser.wasm', options.runtime) : wasmUrl())), globalThis.location?.href ?? import.meta.url).href;
138
+ // The JavaScript files download while the program compiles.
139
+ const loading = assets(options.runtime, options.input ?? '', options.files ?? {});
140
+ loading.catch(() => {});
141
+ const module = await compile(url);
142
+ let imports = {};
143
+ let promising = false;
144
+ let engine = null;
145
+ if (needsEngine(module)) {
146
+ const found = await loading;
147
+ if (found.compat !== undefined) {
148
+ if (!hasPromiseIntegration) {
149
+ throw new Error('tailwind.com: @plugin and @config need JS Promise Integration (WebAssembly.Suspending) in the browser.');
150
+ }
151
+ promising = true;
152
+ }
153
+ // The imports are there also when no build calls them.
154
+ imports = (exports) => {
155
+ if (!promising) return { tailwind_js: missingEngine() };
156
+ engine = createEngine(exports, (name) => found[name]);
157
+ return { tailwind_js: engine.imports };
158
+ };
159
+ }
160
+ const files = new Files();
161
+ files.mkdir('/project');
162
+ for (const [name, content] of Object.entries(options.files ?? {})) {
163
+ files.write(`/project/${name.replace(/^\/+/, '')}`, content);
164
+ }
165
+ try {
166
+ return await run(module, {
167
+ args,
168
+ env: options.env ?? {},
169
+ stdin: options.input ?? '',
170
+ files,
171
+ preopens: { '/': '/project' },
172
+ imports,
173
+ promising,
174
+ });
175
+ } finally {
176
+ engine?.dispose();
177
+ }
178
+ }
179
+
180
+ // The imports of the engine for a build with no @plugin and no @config: the
181
+ // program does not call them.
182
+ function missingEngine() {
183
+ const missing = () => {
184
+ throw new Error('tailwind.com: this build has no JavaScript engine.');
185
+ };
186
+ return { tw_js_new: missing, tw_js_free: missing, tw_js_eval: missing, tw_js_call: missing, tw_js_call_async: missing };
187
+ }