Best Practice for a Single-File Widget Build with ESBuild?

[BMCwebdev]

Hi everyone,

I'm hoping to get some expert advice on the best practice for a specific build scenario.

The Challenge:
I am integrating my StyleX-based design system into a pre-existing, drop-in widget. I have to work within the project's established architecture, which has two firm requirements:

1. The final output must be a single, self-contained JavaScript file (IIFE format).
2. The build system uses ESBuild.

The widget itself is a web component that uses a Shadow DOM, so the CSS must be bundled inside the final JS file to be injected at runtime. An earlier attempt to convert the build to Vite was unsuccessful due to fundamental conflicts between Vite's ESM-first approach and the IIFE output requirement.

My Proposed Solution:
Since StyleX plugins like the PostCSS one is designed to output a separate .css file, (and I can't use that approach) I'm planning a custom build script.

The theory is:

1. Transform with Babel: Use Babel's Node.js API to transform the source code. I then programmatically capture the generated CSS rules from the babelResult.metadata.stylex array.
2. Inject and Bundle with ESBuild: Pass the transformed code and the CSS string to ESBuild. I use the define option to make the CSS available as a global constant, which is then injected into a <style> tag within the component.

// build.js
const esbuild = require('esbuild');
const babel = require('@babel/core');
// ... file system imports

async function build() {
  // ... try/catch block

  // 1. Transform with Babel and get CSS from metadata
  const babelResult = babel.transformSync(sourceCode, {
    presets: ['@babel/preset-react'],
    plugins: ['@stylexjs/babel-plugin'],
  });
  const generatedCss = babelResult.metadata.stylex.join('\n');
  const transformedJs = babelResult.code;
  
  // 2. Inject CSS string and bundle with ESBuild
  await esbuild.build({
    stdin: { contents: transformedJs, /* ... */ },
    bundle: true,
    outfile: 'dist/widget.bundle.js',
    format: 'iife',
    define: { '__STYLEX_CSS__': JSON.stringify(generatedCss) },
    minify: true,
  });
}
build();

My Question:
Given that my project absolutely requires a single-file output and must use ESBuild, is this programmatic approach of capturing the styles from Babel's metadata the recommended best practice?

It seems to be the only viable path, but I wanted to run it by the experts here to ensure I'm not missing a more official or robust method for this kind of integration.

Thanks so much for your time!

[BMCwebdev]

So far I am having success. I have a follow up after, but first I will share what is working for me in case anyone is looking to do the same thing.

// eslint-disable-next-line @typescript-eslint/no-require-imports
const babel = require('@babel/core');
// eslint-disable-next-line @typescript-eslint/no-require-imports
const stylexPlugin = require('@stylexjs/babel-plugin');
// eslint-disable-next-line @typescript-eslint/no-require-imports
const { processStylexRules } = require('@stylexjs/babel-plugin');

// Design System components use StyleX for styling. StyleX generates atomic CSS classes at build time
// and compiles away stylex.create() calls, replacing them with generated classnames.
// The CSS is extracted here and inlined into the JS bundle for Shadow DOM injection.
// Process: transformWithStyleX() extracts CSS → babel-stylex-transform plugin applies it → cssInjectionCode inlines it
// → Runtime: acme-agent.js applies CSS to Shadow DOM via constructable stylesheets

// StyleX CSS collection
let collectedCSS = '';

// Babel transformation for StyleX - processes all files and extracts CSS from StyleX code
function transformWithStyleX(code, filename) {
  try {
    const result = babel.transformSync(code, {
      filename,
      plugins: [
        [stylexPlugin, {
          dev: process.argv.includes('--dev'),
          genConditionalClasses: false,
          treeshakeCompensation: true,
          unstable_moduleResolution: {
            type: 'commonJS',
            rootDir: path.resolve(__dirname, '../../../..'), // Project root
          },
        }],
        '@babel/plugin-syntax-jsx',
      ],
      presets: [
        ['@babel/preset-react', {
          runtime: 'automatic'
        }],
        ['@babel/preset-typescript', {
          isTSX: true,
          allExtensions: true
        }]
      ],
    });

    // Extract and accumulate StyleX CSS from compiled components
    if (result?.metadata && 'stylex' in result.metadata) {
      const stylexRules = result.metadata.stylex;
      if (Array.isArray(stylexRules) && stylexRules.length > 0) {
        const processedCSS = processStylexRules(stylexRules, false);
        collectedCSS += processedCSS;
      }
    }

// ...

    return result?.code || code;
  } catch (error) {
    console.error(`Babel transformation failed for ${filename}:`, error);
    throw error; // Let the build fail completely
  }
}

// ...

    await esbuild.build({
      // ...
        plugins: [
          {
            name: 'babel-stylex-transform',
            setup(build) {
              // Transform JS/JSX/TS/TSX files with Babel + StyleX
              // Note: Currently processes all files - could be optimized to target only Design System files and app files
              build.onLoad({ filter: /\.(js|jsx|ts|tsx)$/ }, async (args) => {
                console.log(`Transforming: ${args.path}`);
                const code = await fs.promises.readFile(args.path, 'utf8');
                const transformedCode = transformWithStyleX(code, args.path);
                return {
                  contents: transformedCode,
                  loader: args.path.endsWith('.tsx') || args.path.endsWith('.ts') ? 'tsx' : 'jsx',
                };
              });
            },
          },
        ],

   // ...

    // Inject StyleX CSS into the bundle
    if (collectedCSS) {
      const cssInjectionCode = `
// StyleX CSS injection
window.__ACMEAGENT_STYLEX_CSS__ = ${JSON.stringify(collectedCSS)};
`;
      bundledCode = cssInjectionCode + bundledCode;
    }

and the runtime part of it

    // Apply StyleX CSS using constructable stylesheets (supported in all modern browsers except IE11)
    if (typeof CSSStyleSheet !== 'undefined' && window.__ACMEAGENT_STYLEX_CSS__) {
      const sheet = new CSSStyleSheet();
      sheet.replaceSync(window.__ACMEAGENT_STYLEX_CSS__);
      this.shadowRoot.adoptedStyleSheets = [sheet];
    } else {
      console.log('CSS not found or CSSStyleSheet not supported');
    }

[BMCwebdev]

Okay, follow up. And, as you'll see, I use named CSS variables (the -- escape hatch).

StyleX generates CSS that looks like this:

:root, .x2bm72k {
  --my-color-primary: #blue;
  --my-spacing-lg: 16px;
  /* ...  */
}

In a regular DOM setup, the :root selector works perfectly for accessing these variables throughout the component tree. However, in Shadow DOM, the :root selector from the main document doesn't apply to elements inside the shadow tree.

Current Solution

I've implemented a working solution that extracts the StyleX-generated classname from the compiled CSS and applies it to a container element in my Shadow DOM:

// Extract StyleX token classname dynamically from injected CSS
let tokenClassName = 'x2bm72k'; // fallback for backward compatibility

if (window.__ACMEAGENT_STYLEX_CSS__) {
  // Look for the pattern ":root, .classname{" which contains the StyleX token variables
  const match = window.__ACMEAGENT_STYLEX_CSS__.match(/:root,\s*\.([a-z0-9]+)\s*\{/);
  if (match) {
    tokenClassName = match[1];
    console.log(`[AcmeAgent] Using StyleX token classname: ${tokenClassName}`);
  }
}

// Apply to shadow DOM container
shadowDomContainer.className = tokenClassName;

This works well - all CSS variables become available to child elements in the Shadow DOM through normal CSS inheritance.

Questions

1. Is there a more reliable/official way to access the StyleX token classname? Currently I'm parsing it from the generated CSS string, but I'm wondering if StyleX exposes this information through its API.
2. Any better ideas?

[nmn]

The widget itself is a web component that uses a Shadow DOM.

Atomic CSS is a bad fit for shadow DOM.

ESBuild

The Rollup plugin should work with ESBuild. You're on your own to make it work in development. If you don't have server components involved, you could probably just use runtimeInjection for dev.

CSS inside the JS file

You should be able to add a placeholder string in your original JS, and then patch it with the final CSS with a custom ESBuild plugin.

The build process for StyleX is conceptually very simple:

1. Transform all the JS files with the StyleX Babel plugin
2. Collect metadata.stylex the result of the Babel transformation
3. Take all the collected metadata from all the files and use the processStylexRules function exported from the Babel plugin. This will give you your output CSS file as a string.

If you look at the Rollup plugin, it writes that CSS string to a file. You should instead be able to find and replace the placeholder string in your JS bundle with the CSS string instead.

The PostCSS plugin was created because existing bundlers don't make this process easy, except for Rollup.

Dealing with :root

The find and replace is a decent solution, but you can just .replaceAll(':root', ':host') to get the effect you want.

If you want to make the same CSS usable both inside a shadow DOM and not, you can use: .replaceAll(':root', ':where(:root, :host)')

---

Overall you already seem to be on the right path, so hopefully all this makes sense. Just another headsup that since atomic CSS is not a good fit for shadow DOM, I'm not sure it's a good idea to use StyleX for small web component at all. Only do so, if this shadow DOM contains something large enough to be considered a "mini app".

[BMCwebdev]

Thanks @nmn .

Yeah, everything is working currently with the setup I have, I'm just worried about fragility.

Didn't think of the Rollup plugin. Might take a second look at that. For now just using the Babel plugin. Not so worried about dev right now. The current build requires that you build the widget, then use it in a NextJS dev app for local testing. So the widget is always a full build.

Atomic CSS is a bad fit for shadow DOM.

I am very interested in this.

So, I'm calling it a widget because they are, but yes, it's complex enough to be considered an app. Basically an agentic chatbot that can be dropped into any of our company's applications. Shadow DOM certainly is causing me grief in several ways.

Hey, thanks again for taking a look at this! Much appreciated.

[BMCwebdev]

Hey there @nmn cleaning up my old threads. Before I close this one, quick question. You said "Atomic CSS is a bad fit for shadow DOM." Would you mind sharing some of your thoughts on this? Thanks!

[nmn]

Yes, Atomic CSS is a bad fit for shadow DOM, but specifically when there are many smaller components which all use their own shadow DOMs. If you have a large that just happens to be embedded within a shadow DOM, then it's fine.

If you're using web components to build an app and the web components use shadow DOM, you end up loading the same CSS over and over again in every shadow dom context and most of the styles are unused in each context, so the efficiency benefits of making CSS sharable is lost. Shadow DOM instead lets the browser process small CSS files in isolation for each component so you end up getting the same load time performance as CSS modules but with faster style recalculation.

Shadow DOM's biggest value is style isolation. When using atomic CSS, this should generally be redundant. So my recommendation is that if you're using atomic CSS, skip shadow DOM even if you do use web components.