@stylexjs/postcss-plugin 0.10.0-beta.2

package/README.md

@@ -0,0 +1,137 @@
+# @stylexjs/postcss-plugin
+
+## Documentation Website
+
+[https://stylexjs.com](https://stylexjs.com)
+
+## Installation
+
+Install the package by using:
+
+```bash
+npm install --save-dev @stylexjs/postcss-plugin autoprefixer
+```
+
+or with yarn:
+
+```
+yarn add --dev @stylexjs/postcss-plugin autoprefixer
+```
+
+Add the following to your `postcss.config.js`
+
+```javascript
+// postcss.config.js
+module.exports = {
+  plugins: {
+    '@stylexjs/postcss-plugin': {
+      include: ['src/**/*.{js,jsx,ts,tsx}'],
+    },
+    autoprefixer: {},
+  },
+};
+```
+
+Add the following to your `babel.config.js`
+
+```javascript
+import styleXPlugin from '@stylexjs/babel-plugin';
+
+const config = {
+  plugins: [
+    [
+      styleXPlugin,
+      {
+        // Required for this plugin
+        runtimeInjection: false,
+        dev: true,
+        // Set this to true for snapshot testing
+        // default: false
+        test: false,
+        // Required for CSS variable support
+        unstable_moduleResolution: {
+          // type: 'commonJS' | 'haste'
+          // default: 'commonJS'
+          type: 'commonJS',
+          // The absolute path to the root directory of your project
+          rootDir: __dirname,
+        },
+      },
+    ],
+  ],
+};
+
+export default config;
+```
+
+Add the following to `src/stylex.css`
+
+```css
+/**
+ * The @stylex directive is used by the @stylexjs/postcss-plugin.
+ * It is automatically replaced with generated CSS during builds.
+ */
+@stylex;
+```
+
+Then, import this file from your application entrypoint:
+
+```javascript
+// src/index.js
+import './stylex.css';
+```
+
+## Plugin Options
+
+### include
+
+```js
+include: string[] // Required
+```
+
+Array of paths or glob patterns to compile.
+
+---
+
+### exclude
+
+```js
+exclude: string[] // Default: []
+```
+
+Array of paths or glob patterns to exclude from compilation. Paths in exclude
+take precedence over include.
+
+---
+
+### cwd
+
+```js
+cwd: string; // Default: process.cwd()
+```
+
+Working directory for the plugin; defaults to process.cwd().
+
+---
+
+### babelConfig
+
+```js
+babelConfig: object; // Default: {}
+```
+
+Options for Babel configuration. By default, the plugin reads from
+babel.config.js in your project. For custom configurations, set babelrc: false
+and specify desired options. Refer to
+[Babel Config Options](https://babeljs.io/docs/options) for available options.
+
+---
+
+### useCSSLayers
+
+```js
+useCSSLayers: boolean; // Default: false
+```
+
+Enabling this option switches Stylex from using `:not(#\#)` to using `@layers`
+for handling CSS specificity.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@stylexjs/postcss-plugin",
+  "version": "0.10.0-beta.2",
+  "description": "PostCSS plugin for StyleX",
+  "main": "src/index.js",
+  "repository": "https://www.github.com/facebook/stylex",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/core": "^7.25.8",
+    "@stylexjs/babel-plugin": "0.10.0-beta.2",
+    "postcss": "^8.4.49",
+    "fast-glob": "^3.3.2",
+    "glob-parent": "^6.0.2",
+    "is-glob": "^4.0.3"
+  }
+}

package/src/builder.js

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { normalize, resolve } = require('path');
+const { globSync } = require('fast-glob');
+const isGlob = require('is-glob');
+const globParent = require('glob-parent');
+const createBundler = require('./bundler');
+
+// Parses a glob pattern and extracts its base directory and pattern.
+// Returns an object with `base` and `glob` properties.
+function parseGlob(pattern) {
+  // License: MIT
+  // Based on:
+  // https://github.com/chakra-ui/panda/blob/6ab003795c0b076efe6879a2e6a2a548cb96580e/packages/node/src/parse-glob.ts
+  let glob = pattern;
+  const base = globParent(pattern);
+
+  if (base !== '.') {
+    glob = pattern.substring(base.length);
+    if (glob.charAt(0) === '/') {
+      glob = glob.substring(1);
+    }
+  }
+
+  if (glob.substring(0, 2) === './') {
+    glob = glob.substring(2);
+  }
+  if (glob.charAt(0) === '/') {
+    glob = glob.substring(1);
+  }
+
+  return { base, glob };
+}
+
+// Parses a file path or glob pattern into a PostCSS dependency message.
+function parseDependency(fileOrGlob) {
+  // License: MIT
+  // Based on:
+  // https://github.com/chakra-ui/panda/blob/6ab003795c0b076efe6879a2e6a2a548cb96580e/packages/node/src/parse-dependency.ts
+  if (fileOrGlob.startsWith('!')) {
+    return null;
+  }
+
+  let message = null;
+
+  if (isGlob(fileOrGlob)) {
+    const { base, glob } = parseGlob(fileOrGlob);
+    message = { type: 'dir-dependency', dir: normalize(resolve(base)), glob };
+  } else {
+    message = { type: 'dependency', file: normalize(resolve(fileOrGlob)) };
+  }
+
+  return message;
+}
+
+// Creates a builder for transforming files and bundling StyleX CSS.
+function createBuilder() {
+  let config = null;
+
+  const bundler = createBundler();
+
+  const fileModifiedMap = new Map();
+
+  // Configures the builder with the provided options.
+  function configure(options) {
+    config = options;
+  }
+
+  /// Retrieves the current configuration.
+  function getConfig() {
+    if (config == null) {
+      throw new Error('Builder not configured');
+    }
+    return config;
+  }
+
+  // Finds the `@stylex;` at-rule in the provided PostCSS root.
+  function findStyleXAtRule(root) {
+    let styleXAtRule = null;
+    root.walkAtRules((atRule) => {
+      if (atRule.name === 'stylex' && !atRule.params) {
+        styleXAtRule = atRule;
+      }
+    });
+    return styleXAtRule;
+  }
+
+  // Retrieves all files that match the include and exclude patterns.
+  function getFiles() {
+    const { cwd, include, exclude } = getConfig();
+    return globSync(include, {
+      onlyFiles: true,
+      ignore: exclude,
+      cwd,
+    });
+  }
+
+  // Transforms the included files, bundles the CSS, and returns the result.
+  async function build({ shouldSkipTransformError }) {
+    const { cwd, babelConfig, useCSSLayers, isDev } = getConfig();
+
+    const files = getFiles();
+    const filesToTransform = [];
+
+    // Remove deleted files since the last build
+    for (const file of fileModifiedMap.keys()) {
+      if (!files.includes(file)) {
+        fileModifiedMap.delete(file);
+        bundler.remove(file);
+      }
+    }
+
+    for (const file of files) {
+      const filePath = path.resolve(cwd, file);
+      const mtimeMs = fs.existsSync(filePath)
+        ? fs.statSync(filePath).mtimeMs
+        : -Infinity;
+
+      // Skip files that have not been modified since the last build
+      // On first run, all files will be transformed
+      const shouldSkip =
+        fileModifiedMap.has(file) && mtimeMs === fileModifiedMap.get(file);
+
+      if (shouldSkip) {
+        continue;
+      }
+
+      fileModifiedMap.set(file, mtimeMs);
+      filesToTransform.push(file);
+    }
+
+    await Promise.all(
+      filesToTransform.map((file) => {
+        const filePath = path.resolve(cwd, file);
+        const contents = fs.readFileSync(filePath, 'utf-8');
+        if (!bundler.shouldTransform(contents)) {
+          return;
+        }
+        return bundler.transform(file, contents, babelConfig, {
+          isDev,
+          shouldSkipTransformError,
+        });
+      }),
+    );
+
+    const css = bundler.bundle({ useCSSLayers });
+    return css;
+  }
+
+  // Retrieves the dependencies that PostCSS should watch.
+  function getDependencies() {
+    const { include } = getConfig();
+    const dependencies = [];
+
+    for (const fileOrGlob of include) {
+      const dependency = parseDependency(fileOrGlob);
+      if (dependency != null) {
+        dependencies.push(dependency);
+      }
+    }
+
+    return dependencies;
+  }
+
+  return {
+    findStyleXAtRule,
+    configure,
+    build,
+    getDependencies,
+  };
+}
+
+module.exports = createBuilder;

package/src/bundler.js

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+const babel = require('@babel/core');
+const stylexBabelPlugin = require('@stylexjs/babel-plugin');
+
+// Creates a stateful bundler for processing StyleX rules using Babel.
+module.exports = function createBundler() {
+  const styleXRulesMap = new Map();
+
+  // Determines if the source code should be transformed based on the presence of StyleX imports.
+  function shouldTransform(sourceCode) {
+    return sourceCode.includes('stylex');
+  }
+
+  // Transforms the source code using Babel, extracting StyleX rules and storing them.
+  async function transform(id, sourceCode, babelConfig, options) {
+    const { isDev, shouldSkipTransformError } = options;
+    const { code, map, metadata } = await babel
+      .transformAsync(sourceCode, {
+        filename: id,
+        caller: {
+          name: '@stylexjs/postcss-plugin',
+          isDev,
+        },
+        ...babelConfig,
+      })
+      .catch((error) => {
+        if (shouldSkipTransformError) {
+          console.warn(
+            `[@stylexjs/postcss-plugin] Failed to transform "${id}": ${error.message}`,
+          );
+
+          return { code: sourceCode, map: null, metadata: {} };
+        }
+        throw error;
+      });
+
+    const stylex = metadata.stylex;
+    if (stylex != null && stylex.length > 0) {
+      styleXRulesMap.set(id, stylex);
+    }
+
+    return { code, map, metadata };
+  }
+
+  // Removes the stored StyleX rules for the specified file.
+  function remove(id) {
+    styleXRulesMap.delete(id);
+  }
+
+  //  Bundles all collected StyleX rules into a single CSS string.
+  function bundle({ useCSSLayers }) {
+    const rules = Array.from(styleXRulesMap.values()).flat();
+
+    const css = stylexBabelPlugin.processStylexRules(rules, useCSSLayers);
+
+    return css;
+  }
+
+  return {
+    shouldTransform,
+    transform,
+    remove,
+    bundle,
+  };
+};

package/src/index.js

@@ -0,0 +1,101 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+const postcss = require('postcss');
+const createBuilder = require('./builder');
+
+const PLUGIN_NAME = '@stylexjs/postcss-plugin';
+
+const builder = createBuilder();
+
+const isDev = process.env.NODE_ENV === 'development';
+
+const plugin = ({
+  cwd = process.cwd(),
+  // By default reuses the Babel configuration from the project root.
+  // Use `babelrc: false` to disable this behavior.
+  babelConfig = {},
+  include,
+  exclude,
+  useCSSLayers = false,
+}) => {
+  exclude = [
+    // Exclude type declaration files by default because it never contains any CSS rules.
+    '**/*.d.ts',
+    '**/*.flow',
+    ...(exclude ?? []),
+  ];
+
+  // Whether to skip the error when transforming StyleX rules.
+  // Useful in watch mode where Fast Refresh can recover from errors.
+  // Initial transform will still throw errors in watch mode to surface issues early.
+  let shouldSkipTransformError = false;
+
+  return {
+    postcssPlugin: PLUGIN_NAME,
+    plugins: [
+      // Processes the PostCSS root node to find and transform StyleX at-rules.
+      async function (root, result) {
+        const fileName = result.opts.from;
+
+        // Configure the builder with the provided options
+        await builder.configure({
+          include,
+          exclude,
+          cwd,
+          babelConfig,
+          useCSSLayers,
+          isDev,
+        });
+
+        // Find the "@stylex" at-rule
+        const styleXAtRule = builder.findStyleXAtRule(root);
+        if (styleXAtRule == null) {
+          return;
+        }
+
+        // Get dependencies to be watched for changes
+        const dependencies = builder.getDependencies();
+
+        // Add each dependency to the PostCSS result messages.
+        // This watches the entire "./src" directory for "./src/**/*.{ts,tsx}"
+        // to handle new files and deletions reliably in watch mode.
+        for (const dependency of dependencies) {
+          result.messages.push({
+            plugin: PLUGIN_NAME,
+            parent: fileName,
+            ...dependency,
+          });
+        }
+
+        // Build and parse the CSS from collected StyleX rules
+        const css = await builder.build({
+          shouldSkipTransformError,
+        });
+        const parsed = await postcss.parse(css, {
+          from: fileName,
+        });
+
+        // Replace the "@stylex" rule with the generated CSS
+        styleXAtRule.replaceWith(parsed);
+
+        result.root = root;
+
+        if (!shouldSkipTransformError) {
+          // Build was successful, subsequent builds are for watch mode
+          shouldSkipTransformError = true;
+        }
+      },
+    ],
+  };
+};
+
+plugin.postcss = true;
+
+module.exports = plugin;