stylex-webpack 0.3.0 → 0.3.1

package/README.md

@@ -0,0 +1,228 @@
+# stylex-webpack
+
+[First introduced at React Conf 2020 by Frank Yan](https://www.youtube.com/watch?v=9JZHodNR184), [stylex](https://stylexjs.com/) is a framework agnostic CSS-in-JS system with near-zero runtime, ahead-of-time compiler, atomic CSS extraction that powers [Facebook.com](https://www.facebook.com).
+
+`stylex-webpack` is an alternative webpack plugin and loader for stylex.
+
+## Motivation
+
+stylex provides a CSS-in-JS compiler, which means you will write your CSS in your JavaScript/JSX/TSX. But unlike other CSS-in-JS solutions that collect and process styles inside the browser, stylex will read your source code, collect your style and transform your JS/JSX/TSX, stripping runtime calls as much as possible (making the value of `className` a static string literal), and output CSS elsewhere.
+
+stylex does provide a webpack plugin. Under the hood, it will traverse through the source code, collect styles, and emit a new CSS asset during the webpack compilation. However, it has some limitations:
+
+- stylex's official Next.js setup requires a `.babelrc` file, which disables Next.js' built-in SWC compiler.
+- stylex's official Next.js plugin requires a CSS asset to pre-exist so that it can append the extracted CSS to it.
+
+I start this project as a Proof of Concept, to see if it is possible to make a webpack plugin for ststylex that doesn't disable Next.js' SWC compiler. I have already made [a similar webpack plugin for style9](https://github.com/sukkaw/style9-webpack), which is also an AoT atomic CSS-in-JS system that is inspired by stylex.
+
+Unlike stylex's official webpack plugin, `stylex-webpack` requires you have setup `css-loader` and `MiniCssExtractPlugin` in your webpack configuration, just like your normal CSS based webpack project. `stylex-webpack`'s built-in loader will generate a virtual CSS import containing a dummy CSS rule. This allows the `MiniCssExtractPlugin` to collect those virtual CSS imports and emit a CSS asset, which `stylex-webpack` will later inject the actual extracted CSS into.
+
+## Installation
+
+```sh
+# npm
+npm i style9-webpack
+# Yarn
+yarn add style9-webpack
+# pnpm
+pnpm add style9-webpack
+```
+
+## Usage
+
+### Webpack
+
+```js
+// webpack.config.js
+const { StyleXPlugin } = require('stylex-webpack');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+
+module.exports = {
+  module: {
+    rules: [
+      // Just like your normal CSS setup, a css-loader and MiniCssExtractPlugin.loader
+      {
+        test: /\.css$/i,
+        use: [MiniCssExtractPlugin.loader, 'css-loader']
+      }
+    ]
+  },
+  plugins: [
+    new StyleXPlugin({
+      // stylex-webpack options goes here, see the following section for more details
+    }),
+    new MiniCssExtractPlugin(),
+    new CssMinimizerPlugin()
+    // You can also use `LightningCssMinifyPlugin` from `lightningcss-loader`
+    // to replace CssMinimizerPlugin for faster CSS minification
+    // https://github.com/fz6m/lightningcss-loader
+  ]
+};
+```
+
+### Next.js
+
+```js
+// next.config.js
+const { withStyleX } = require('stylex-webpack/next');
+
+module.exports = withStyle9({
+  // stylex-webpack options goes here, see the following section for more details
+})({
+  // Your Next.js config goes here.
+  reactStrictMode: true
+});
+```
+
+## Options
+
+### webpack
+
+```ts
+new StyleXPlugin({
+  // stylex-webpack options
+
+  /**
+   * stylex options passed to stylex babel plugin
+   *
+   * @see https://stylexjs.com/docs/api/configuration/babel-plugin/
+   */
+  stylexOption: {
+    dev: process.env.NODE_ENV === 'development',
+    test: process.env.NODE_ENV === 'test'
+    // Check the stylex documentation for more options
+  },
+  /* Specify where stylex will be imported from
+   * This overrides `importSources` in the `stylexOption` above
+   *
+   * @default ['stylex', '@stylexjs/stylex']
+   */
+  stylexImports: ['stylex', '@stylexjs/stylex'],
+  /**
+   * Whether to use CSS layers
+   *
+   * @default false
+   */
+  useCSSLayers?: boolean,
+  /**
+   * Enable other CSS transformation
+   *
+   * Since stylex-webpack's loader only emit virtual CSS imports with dummy rules,
+   * while the actual CSS is injected by the plugin after all loaders, you can not
+   * use postcss-loader + PostCSS plugins. You can manually transform the CSS here.
+   */
+  transformCss(css) {
+    const postcss = require('postcss');
+    const autoprefixer = require('autoprefixer');
+    /**
+     * It is a known issue that stylex won't sort your at-rules and media queries.
+     *
+     * https://github.com/facebook/stylex/issues/455
+     * https://github.com/facebook/stylex/issues/517
+     *
+     * For now, it is recommended to use postcss-sort-media-queries as a workaround.
+     */
+    const sortMediaQueries = require('postcss-sort-media-queries');
+
+    return postcss([
+      autoprefixer({
+        // autoprefixer options
+      }),
+      sortMediaQueries({
+        sort: 'mobile-first'
+      })
+    ]).process(css, { from: undefined }).css;
+
+    // If you don't use custom PostCSS plugins (like `postcss-sort-media-queries`
+    // mentioned above), only downleveling CSS syntax using autoprefixer, you can
+    // also use LightningCSS. It is a Rust-based CSS transformer and minifier that
+    // has built-in downleveling support.
+    const browserslist = require('browserslist');
+    const { transform, browserslistToTargets } = require('lightningcss');
+    return transform({
+      code: Buffer.from(css),
+      targets: browserslistToTargets(browserslist('>= 0.25%'))
+    }).code;
+
+    // If you don't need to transform CSS at all, you can just return the input as-is as well.
+    return css;
+  }
+});
+```
+
+### Next.js
+
+```ts
+withStyleX({
+  // The same options as the webpack plugin, but with a few differences
+  stylexOption: {
+    /**
+     * You don't have to specify `dev` here. `stylex-webpack` will automatically read
+     * Next.js building mode and set `dev` accordingly.
+     */
+    // dev: process.env.NODE_ENV === 'development',
+  },
+  /**
+   * You don't have to specify `transformCss` here. `stylex-webpack` will automatically
+   * read your PostCSS configuration and apply it here, just like how Next.js does.
+   *
+   * Under the hood, `withStyleX` uses Next.js built-in PostCSS config reader to
+   * maintain the consistency with Next.js' built-in PostCSS support.
+   */
+  // transformCss(css) {}
+})
+```
+
+It is recommended to use `postcss-sort-media-queries` as a workaround for stylex's known issue with sorting at-rules and media queries. You can configure it in your PostCSS configuration file, and `stylex-webpack` will automatically apply your PostCSS configuration to the extracted CSS just like Next.js' built-in PostCSS support.
+
+```js
+// postcss.config.js
+
+/** @type {Record<'plugins', import('postcss').AcceptedPlugin[]>} */
+module.exports = {
+  plugins: [
+    [
+      require.resolve('postcss-sort-media-queries'),
+      {
+        sort: 'mobile-first' // default value
+      }
+    ],
+
+    // Next.js will disable its built-in default PostCSS configuration you
+    // create `postcss.config.js`, which you can add it back:
+
+    /* --- Start of Next.js built-in default PostCSS configuration --- */
+    require.resolve('next/dist/compiled/postcss-flexbugs-fixes'),
+    [
+      require.resolve('next/dist/compiled/postcss-preset-env'),
+      {
+        browsers: ['defaults'],
+        autoprefixer: {
+          // Disable legacy flexbox support
+          flexbox: 'no-2009'
+        },
+        // Enable CSS features that have shipped to the
+        // web platform, i.e. in 2+ browsers unflagged.
+        stage: 3,
+        features: {
+          'custom-properties': false
+        }
+      }
+    ]
+    /* --- End of Next.js built-in default PostCSS configuration --- */
+  ]
+};
+```
+
+## Author
+
+**stylex-webpack** © [Sukka](https://github.com/SukkaW), Released under the [MIT](./LICENSE) License.<br>
+Authored and maintained by Sukka with help from contributors ([list](https://github.com/SukkaW/stylex-webpack/graphs/contributors)).
+
+> [Personal Website](https://skk.moe) · [Blog](https://blog.skk.moe) · GitHub [@SukkaW](https://github.com/SukkaW) · Telegram Channel [@SukkaChannel](https://t.me/SukkaChannel) · Twitter [@isukkaw](https://twitter.com/isukkaw) · Mastodon [@sukka@acg.mn](https://acg.mn/@sukka) · Keybase [@sukka](https://keybase.io/sukka)
+
+<p align="center">
+  <a href="https://github.com/sponsors/SukkaW/">
+    <img src="https://sponsor.cdn.skk.moe/sponsors.svg"/>
+  </a>
+</p>

package/dist/index.d.ts

@@ -9,6 +9,11 @@ interface StyleXLoaderOptions {
 
 type CSSTransformer = (css: string) => string | Buffer | Promise<string | Buffer>;
 interface StyleXPluginOption {
+    /**
+     * stylex options passed to stylex babel plugin
+     *
+     * @see https://stylexjs.com/docs/api/configuration/babel-plugin/
+     */
     stylexOption?: Partial<Options>;
     /**
      * Specify where stylex will be imported from

package/dist/index.js

@@ -7,6 +7,7 @@ const PLUGIN_NAME = 'stylex';
 const VIRTUAL_CSS_PATH = require.resolve('./stylex.virtual.css');
 const VIRTUAL_CSS_PATTERN = /stylex\.virtual\.css/;
 const STYLEX_CHUNK_NAME = '_stylex-webpack-generated';
+const INCLUDE_REGEXP = /\.[cm]?[jt]sx?$/;
 
 function _define_property(obj, key, value) {
     if (key in obj) {
@@ -71,8 +72,7 @@ class StyleXPlugin {
         compiler.hooks.make.tap(PLUGIN_NAME, (compilation)=>{
             NormalModule.getCompilationHooks(compilation).loader.tap(PLUGIN_NAME, (loaderContext, mod)=>{
                 const extname = path.extname(mod.matchResource || mod.resource);
-                if (// JavaScript (and Flow) modules
-                /\.jsx?/.test(extname) || /\.tsx?/.test(extname)) {
+                if (INCLUDE_REGEXP.test(extname)) {
                     loaderContext.StyleXWebpackContextKey = {
                         registerStyleXRules: (resourcePath, stylexRules)=>{
                             this.stylexRules.set(resourcePath, stylexRules);
@@ -113,7 +113,7 @@ class StyleXPlugin {
                     const cssModulesInStylexChunk = compilation.chunkGraph.getChunkModulesIterableBySourceType(stylexChunk, 'css/mini-extract');
                     // we only re-collect stylex rules if we can found css in the stylex chunk
                     if (cssModulesInStylexChunk) {
-                        this.stylexRules = new Map();
+                        this.stylexRules.clear();
                         for (const cssModule of cssModulesInStylexChunk){
                             const stringifiedStylexRule = cssModule._identifier.split('!').pop()?.split('?').pop();
                             if (!stringifiedStylexRule) {
@@ -128,7 +128,7 @@ class StyleXPlugin {
                     }
                 }
                 // Let's find the css file that belongs to the stylex chunk
-                const cssAssetDetails = Object.entries(assets).find(([assetName])=>stylexChunk.files.has(assetName) && assetName.includes(STYLEX_CHUNK_NAME));
+                const cssAssetDetails = Object.entries(assets).find(([assetName])=>stylexChunk.files.has(assetName) && assetName.endsWith('.css'));
                 if (!cssAssetDetails) {
                     return;
                 }

package/dist/next.d.ts

@@ -3,6 +3,11 @@ import { Options } from '@stylexjs/babel-plugin';
 
 type CSSTransformer = (css: string) => string | Buffer | Promise<string | Buffer>;
 interface StyleXPluginOption {
+    /**
+     * stylex options passed to stylex babel plugin
+     *
+     * @see https://stylexjs.com/docs/api/configuration/babel-plugin/
+     */
     stylexOption?: Partial<Options>;
     /**
      * Specify where stylex will be imported from

package/dist/next.js

@@ -144,6 +144,9 @@ const withStyleX = (pluginOptions)=>(nextConfig = {})=>{
                     async transformCss (css) {
                         const { postcssWithPlugins } = await postcss();
                         const result = await postcssWithPlugins.process(css);
+                        if (pluginOptions?.transformCss) {
+                            return pluginOptions.transformCss(result.css);
+                        }
                         return result.css;
                     }
                 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylex-webpack",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The another Webpack Plugin for Facebook's StyleX",
   "homepage": "https://github.com/SukkaW/style9-webpack#readme",
   "repository": {