Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
12.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use strict';

/**
 * @astryxdesign/postcss-plugin
 *
 * PostCSS plugin for Astryx source builds. Compiles StyleX from both
 * Astryx library source and product code in two separate passes with
 * different class name prefixes, then outputs them in separate layers:
 *
 *   reset < astryx-base (library, prefix: 'astryx') < astryx-theme < product (prefix: 'x')
 *
 * Library source is what each installed Astryx package publishes (its
 * `files`), so a package linked from a workspace contributes what a registry
 * install of it would.
 *
 * The separate prefixes ensure atomic classes don't collide between
 * layers, which would break theme overrides. Generated replacement CSS is
 * parsed by the host PostCSS instance so consumers do not load a second copy.
 * The library pass reads no Babel config file, so the app's own Babel config
 * never transforms Astryx source; the product pass still loads it.
 */

const path = require('node:path');
const {isSwizzledSource} = require('./swizzle-marker');
const fs = require('node:fs');
const babel = require('@babel/core');
const stylexBabelPlugin = require('@stylexjs/babel-plugin');
const {escapePath, globSync} = require('fast-glob');
const isGlob = require('is-glob');
const globParent = require('glob-parent');

const PLUGIN_NAME = '@astryxdesign/postcss-plugin';

const LIBRARY_SCOPE = 'node_modules/@astryxdesign';
const LIBRARY_SOURCE = /\.tsx?$/;
const LIBRARY_PATTERNS = [
  'node_modules/@astryxdesign/',
  'packages/core/',
  'packages/themes/',
];
const STYLEX_IMPORT_SOURCE = '@stylexjs/stylex';

/**
 * Globs for the source each installed Astryx package publishes: each positive
 * `files` entry is a directory (the files below it) or a file, while negated
 * entries become discovery exclusions. Positive entries with glob characters
 * are refused rather than approximated. A package's own `node_modules` is never
 * scanned: in a workspace its links can lead back to the package (here, core's
 * dev dependency `@astryxdesign/cli` links core again).
 */
function libraryGlobs(cwd) {
  const include = [];
  const ignore = [];
  const scope = path.join(cwd, LIBRARY_SCOPE);
  const seen = new Set();
  for (const name of fs.existsSync(scope) ? fs.readdirSync(scope) : []) {
    const dir = path.join(scope, name);
    const manifest = path.join(dir, 'package.json');
    if (!fs.existsSync(manifest)) continue;
    const real = fs.realpathSync(dir);
    if (seen.has(real)) continue;
    seen.add(real);
    const base = `${LIBRARY_SCOPE}/${name}`;
    ignore.push(`${base}/**/node_modules/**`);
    const {files} = JSON.parse(fs.readFileSync(manifest, 'utf8'));
    if (!Array.isArray(files)) {
      include.push(`${base}/**/*.{ts,tsx}`);
      continue;
    }
    for (const entry of files) {
      if (entry.startsWith('!')) {
        const excluded = entry.slice(1).replace(/^\.?\/|\/$/g, '');
        if (excluded) ignore.push(`${base}/${excluded}`);
        continue;
      }
      if (isGlob(entry)) {
        throw new Error(
          `@astryxdesign/build reads plain positive files entries only; @astryxdesign/${name} lists "${entry}"`,
        );
      }
      const plain = entry.replace(/^\.?\/|\/$/g, '');
      const target = path.join(dir, plain);
      const isDirectory =
        fs.existsSync(target) && fs.statSync(target).isDirectory();
      include.push(
        isDirectory
          ? `${base}/${escapePath(plain)}/**/*.{ts,tsx}`
          : `${base}/${escapePath(plain)}`,
      );
    }
  }
  return {include, ignore};
}

function parseDependency(fileOrGlob, cwd) {
  if (fileOrGlob.startsWith('!')) return null;
  if (isGlob(fileOrGlob)) {
    const base = globParent(fileOrGlob);
    let glob = fileOrGlob.substring(base === '.' ? 0 : base.length);
    if (glob.charAt(0) === '/') glob = glob.substring(1);
    return {
      type: 'dir-dependency',
      dir: path.normalize(path.resolve(cwd, base)),
      glob,
    };
  }
  return {
    type: 'dependency',
    file: path.normalize(path.resolve(cwd, fileOrGlob)),
  };
}

/**
 * Clone a babel plugins array, overriding the classNamePrefix on the
 * StyleX babel plugin entry.
 */
function withClassNamePrefix(plugins, prefix) {
  return plugins.map(p => {
    if (!Array.isArray(p)) return p;
    const [pluginPath, opts] = p;
    // Match @stylexjs/babel-plugin by name
    const name = typeof pluginPath === 'string' ? pluginPath : '';
    if (name.includes('@stylexjs/babel-plugin') || name.includes('stylex')) {
      return [pluginPath, {...opts, classNamePrefix: prefix}];
    }
    return p;
  });
}

function createPlugin() {
  const isDev = process.env.NODE_ENV === 'development';

  // Separate rule maps for library and product
  const libraryRulesMap = new Map();
  const productRulesMap = new Map();
  const fileModifiedMap = new Map();

  const plugin = ({
    cwd = process.cwd(),
    appDir = 'src',
    babelPlugins = [],
    layers = {
      library: 'astryx-base',
      product: 'product',
    },
    // Class name prefix for library styles (product keeps default 'x')
    libraryPrefix = 'astryx',
    extraInclude = [],
    libraryPatterns = LIBRARY_PATTERNS,
    exclude = [],
  }) => {
    const appInclude = `${appDir}/**/*.{js,jsx,ts,tsx}`;

    const excludeWithDefaults = ['**/*.d.ts', '**/*.flow', ...exclude];

    // Two babel configs — different classNamePrefix
    const libraryBabelConfig = {
      babelrc: false,
      // Astryx source needs only the StyleX plugin. Without this, Babel also
      // loads the app's root config (`next/babel` in the documented setup),
      // and its preset-env rewrites package source the app cannot change,
      // such as `\p{…}` regular expressions, before StyleX reads it.
      configFile: false,
      parserOpts: {plugins: ['typescript', 'jsx']},
      plugins: withClassNamePrefix(babelPlugins, libraryPrefix),
    };

    const productBabelConfig = {
      babelrc: false,
      parserOpts: {plugins: ['typescript', 'jsx']},
      plugins: babelPlugins, // keeps default 'x' prefix
    };

    let shouldSkipTransformError = false;

    return {
      postcssPlugin: PLUGIN_NAME,
      plugins: [
        async function (root, result) {
          if (process.env.TURBOPACK && process.env.ASTRYX_BUILD_TURBOPACK) {
            throw new Error(
              'withAstryx() under Turbopack cannot run beside @astryxdesign/build/postcss, ' +
                "the webpack setup's PostCSS plugin: its rules never match the classes " +
                'Turbopack renders, so every Astryx component would be unstyled. Use ' +
                "'@astryxdesign/build/next/postcss' and `@astryx;` (see the " +
                '@astryxdesign/build README), or build with `next build --webpack`.',
            );
          }
          const fileName = result.opts.from;

          let styleXAtRule = null;
          root.walkAtRules(atRule => {
            if (atRule.name === 'stylex' && !atRule.params) {
              styleXAtRule = atRule;
            }
          });
          if (styleXAtRule == null) return;

          // Discover files: the app's own, and the source each installed
          // Astryx package publishes
          const library = libraryGlobs(cwd);
          const files = new Set();
          const discover = (patterns, ignore, keep) => {
            for (const pattern of patterns) {
              const matched = globSync(pattern, {onlyFiles: true, ignore, cwd});
              for (const f of matched) {
                if (keep(f)) files.add(path.normalize(path.resolve(cwd, f)));
              }
            }
          };
          const include = [appInclude, ...library.include, ...extraInclude];
          discover([appInclude], excludeWithDefaults, () => true);
          discover(
            library.include,
            [...excludeWithDefaults, ...library.ignore],
            f => LIBRARY_SOURCE.test(f),
          );
          discover(extraInclude, excludeWithDefaults, () => true);

          // Watch dependencies
          for (const pattern of include) {
            const dep = parseDependency(pattern, cwd);
            if (dep) {
              result.messages.push({
                plugin: PLUGIN_NAME,
                parent: fileName,
                ...dep,
              });
            }
          }

          // Remove deleted files
          for (const f of fileModifiedMap.keys()) {
            if (!files.has(f)) {
              fileModifiedMap.delete(f);
              libraryRulesMap.delete(f);
              productRulesMap.delete(f);
            }
          }

          // Partition files into library vs product, then compile
          // each group with its own babel config (different prefix)
          const transforms = [];
          // A swizzled copy is Astryx source too: it compiles in the library pass.
          const markerMemo = new Map();
          for (const filePath of files) {
            // Classify every file on each pass: when a marker appears or goes,
            // `withAstryx()` rebuilds the copy with the other prefix.
            const isLibrary =
              libraryPatterns.some(p => filePath.includes(p)) ||
              isSwizzledSource(filePath, markerMemo);
            const rulesMap = isLibrary ? libraryRulesMap : productRulesMap;
            const movedSides = (
              isLibrary ? productRulesMap : libraryRulesMap
            ).delete(filePath);

            const mtimeMs = fs.existsSync(filePath)
              ? fs.statSync(filePath).mtimeMs
              : -Infinity;
            if (
              !movedSides &&
              fileModifiedMap.has(filePath) &&
              mtimeMs === fileModifiedMap.get(filePath)
            ) {
              continue;
            }
            fileModifiedMap.set(filePath, mtimeMs);

            const contents = fs.readFileSync(filePath, 'utf-8');
            if (!contents.includes(STYLEX_IMPORT_SOURCE)) continue;

            const config = isLibrary ? libraryBabelConfig : productBabelConfig;

            transforms.push(
              babel
                .transformAsync(contents, {
                  filename: filePath,
                  caller: {name: PLUGIN_NAME, platform: 'web', isDev},
                  ...config,
                })
                .then(({metadata}) => {
                  const stylex = metadata?.stylex;
                  if (stylex != null && stylex.length > 0) {
                    rulesMap.set(filePath, stylex);
                  }
                })
                .catch(error => {
                  if (shouldSkipTransformError) {
                    console.warn(
                      `[${PLUGIN_NAME}] Failed to transform "${filePath}": ${error.message}`,
                    );
                  } else {
                    throw error;
                  }
                }),
            );
          }
          await Promise.all(transforms);

          // Collect rules from each map
          const libraryRules = Array.from(libraryRulesMap.values()).flat();
          const productRules = Array.from(productRulesMap.values()).flat();

          // Process each group separately
          const libraryCss = libraryRules.length
            ? stylexBabelPlugin.processStylexRules(libraryRules, {
                useLayers: true,
              })
            : '';
          const productCss = productRules.length
            ? stylexBabelPlugin.processStylexRules(productRules, {
                useLayers: true,
              })
            : '';

          // Wrap in named layers
          const parts = [];
          if (libraryCss) {
            parts.push(`@layer ${layers.library} {\n${libraryCss}\n}`);
          }
          if (productCss) {
            parts.push(`@layer ${layers.product} {\n${productCss}\n}`);
          }

          // Let the host PostCSS instance parse the replacement so this plugin
          // does not need or load a second copy of PostCSS.
          styleXAtRule.replaceWith(parts.join('\n\n'));
          result.root = root;

          if (!shouldSkipTransformError) {
            shouldSkipTransformError = true;
          }
        },
      ],
    };
  };

  plugin.postcss = true;
  return plugin;
}

module.exports = createPlugin();