+# @devup-ui/wasm
-
+The Devup UI compiler as a Node.js WebAssembly module. It is the engine the
+build plugins (`@devup-ui/vite-plugin`, `next-plugin`, `webpack-plugin`,
+`rsbuild-plugin`, `bun-plugin`) call; most projects never import it directly.
-A template for kick starting a Rust and WebAssembly project using wasm-pack.
+It is built from the Rust crates in `libs/` (`extractor`, `sheet`, `css`) with
+`wasm-pack build --target nodejs`, so it loads with `require`/`import` in Node
+and Bun, not in a browser.
-
-
-## About
-
-[**📚 Read this template tutorial! 📚**][template-docs]
-
-This template is designed for compiling Rust libraries into WebAssembly and
-publishing the resulting package to NPM.
-
-Be sure to check out [other `wasm-pack` tutorials online][tutorials] for other
-templates and usages of `wasm-pack`.
-
-[tutorials]: https://rustwasm.github.io/docs/wasm-pack/tutorials/index.html
-[template-docs]: https://rustwasm.github.io/docs/wasm-pack/tutorials/npm-browser-packages/index.html
-
-## 🚴 Usage
-
-### 🐑 Use `cargo generate` to Clone this Template
-
-[Learn more about `cargo generate` here.](https://github.com/ashleygwilliams/cargo-generate)
-
-```
-cargo generate --git https://github.com/rustwasm/wasm-pack-template.git --name my-project
-cd my-project
+```sh
+cd bindings/devup-ui-wasm
+bun run build # removes pkg/, runs wasm-pack, writes pkg/package.json
```
-### 🛠️ Build with `wasm-pack build`
+`pkg/` is generated and ignored by git. The build starts from an empty `pkg/`,
+so files of a removed export cannot linger there; `bun run verify:dist` in the
+repository root fails if one does.
-```
-wasm-pack build
-```
+## API
-### 🔬 Test in Headless Browsers with `wasm-pack test`
+Everything is exported from `pkg/index.js` (types in `pkg/index.d.ts`).
-```
-wasm-pack test --headless --firefox
-```
+| Function | Does |
+| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `codeExtract(filename, code, package, cssDir, singleCss, importMainCssInCode, importMainCssInCss, importAliases)` | Compiles one source file and returns an `Output`: the rewritten `code`, its `css`, `cssFile`, source `map`, the `dependencies` it read and `updatedBaseStyle`. Throws on a build error. |
+| `codeExtractWithoutSourceMap(...)` | The same without the source map. |
+| `hasDevupUI(filename, code, package)` | Whether the file imports Devup UI, so a plugin can skip the rest. |
+| `getCss(fileNum, importMainCss)` | The stylesheet collected so far: the whole sheet for `null`, one file's for its number. |
+| `registerTheme(theme)`, `registerShorthands(shorthands)` | Registers the `devup.json` theme and the custom shorthand props before extracting. |
+| `getThemeInterface(package, color, typography, length, shadows, theme)` | The `.d.ts` text that types the registered theme. |
+| `getDefaultTheme()` | The theme variant that applies without `data-theme`. |
+| `setPrefix(prefix)`, `getPrefix()` | Class name prefix. |
+| `setDebug(debug)`, `isDebug()` | Readable class names instead of base-37 ones, with repeated declarations kept (the tests run this way). |
+| `setModuleResolver(resolver)` | `(specifier, importer) => ({ path, code })`: how imports are resolved, so imported stylesheets are evaluated and imported constants inlined. |
+| `setAtomHoist(threshold)`, `importFileRoutes(routes)` | Moves atoms used by `threshold` routes or more into the shared sheet. Call before `codeExtract`. |
+| `exportSheet`, `exportClassMap`, `exportFileMap`, `exportCanonicalMap` and the matching `import*` functions | Save the collected state and load it into another process, as a bundler does between its server and client builds. |
-### 🎁 Publish to NPM with `wasm-pack publish`
+## State
-```
-wasm-pack publish
-```
+The module keeps its state, the sheet, class maps, theme, prefix and debug flag,
+in one global per process, and there is no single reset. Two consequences:
-## 🔋 Batteries Included
+- Register the theme, shorthands, prefix and resolver before the first
+ `codeExtract`, and extract the files of one build in one process.
+- Tests that share a process share that state. Set what a test depends on
+ (`registerTheme`, `setPrefix`, `setDebug`, `importSheet`) at its start, and
+ run files that need an empty sheet in their own process.
-- [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) for communicating
- between WebAssembly and JavaScript.
-- [`console_error_panic_hook`](https://github.com/rustwasm/console_error_panic_hook)
- for logging panic messages to the developer console.
-- `LICENSE-APACHE` and `LICENSE-MIT`: most Rust projects are licensed this way, so these are included for you
+## Errors
-## License
-
-Licensed under either of
-
-- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+A source the build cannot compile makes `codeExtract` throw an `Error`. Its
+message names the call and says what the build needs, for example
+``path/to/file.tsx:12:5: `css()` cannot use `window.name` at build time: its
+values must be literals, theme tokens or constants`` (the location is included
+whenever the problem has one). A `.css.ts` stylesheet that throws while it runs
+reports that exception.
-at your option.
-
-### Contribution
+## License
-Unless you explicitly state otherwise, any contribution intentionally
-submitted for inclusion in the work by you, as defined in the Apache-2.0
-license, shall be dual licensed as above, without any additional terms or
-conditions.
+Apache-2.0
diff --git a/bindings/devup-ui-wasm/package.json b/bindings/devup-ui-wasm/package.json
index c30850d49..963734de6 100644
--- a/bindings/devup-ui-wasm/package.json
+++ b/bindings/devup-ui-wasm/package.json
@@ -19,7 +19,7 @@
],
"version": "1.0.83",
"scripts": {
- "build": "wasm-pack build --target nodejs --out-dir ./pkg --out-name index && node script.js",
+ "build": "node -e \"require('node:fs').rmSync('pkg', { recursive: true, force: true })\" && wasm-pack build --target nodejs --out-dir ./pkg --out-name index && node script.js",
"test": "wasm-pack test --node"
},
"publishConfig": {
diff --git a/bun.lock b/bun.lock
index 412668d4f..1f7b6c2be 100644
--- a/bun.lock
+++ b/bun.lock
@@ -78,6 +78,25 @@
"typescript": "^7.0.2",
},
},
+ "apps/react-18": {
+ "name": "react-18-example",
+ "version": "0.1.0",
+ "dependencies": {
+ "@devup-ui/components": "workspace:^",
+ "@devup-ui/react": "workspace:^",
+ "react": "18.3.1",
+ "react-dom": "18.3.1",
+ },
+ "devDependencies": {
+ "@devup-ui/vite-plugin": "workspace:^",
+ "@playwright/test": "^1.63.0",
+ "@types/react": "^18.3",
+ "@types/react-dom": "^18.3",
+ "@vitejs/plugin-react": "^6.1",
+ "typescript": "^7.0.2",
+ "vite": "^8.3",
+ },
+ },
"apps/rsbuild": {
"name": "rsbuild-example",
"version": "1.0.0",
@@ -2813,6 +2832,8 @@
"react": ["react@19.3.0", "", {}, "sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog=="],
+ "react-18-example": ["react-18-example@workspace:apps/react-18"],
+
"react-docgen": ["react-docgen@8.0.4", "", { "dependencies": { "@babel/core": "^7.28.0", "@babel/traverse": "^7.28.0", "@babel/types": "^7.28.2", "@types/babel__core": "^7.20.5", "@types/babel__traverse": "^7.20.7", "@types/doctrine": "^0.0.9", "@types/resolve": "^1.20.2", "doctrine": "^3.0.0", "resolve": "^1.22.1", "strip-indent": "^4.0.0" } }, "sha512-gIYjtVTU4NCWZnb/LXVSWfClZXnjzX3+xxi69Tkfu4YsmYuqiOk8giLkKt/WwxWqh+U66CTh8Kqbha1uPv8/qQ=="],
"react-docgen-typescript": ["react-docgen-typescript@2.4.0", "", { "peerDependencies": { "typescript": ">= 4.3.x" } }, "sha512-ZtAp5XTO5HRzQctjPU0ybY0RRCQO19X/8fxn3w7y2VVTUbGHDKULPTL4ky3vB05euSgG5NpALhEhDPvQ56wvXg=="],
@@ -3769,6 +3790,14 @@
"qified/hookified": ["hookified@2.2.0", "", {}, "sha512-p/LgFzRN5FeoD3DLS6bkUapeye6E4SI6yJs6KetENd18S+FBthqYq2amJUWpt5z0EQwwHemidjY5OqJGEKm5uA=="],
+ "react-18-example/@types/react": ["@types/react@18.3.31", "", { "dependencies": { "@types/prop-types": "*", "csstype": "^3.2.2" } }, "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw=="],
+
+ "react-18-example/@types/react-dom": ["@types/react-dom@18.3.7", "", { "peerDependencies": { "@types/react": "^18.0.0" } }, "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ=="],
+
+ "react-18-example/react": ["react@18.3.1", "", { "dependencies": { "loose-envify": "^1.1.0" } }, "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ=="],
+
+ "react-18-example/react-dom": ["react-dom@18.3.1", "", { "dependencies": { "loose-envify": "^1.1.0", "scheduler": "^0.23.2" }, "peerDependencies": { "react": "^18.3.1" } }, "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw=="],
+
"react-docgen/@babel/core": ["@babel/core@7.29.7", "", { "dependencies": { "@babel/code-frame": "^7.29.7", "@babel/generator": "^7.29.7", "@babel/helper-compilation-targets": "^7.29.7", "@babel/helper-module-transforms": "^7.29.7", "@babel/helpers": "^7.29.7", "@babel/parser": "^7.29.7", "@babel/template": "^7.29.7", "@babel/traverse": "^7.29.7", "@babel/types": "^7.29.7", "@jridgewell/remapping": "^2.3.5", "convert-source-map": "^2.0.0", "debug": "^4.1.0", "gensync": "^1.0.0-beta.2", "json5": "^2.2.3", "semver": "^6.3.1" } }, "sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA=="],
"react-docgen/@babel/traverse": ["@babel/traverse@7.29.8", "", { "dependencies": { "@babel/code-frame": "^7.29.7", "@babel/generator": "^7.29.8", "@babel/helper-globals": "^7.29.7", "@babel/parser": "^7.29.8", "@babel/template": "^7.29.7", "@babel/types": "^7.29.8", "debug": "^4.3.1" } }, "sha512-I5z7H3bf/41ktsNVLtpN0wAa336HkqIHQ5BuPLEhTkt1jVSyZpeNKIzTgEWmlxjdg81R0IgUCcaE+Ok3NvrfZg=="],
@@ -5617,6 +5646,8 @@
"pkg-dir/find-up/path-exists": ["path-exists@5.0.0", "", {}, "sha512-RjhtfwJOxzcFmNOi6ltcbcu4Iu+FL3zEj83dk4kAS+fVpTxXLO1b38RvJgT/0QwvV/L3aY9TAnyv0EOqW4GoMQ=="],
+ "react-18-example/react-dom/scheduler": ["scheduler@0.23.2", "", { "dependencies": { "loose-envify": "^1.1.0" } }, "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ=="],
+
"react-docgen/@babel/core/@babel/code-frame": ["@babel/code-frame@7.29.7", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.29.7", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw=="],
"react-docgen/@babel/core/@babel/generator": ["@babel/generator@7.29.8", "", { "dependencies": { "@babel/parser": "^7.29.8", "@babel/types": "^7.29.8", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-gZbepsdh3WDtgZKWL+vTPh71LSBrm/Y4/QDZBVCcYfmeTEEuoOYwlSy+G1StfJg+/Zy550u/3TATbm7qDbbMtg=="],
diff --git a/packages/plugin-utils/src/__tests__/wasm-abi.test.ts b/packages/plugin-utils/src/__tests__/wasm-abi.test.ts
new file mode 100644
index 000000000..6862abf62
--- /dev/null
+++ b/packages/plugin-utils/src/__tests__/wasm-abi.test.ts
@@ -0,0 +1,254 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+
+// The compiled module as a plugin loads it: the Rust tests cover the crates, not
+// this boundary (every wrapper is excluded from tarpaulin), so the contract the
+// plugins rely on is checked here, through the JS bindings.
+const wasm = await import('../../../../bindings/devup-ui-wasm/pkg/index.js')
+
+const PACKAGE = '@devup-ui/react'
+
+/** What the module keeps for the process, so a test leaves it as it found it */
+function saveState() {
+ return {
+ sheet: JSON.parse(wasm.exportSheet()),
+ classMap: JSON.parse(wasm.exportClassMap()),
+ fileMap: JSON.parse(wasm.exportFileMap()),
+ canonicalMap: JSON.parse(wasm.exportCanonicalMap()),
+ css: wasm.getCss(null, false),
+ debug: wasm.isDebug(),
+ prefix: wasm.getPrefix(),
+ }
+}
+
+function restoreState(state: ReturnTypewasm-pack-template
+The Devup UI compiler as a Node.js WebAssembly module. It is the engine the
+build plugins (`@devup-ui/vite-plugin`, `next-plugin`, `webpack-plugin`,
+`rsbuild-plugin`, `bun-plugin`) call; most projects never import it directly.
-A template for kick starting a Rust and WebAssembly project using wasm-pack.
+It is built from the Rust crates in `libs/` (`extractor`, `sheet`, `css`) with
+`wasm-pack build --target nodejs`, so it loads with `require`/`import` in Node
+and Bun, not in a browser.
-
- 
-