@octanejs/stylex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @octanejs/stylex
+
+[StyleX](https://stylexjs.com) for the [octane](https://github.com/octanejs/octane) renderer.
+
+StyleX is a **build-time** CSS-in-JS system: a compiler turns `stylex.create({...})`
+into atomic class names and extracts the CSS, and `stylex.props(...)` merges those at
+runtime into the props you spread onto an element. So — unlike the zustand/motion
+_runtime_ bindings — the octane integration is the **compiler pass**, shipped in two
+parts:
+
+- **`@octanejs/stylex`** — the authoring surface you import in components. It
+  re-exports `@stylexjs/stylex` (so the runtime `props`/`attrs` and all the types
+  work) and is registered as a StyleX _import source_ so the compiler finds your
+  `stylex.*` call sites.
+- **`@octanejs/stylex/vite`** — the Vite plugin that runs the StyleX compiler over
+  octane's compiled `.tsrx` output and emits one static atomic stylesheet
+  (`virtual:stylex.css`). **Zero StyleX runtime ships in your bundle.**
+
+## Setup
+
+Add the plugin **after** `octane()` and import the generated sheet once:
+
+```ts
+// vite.config.ts
+import { octane } from 'octane/compiler/vite';
+import { stylex } from '@octanejs/stylex/vite';
+
+export default {
+  plugins: [octane(), stylex()],
+};
+```
+
+```ts
+// app entry
+import 'virtual:stylex.css';
+```
+
+## Usage
+
+```tsx
+import * as stylex from '@octanejs/stylex';
+
+const styles = stylex.create({
+  root: { padding: 16, color: 'tomato' },
+  active: { color: 'blue' },
+});
+
+export function Card(props) @{
+  <div {...stylex.props(styles.root, props.on && styles.active)}>{'Card'}</div>
+}
+```
+
+`stylex.props()` returns `{ className?, style? }`. Octane host elements take that
+directly — the spread handler maps both `className` and `class` to the `class`
+attribute and applies a `style` object — so there's no octane-specific `props()`
+variant to learn. `stylex.attrs()` (which returns `{ class, style }` as a string) is
+also re-exported for raw-attribute contexts.
+
+## How it works
+
+`octane()` (`enforce: 'pre'`) compiles `.tsrx` → JS, preserving the `stylex.*` calls.
+`stylex()` (`enforce: 'post'`) then runs `@stylexjs/babel-plugin` over that output:
+each `stylex.create`/`props`/`keyframes`/`defineVars`/`createTheme` call is replaced
+with its compiled atomic form, and the extracted rules from every module are folded
+into `virtual:stylex.css` — deduped by content-hashed key and ordered by StyleX's
+baked-in cascade priority (so import order is irrelevant). In dev, editing a file
+re-aggregates the sheet (HMR full-reload). In a production build, where the virtual
+module can be loaded before every styled module has been transformed, the sheet is
+finalized in `generateBundle` once all rules are collected — so the shipped CSS always
+contains every rule regardless of module/transform order.
+
+## Options
+
+`stylex(options)`:
+
+- `include` — files to scan (default: `.tsrx`/`.tsx`/`.jsx`/`.ts`/`.js`).
+- `importSources` — specifiers treated as StyleX (default: `@octanejs/stylex` +
+  `@stylexjs/stylex`).
+- `dev` — force dev/prod compilation (default: dev while Vite is serving).
+- `useCSSLayers` — emit `@layer` rules instead of the `:not(#\#)` specificity hack.
+- `unstable_moduleResolution` — StyleX cross-file token (`.stylex.ts`) resolution.
+- `stylexOptions` — escape hatch for any other `@stylexjs/babel-plugin` option.
+
+## Divergences
+
+- StyleX's `sx` JSX prop is not supported — use the `{...stylex.props(...)}` spread
+  (which is also StyleX's own recommended pattern).
+- The plugin runs the StyleX compiler on octane's _output_, so StyleX's own
+  source-scanning tools (the PostCSS plugin) are not used and not needed.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@octanejs/stylex",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "StyleX bindings for the octane renderer — reuses StyleX's framework-agnostic compiler core and routes the generated atomic CSS through octane's stylesheet channel (client dedupe + SSR render().css).",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/stylex"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./vite": "./src/vite.js"
+  },
+  "dependencies": {
+    "@babel/core": "7.29.7",
+    "@stylexjs/babel-plugin": "0.19.0",
+    "@stylexjs/stylex": "0.19.0",
+    "octane": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/babel__core": "7.20.5",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// @octanejs/stylex — StyleX for the octane renderer.
+//
+// StyleX is a BUILD-TIME CSS-in-JS system: `@stylexjs/babel-plugin` compiles
+// `stylex.create({...})` into atomic class-name maps and extracts the CSS, and
+// `stylex.props(...)` / `stylex.attrs(...)` merge those at runtime into the props
+// you spread onto an element. Unlike zustand/motion there is no React runtime to
+// reimplement — the integration is the COMPILER pass. So this package is two parts:
+//
+//   • `@octanejs/stylex`       — this module: the authoring surface you import in
+//                                 components. It re-exports `@stylexjs/stylex` so
+//                                 types + the runtime `props`/`attrs` work, and so
+//                                 the babel plugin (configured to treat
+//                                 `@octanejs/stylex` as an import source) can find
+//                                 and compile the `stylex.*` call sites.
+//   • `@octanejs/stylex/vite`  — the Vite plugin that runs the StyleX compiler over
+//                                 octane's compiled `.tsrx` output and emits one
+//                                 static atomic stylesheet (`virtual:stylex.css`).
+//
+// Octane host elements accept StyleX's output directly: `props()` returns
+// `{ className?, style? }`, and octane's spread handler maps both `className` and
+// `class` to the `class` attribute and applies a `style` object — so
+// `<div {...stylex.props(styles.root)}>` just works.
+import * as stylex from '@stylexjs/stylex';
+
+export * from '@stylexjs/stylex';
+
+// `@stylexjs/stylex` has no default export; provide the namespace as the default so
+// `import stylex from '@octanejs/stylex'` (the common StyleX usage) also resolves —
+// the babel plugin recognizes default, namespace, and named imports alike.
+export default stylex;

package/src/transform.js

@@ -0,0 +1,58 @@
+// The StyleX compiler pass, factored out of the Vite plugin so it can be unit
+// tested directly. `transformStylex` runs `@stylexjs/babel-plugin` over a module
+// (octane's compiled `.tsrx` output, or plain `.ts`/`.tsx`) — replacing every
+// `stylex.create`/`props`/`keyframes`/`defineVars`/`createTheme` call with its
+// compiled form and collecting the extracted atomic rules. `generateStylexCSS`
+// folds the rules from ALL modules into one deduped, priority-ordered stylesheet.
+//
+// Authored in `.js` (like octane's `compiler/` tooling) so it loads cleanly when a
+// consuming app's `vite.config.ts` pulls the plugin in through Node's ESM loader —
+// build tooling that Node executes directly cannot be raw `.ts` source.
+import babel from '@babel/core';
+import stylexBabelPlugin from '@stylexjs/babel-plugin';
+
+// `@stylexjs/babel-plugin` emits one tuple per atomic rule —
+// `[key, { ltr, rtl? }, priority]`: a stable content-hashed key, the LTR (and
+// optional RTL) CSS text, and a numeric cascade priority. The key dedupes identical
+// rules across files; the priority is baked into the selector by `processStylexRules`,
+// so cascade order is independent of injection order.
+
+export const DEFAULT_IMPORT_SOURCES = ['@octanejs/stylex', '@stylexjs/stylex'];
+
+export function transformStylex(code, opts) {
+	const res = babel.transformSync(code, {
+		filename: opts.filename,
+		babelrc: false,
+		configFile: false,
+		sourceMaps: opts.sourceMaps ?? true,
+		plugins: [
+			[
+				stylexBabelPlugin,
+				{
+					dev: opts.dev ?? false,
+					// Never the runtime-injection path — CSS is collected from
+					// `metadata.stylex` and emitted as one static sheet (the build-time route).
+					runtimeInjection: false,
+					importSources: opts.importSources ?? DEFAULT_IMPORT_SOURCES,
+					unstable_moduleResolution: opts.unstable_moduleResolution ?? {
+						type: 'commonJS',
+						rootDir: process.cwd(),
+					},
+					...opts.stylexOptions,
+				},
+			],
+		],
+	});
+	return {
+		code: res?.code ?? code,
+		map: res?.map ?? null,
+		rules: res?.metadata?.stylex ?? [],
+	};
+}
+
+// Fold every module's collected rules into one stylesheet: deduped by key, ordered
+// by StyleX's baked-in cascade priority (so source/import order is irrelevant).
+export function generateStylexCSS(rules, useCSSLayers = false) {
+	if (rules.length === 0) return '';
+	return stylexBabelPlugin.processStylexRules(rules, useCSSLayers);
+}

package/src/vite.js

@@ -0,0 +1,172 @@
+// @octanejs/stylex/vite — the build-time StyleX integration for octane apps.
+//
+// Add it AFTER `octane()` in your Vite config and import the generated sheet once:
+//
+//   import { octane } from 'octane/compiler/vite';
+//   import { stylex } from '@octanejs/stylex/vite';
+//   export default { plugins: [octane(), stylex()] };
+//
+//   // app entry:
+//   import 'virtual:stylex.css';
+//
+// `enforce: 'post'` makes this run on octane's COMPILED output (octane is
+// `enforce: 'pre'`), where the `stylex.*` call sites still live. Each module is run
+// through the StyleX compiler (`./transform`): the calls are replaced with their
+// atomic form and the extracted rules are accumulated per file. `virtual:stylex.css`
+// resolves to the deduped, priority-ordered concatenation of every file's rules — one
+// static atomic stylesheet, zero StyleX runtime in the shipped bundle.
+//
+// SERVE vs BUILD ordering. In dev, `virtual:stylex.css`'s `load` returns the live
+// aggregate and an HMR full-reload re-pulls it whenever a file's rules change. In a
+// production build the virtual module can be loaded BEFORE every styled module has
+// been transformed (Rollup traverses the graph in parallel), so `load` returns a
+// stable PLACEHOLDER rule and `generateBundle` — which runs after ALL transforms are
+// done — swaps that placeholder for the now-complete sheet. Either way the shipped
+// stylesheet contains every rule.
+//
+// Authored in `.js` (like octane's `compiler/vite.js`) so the plugin loads when a
+// consuming app's `vite.config.ts` pulls it in through Node's ESM loader.
+import { transformStylex, generateStylexCSS, DEFAULT_IMPORT_SOURCES } from './transform.js';
+
+const VIRTUAL_CSS_ID = 'virtual:stylex.css';
+const RESOLVED_VIRTUAL_CSS_ID = '\0' + VIRTUAL_CSS_ID;
+
+// A unique, minification-surviving rule emitted in a build so the virtual module can
+// load early; `generateBundle` finds and replaces it with the final sheet. The custom
+// property keeps the rule non-empty (minifiers drop empty rules) and never collides
+// with StyleX's hashed `x…` class names.
+const PLACEHOLDER_RULE = '.__stylex_sheet__{--stylex-sheet:1}';
+const PLACEHOLDER_RE = /\.__stylex_sheet__\s*\{[^}]*\}/g;
+
+/**
+ * @param {object} [options]
+ * @param {RegExp} [options.include] Files to scan (default: `.tsrx`/`.tsx`/`.jsx`/`.ts`/`.js`).
+ * @param {Array<string | { from: string, as: string }>} [options.importSources] StyleX import specifiers.
+ * @param {boolean} [options.dev] Force dev/prod compilation (default: dev when Vite is serving).
+ * @param {boolean} [options.useCSSLayers] Use `@layer` rules instead of the `:not(#\#)` specificity hack.
+ * @param {Record<string, unknown>} [options.unstable_moduleResolution] StyleX cross-file token resolution.
+ * @param {Record<string, unknown>} [options.stylexOptions] Escape hatch for other `@stylexjs/babel-plugin` options.
+ */
+export function stylex(options = {}) {
+	const include = options.include ?? /\.(tsrx|tsx|jsx|ts|js)(\?|$)/;
+	const importSources = options.importSources ?? DEFAULT_IMPORT_SOURCES;
+	const useCSSLayers = options.useCSSLayers ?? false;
+	// Per-module rule sets, so re-transforming one file (HMR) replaces only its rules.
+	const rulesByFile = new Map();
+	let isDev = false;
+	let isBuild = false;
+	let root = process.cwd();
+	let server;
+
+	const aggregate = () => {
+		const all = [];
+		for (const rules of rulesByFile.values()) for (const r of rules) all.push(r);
+		return generateStylexCSS(all, useCSSLayers);
+	};
+
+	return {
+		name: '@octanejs/stylex',
+		// Run after octane's `.tsrx` -> JS transform, where `stylex.*` calls survive.
+		enforce: 'post',
+
+		configResolved(config) {
+			isDev = options.dev ?? config.command === 'serve';
+			isBuild = config.command === 'build';
+			if (config.root) root = config.root;
+		},
+		configureServer(s) {
+			server = s;
+		},
+
+		resolveId(id) {
+			if (id === VIRTUAL_CSS_ID) return RESOLVED_VIRTUAL_CSS_ID;
+			return null;
+		},
+		load(id) {
+			if (id !== RESOLVED_VIRTUAL_CSS_ID) return null;
+			// In a build the graph may not be fully transformed yet — emit a placeholder
+			// that `generateBundle` replaces with the complete sheet. In serve, the live
+			// aggregate is correct (HMR re-pulls on change).
+			return isBuild ? PLACEHOLDER_RULE : aggregate();
+		},
+
+		transform(code, id) {
+			const file = id.split('?')[0];
+			if (!include.test(file) || file.includes('/node_modules/')) return null;
+			// Cheap gate: skip files that can't reference StyleX at all.
+			if (!importSources.some((s) => code.includes(typeof s === 'string' ? s : s.from))) {
+				return null;
+			}
+			const {
+				code: out,
+				map,
+				rules,
+			} = transformStylex(code, {
+				filename: file,
+				dev: isDev,
+				importSources,
+				unstable_moduleResolution: options.unstable_moduleResolution ?? {
+					type: 'commonJS',
+					rootDir: root,
+				},
+				stylexOptions: options.stylexOptions,
+			});
+
+			const prevKey = keyOf(rulesByFile.get(id));
+			if (rules.length > 0) rulesByFile.set(id, rules);
+			else rulesByFile.delete(id);
+
+			// HMR: if this file's rule set changed, invalidate the virtual sheet so the
+			// next request re-aggregates. A full reload keeps it simple and correct.
+			if (server && prevKey !== keyOf(rulesByFile.get(id))) {
+				const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_CSS_ID);
+				if (mod) {
+					server.moduleGraph.invalidateModule(mod);
+					server.ws.send({ type: 'full-reload' });
+				}
+			}
+
+			return { code: out, map };
+		},
+
+		// After every module is transformed, the aggregate is complete — swap the
+		// placeholder for the real sheet wherever it landed (a CSS asset normally, or a
+		// JS chunk if the CSS was inlined). `enforce: 'post'` runs this after Vite has
+		// emitted its CSS asset.
+		generateBundle(_options, bundle) {
+			if (!isBuild) return;
+			const css = aggregate();
+			for (const fileName in bundle) {
+				const file = bundle[fileName];
+				if (file.type === 'asset' && typeof file.source === 'string') {
+					if (PLACEHOLDER_RE.test(file.source)) {
+						file.source = file.source.replace(PLACEHOLDER_RE, () => css);
+					}
+				} else if (file.type === 'chunk' && typeof file.code === 'string') {
+					if (PLACEHOLDER_RE.test(file.code)) {
+						// CSS inlined into JS: the placeholder sits inside a string literal,
+						// so the replacement must be string-escaped to match.
+						file.code = file.code.replace(PLACEHOLDER_RE, () => jsStringEscape(css));
+					}
+				}
+			}
+		},
+	};
+}
+
+function keyOf(rules) {
+	return rules ? rules.map((r) => r[0]).join('|') : '';
+}
+
+// Escape a CSS string so it can be spliced inside an existing JS string literal
+// (covers the rarer case of Vite inlining the sheet into a JS chunk). Backslash must
+// be escaped first; quotes/backticks cover the literal styles esbuild emits.
+function jsStringEscape(css) {
+	return css
+		.replace(/\\/g, '\\\\')
+		.replace(/'/g, "\\'")
+		.replace(/"/g, '\\"')
+		.replace(/`/g, '\\`')
+		.replace(/\n/g, '\\n')
+		.replace(/\r/g, '\\r');
+}