@farm.js/stylex 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+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,65 @@
+# `@farm.js/stylex`
+
+Compile [StyleX](https://stylexjs.com/) in Farm with extracted production CSS, pre-paint
+development styles, and CSS HMR.
+
+## Install
+
+```bash
+pnpm add @farm.js/stylex @stylexjs/stylex
+```
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { stylex } from "@farm.js/stylex";
+
+export default defineConfig({
+  plugins: [stylex()],
+});
+```
+
+Use the normal StyleX authoring API in application components:
+
+```tsx
+import * as stylex from "@stylexjs/stylex";
+
+const styles = stylex.create({
+  button: {
+    backgroundColor: "#111",
+    borderRadius: 8,
+    color: "white",
+    padding: "10px 16px",
+    ":hover": { backgroundColor: "#333" },
+  },
+});
+
+export function Button() {
+  return <button {...stylex.props(styles.button)}>Create project</button>;
+}
+```
+
+Farm selects StyleX's development or production compiler mode, injects the development stylesheet
+before paint, connects HMR, and appends extracted production rules to Farm's CSS output. Do not add
+StyleX virtual modules or stylesheet tags yourself.
+
+## External packages
+
+Dependencies are normally optimized as already-built code. Add a package to `externalPackages`
+when it publishes source containing uncompiled `stylex.create()` calls:
+
+```ts
+stylex({
+  externalPackages: ["@acme/ui", "shared-stylex-components"],
+});
+```
+
+Farm then excludes those packages from Vite dependency optimization and runs the StyleX compiler
+over them. Pass package names only, not file paths, glob patterns, or package subpaths. You do not
+need this option for packages that publish compiled StyleX output or ordinary CSS.
+
+Other StyleX compiler options such as `useCSSLayers`, `importSources`, `babelConfig`,
+`unstable_moduleResolution`, `lightningcssOptions`, and `cssInjectionTarget` pass through to
+`@stylexjs/unplugin`. Farm owns `dev`, `devMode`, and `devPersistToDisk` so development and build
+behavior cannot drift apart.

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import type { UserOptions } from "@stylexjs/unplugin";
+type FarmManagedStyleXOption = "dev" | "devMode" | "devPersistToDisk";
+/** StyleX compiler options. Farm owns the development mode and browser hookup. */
+export type StyleXOptions = Omit<Partial<UserOptions>, FarmManagedStyleXOption | "externalPackages"> & {
+    /**
+     * Packages in `node_modules` that publish uncompiled StyleX source.
+     * Farm de-optimizes and compiles these packages as application source.
+     */
+    externalPackages?: readonly string[];
+};
+export interface ResolvedStyleXOptions extends Omit<StyleXOptions, "externalPackages"> {
+    externalPackages: string[];
+}
+export declare function resolveStylexOptions(options?: StyleXOptions): ResolvedStyleXOptions;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,KAAK,uBAAuB,GAAG,KAAK,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAEtE,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,OAAO,CAAC,WAAW,CAAC,EACpB,uBAAuB,GAAG,kBAAkB,CAC7C,GAAG;IACF;;;OAGG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAEF,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,aAAa,EAAE,kBAAkB,CAAC;IACpF,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,qBAAqB,CAqBvF"}

package/dist/config.js

@@ -0,0 +1,27 @@
+export function resolveStylexOptions(options = {}) {
+    const externalPackages = options.externalPackages ?? [];
+    if (!Array.isArray(externalPackages)) {
+        throw new TypeError("[farm:stylex] externalPackages must be an array of package names");
+    }
+    const normalizedPackages = [];
+    for (const value of externalPackages) {
+        if (typeof value !== "string" || value.trim() === "") {
+            throw new TypeError("[farm:stylex] externalPackages must contain non-empty package names");
+        }
+        const packageName = value.trim();
+        if (!isPackageName(packageName)) {
+            throw new TypeError(`[farm:stylex] externalPackages must contain package names, not paths or subpath imports: ${JSON.stringify(value)}`);
+        }
+        if (!normalizedPackages.includes(packageName))
+            normalizedPackages.push(packageName);
+    }
+    return { ...options, externalPackages: normalizedPackages };
+}
+function isPackageName(value) {
+    if (value.startsWith(".") || value.startsWith("/") || value.includes("\\"))
+        return false;
+    const segments = value.split("/");
+    return value.startsWith("@")
+        ? segments.length === 2 && segments.every(Boolean)
+        : segments.length === 1;
+}

package/dist/html.d.ts

@@ -0,0 +1,5 @@
+/** Add StyleX's development CSS before paint and connect its HMR runtime. */
+export declare function injectStylexDevelopmentAssets(html: string, basePath?: string): string;
+/** Strip Farm's mount path before StyleX's development middleware resolves its virtual assets. */
+export declare function stripStylexDevelopmentBasePath(url: string, basePath: string): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAGA,6EAA6E;AAC7E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM,CAiBlF;AAED,kGAAkG;AAClG,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWpF"}

package/dist/html.js

@@ -0,0 +1,57 @@
+const STYLEX_DEVELOPMENT_CSS = "/virtual:stylex.css";
+const STYLEX_DEVELOPMENT_RUNTIME = "/@id/virtual:stylex:runtime";
+/** Add StyleX's development CSS before paint and connect its HMR runtime. */
+export function injectStylexDevelopmentAssets(html, basePath = "/") {
+    const closingHead = html.search(/<\/head\s*>/i);
+    if (closingHead < 0)
+        return html;
+    const head = html.slice(0, closingHead);
+    const cssUrl = withBasePath(STYLEX_DEVELOPMENT_CSS, basePath);
+    const runtimeUrl = withBasePath(STYLEX_DEVELOPMENT_RUNTIME, basePath);
+    const tags = [];
+    if (!hasStylexAsset(head, "link", "css")) {
+        tags.push(`<link rel="stylesheet" href="${cssUrl}" data-farm-stylex="css">`);
+    }
+    if (!hasStylexAsset(head, "script", "runtime")) {
+        tags.push(`<script type="module" src="${runtimeUrl}" data-farm-stylex="runtime"></script>`);
+    }
+    if (tags.length === 0)
+        return html;
+    return `${html.slice(0, closingHead)}${tags.join("")}${html.slice(closingHead)}`;
+}
+/** Strip Farm's mount path before StyleX's development middleware resolves its virtual assets. */
+export function stripStylexDevelopmentBasePath(url, basePath) {
+    const prefix = normalizeBasePath(basePath);
+    if (!prefix)
+        return url;
+    for (const asset of [STYLEX_DEVELOPMENT_CSS, STYLEX_DEVELOPMENT_RUNTIME]) {
+        const prefixedAsset = `${prefix}${asset}`;
+        if (url === prefixedAsset || url.startsWith(`${prefixedAsset}?`)) {
+            return url.slice(prefix.length);
+        }
+    }
+    return url;
+}
+function hasStylexAsset(html, tagName, value) {
+    const tags = tagName === "link"
+        ? html.matchAll(/<link\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi)
+        : html.matchAll(/<script\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi);
+    for (const tag of tags) {
+        const attributes = tag[0].slice(tagName.length + 1, -1);
+        const parsed = attributes.matchAll(/([^\s"'<>=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>]+)))?/g);
+        for (const attribute of parsed) {
+            const attributeValue = attribute[2] ?? attribute[3] ?? attribute[4];
+            if (attribute[1]?.toLowerCase() === "data-farm-stylex" && attributeValue === value) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function withBasePath(url, basePath) {
+    return `${normalizeBasePath(basePath)}${url}`;
+}
+function normalizeBasePath(basePath) {
+    const normalized = basePath.replace(/^\/+|\/+$/g, "");
+    return normalized ? `/${normalized}` : "";
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { type StyleXOptions } from "./config.js";
+export type { StyleXOptions };
+/** Compile StyleX and connect its extracted CSS to Farm development and production builds. */
+export declare function stylex(options?: StyleXOptions): import("@farm.js/core/plugin").FarmPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGvE,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,8FAA8F;AAC9F,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,6CAuDjD"}

package/dist/index.js

@@ -0,0 +1,89 @@
+import { definePlugin } from "@farm.js/core/plugin";
+import stylexUnplugin from "@stylexjs/unplugin";
+import { resolveStylexOptions } from "./config.js";
+import { injectStylexDevelopmentAssets, stripStylexDevelopmentBasePath } from "./html.js";
+/** Compile StyleX and connect its extracted CSS to Farm development and production builds. */
+export function stylex(options = {}) {
+    const resolved = resolveStylexOptions(options);
+    let development = false;
+    let configuredBasePath = "/";
+    return definePlugin({
+        name: "farm:stylex",
+        enforce: "pre",
+        configure(config, context) {
+            if ((config.plugins ?? []).filter((candidate) => candidate.name === "farm:stylex").length > 1) {
+                throw new Error("[farm:stylex] Configure StyleX in one stylex() plugin instance");
+            }
+            development = context.isDev;
+            configuredBasePath = readBasePath(config.basePath) ?? "/";
+            // @stylexjs/unplugin documents and implements externalPackages, but its
+            // 0.19.0 UserOptions declaration does not include the property yet.
+            const compilerOptions = {
+                ...resolved,
+                externalPackages: [...resolved.externalPackages],
+                dev: context.isDev,
+                devMode: context.isDev ? "full" : "off",
+            };
+            const vitePlugin = createStylexVitePlugin(compilerOptions, context.isDev);
+            const basePathPlugin = context.isDev && hasBasePath(configuredBasePath)
+                ? createStylexBasePathVitePlugin(configuredBasePath)
+                : undefined;
+            return {
+                ...config,
+                vite: {
+                    ...config.vite,
+                    plugins: [
+                        ...(basePathPlugin ? [basePathPlugin] : []),
+                        vitePlugin,
+                        ...(config.vite?.plugins ?? []),
+                    ],
+                },
+            };
+        },
+        render: {
+            html(html, _render, context) {
+                if (!development)
+                    return html;
+                return injectStylexDevelopmentAssets(html, readBasePath(context.config.basePath) ?? configuredBasePath);
+            },
+        },
+    });
+}
+function readBasePath(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function hasBasePath(value) {
+    return value.replace(/^\/+|\/+$/g, "").length > 0;
+}
+function createStylexBasePathVitePlugin(basePath) {
+    return {
+        name: "farm:stylex-base-path",
+        enforce: "pre",
+        configureServer(server) {
+            server.middlewares.use((request, _response, next) => {
+                if (request.url) {
+                    request.url = stripStylexDevelopmentBasePath(request.url, basePath);
+                }
+                next();
+            });
+        },
+    };
+}
+function createStylexVitePlugin(options, development) {
+    const plugins = stylexUnplugin.vite(options);
+    if (development)
+        return plugins;
+    const keepProductionTransforms = (plugin) => ({
+        ...plugin,
+        // Farm evaluates routes through an internal Vite server during builds.
+        // Keep compiler transforms active there without starting StyleX's dev
+        // middleware, HMR interval, or HTML injection hooks.
+        apply: () => true,
+        configureServer: undefined,
+        handleHotUpdate: undefined,
+        transformIndexHtml: undefined,
+    });
+    return Array.isArray(plugins)
+        ? plugins.map((plugin) => keepProductionTransforms(plugin))
+        : keepProductionTransforms(plugins);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@farm.js/stylex",
+  "version": "0.1.0-beta.0",
+  "description": "Zero-config StyleX compilation and HMR for Farm.js applications",
+  "keywords": [
+    "css-in-js",
+    "farm.js",
+    "stylex",
+    "vite"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-stylex"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@stylexjs/unplugin": "^0.19.0",
+    "unplugin": "^2.3.11",
+    "@farm.js/core": "0.1.0-beta.92"
+  },
+  "devDependencies": {
+    "@stylexjs/stylex": "^0.19.0",
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.10",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@stylexjs/stylex": "^0.19.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}