docs: v0.10.0 releate notes

facebook · Jan 2, 2025 · eb62148 · eb62148
1 parent 44428fc
commit eb62148
Show file tree

Hide file tree

Showing 3 changed files with 145 additions and 90 deletions.
diff --git a/apps/docs/blog/2025-01-02-Release-v0.10.0.mdx b/apps/docs/blog/2025-01-02-Release-v0.10.0.mdx
@@ -0,0 +1,89 @@
+---
+# 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.
+slug: v0.10.0
+title: Release 0.10.0
+authors: 
+  - nmn
+tags: 
+  - release
+---
+
+Happy new year! We are excited to announce the release of StyleX v0.10.0, which includes several new features and improvements.
+
+## Easier adoption with the all-new PostCSS plugin
+
+StyleX now ships with an all-new PostCSS plugin. This plugin allows you to use StyleX with any PostCSS-compatible toolchain,
+to better integrate with existing projects. The PostCSS plugin is now our recommended approach for using StyleX
+in a Next.js or Vite project. The example Next.js app in this repository has been updated to reflect this change. The existing 
+`@stylexjs/nextjs-plugin` will be deprecated in the next release.
+
+A huge thanks to [javascripter](https://github.com/javascripter/) for contributing this plugin.
+
+## Better debugging
+
+StyleX has a new `debug` option to enable more readable classNames and variable names during development.
+With this option turned on, classNames will be prefixed with the affected CSS property and variables will
+be prefixed with their key name in your source code. (Thanks [mellyeliu](https://github.com/mellyeliu/))
+
+Additionally, the error messages of the StyleX Babel plugin have been improved to be more granular and
+correctly highlight the location of the source code causing the error.
+
+## ESLint improvements
+
+### All new `no-unused` rule
+
+The StyleX ESLint plugin now ships with a new `no-unused` rule that detects unused styles. (Thanks [Samantha-Zhan](https://github.com/Samantha-Zhan/))
+
+### Other improvements
+
+The `valid-styles` rule now offers more auto-fixes, and a small bug was fixed in the `valid-shorthands` rule.
+(Thanks [mellyeliu](https://github.com/mellyeliu/))
+
+## Theming now works without manually configuring `rootDir`
+
+StyleX previously required manual configuration of `unstable_moduleResolution.rootDir` for enabling
+the theming APIs. This is no longer the case. Additionally, compilation should be more reliable
+and cache-friendly, especially when using package managers like `pnpm`.
+
+## Performance improvements for Dynamic styles
+
+StyleX uses CSS custom properties (aka CSS variables) as inline styles for dynamic values for styles.
+In v0.10.0 StyleX now generates `@property` declarations marking these variables as non-inheritable.
+This improves the style resolution performance of the browser's styling engine, which in some cases can
+be quite significant. We have also updated our benchmarks to track the code size impact of this change.
+(Thanks [Samantha-Zhan](https://github.com/Samantha-Zhan/))
+
+## CLI improvements
+
+### Caching
+
+The StyleX CLI now uses a cache by default which ensures that only changed files are recompiled.
+This cache is stored in the nearest `node_modules` folder and works even without using `watch` mode.
+(Thanks [mellyeliu](https://github.com/mellyeliu/))
+
+### Better interoperability
+
+The CLI now supports configuring additional Babel presets and plugins that can run before the StyleX
+plugin to let you use custom syntax transformations. The StyleX Babel plugin was also updated to make
+this use-case more reliable.
+
+### Windows support
+
+A bug with file paths was fixed and the CLI should now work correctly on Windows.
+
+## Documentation
+
+We have introduced a new [Recipes](/docs/learn/recipes/variants/) section in the documentation to showcase some useful patterns when
+using StyleX.
+
+## Miscellaneous
+
+- The StyleX Rollup plugin now supports generating filename hashes. (Thanks [nonzzz](https://github.com/nonzzz))
+- We now use the `@dual-bundle/import-meta-resolve` package to replace `esm-resolve` which should making theming APIs more reliable. 
+  (Thanks [p0nch000](https://github.com/p0nch000))
+- Removed unnecessary quotes around 'content' values in CSS files. (Thanks [nikeee](https://github.com/nikeee))
+- Added support for `view-transition-name` in ESLint's `valid-styles` rule.
+- Added support for `interpolate-size` in ESLint's `valid-styles` rule.
diff --git a/apps/docs/docs/api/configuration/babel-plugin.mdx b/apps/docs/docs/api/configuration/babel-plugin.mdx
@@ -145,6 +145,7 @@ unstable_moduleResolution: // Default: undefined
       // Use this value when using `ESModules`.
       type: 'commonJS',
       // The absolute path to the root directory of your project.
+      // Only used as a fallback
       rootDir?: string,
       // Override `.stylex.js` with your own extension.
       themeFileExtension?: string,

diff --git a/apps/docs/docs/learn/03-installation.mdx b/apps/docs/docs/learn/03-installation.mdx
@@ -22,54 +22,66 @@ All uses of StyleX require the runtime package to be installed.
 ## Compiler
 
 The recommended way to use StyleX in development and production is with the
-build-time compiler.
+build-time compiler. This can be done with any bundler that supports Babel,
+using the metadata generated by the StyleX plugin. See the API reference for more details on the
+`@stylexjs/babel-plugin` API.
 
-### Development
+To make this easier for commonly used packages and meta-frameworks, StyleX provides
+a PostCSS plugin. StyleX also provides (experimental) plugins for Webpack, Rollup, Next.js
+and esbuild.
 
-For development, you need only to configure the Babel plugin so that styles are
-processed at compile-time. The plugin will compile styles and insert runtime
-style injection code into your JavaScript modules.
+<details open>
+  <summary>PostCSS</summary>
 
-<DevInstallExample dev={[`@stylexjs/babel-plugin`]} />
+  PostCSS is the more versatile way to integrate StyleX into your project. Create a 
+  `postcss.config.js` file in your project root and add the StyleX plugin to it.
 
-```ts
-// babel.config.js
-import styleXPlugin from '@stylexjs/babel-plugin';
-
-const config = {
-  plugins: [
-    [
-      styleXPlugin,
-      {
-        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,
-        },
+  <DevInstallExample dev={[`@stylexjs/postcss-plugin`, `@stylexjs/babel-plugin`]} />
+
+  ```tsx title="postcss.config.js"
+  module.exports = {
+    plugins: {
+      '@stylexjs/postcss-plugin': {
+        include: [
+          './**/*.{js,jsx,ts,tsx}',
+          // any other files that should be included
+          // this should include NPM dependencies that use StyleX
+        ],
+        useCSSLayers: true,
       },
-    ],
-  ],
-};
+      autoprefixer: {},
+    },
+  };
+  ```
 
-export default config;
-```
+  You must also configure the `.babelrc` file for StyleX to work as expected.
+  Please see the [Babel plugin API reference](/docs/api/configuration/babel-plugin/) for more details.
 
-### Production
 
-Production use of StyleX should extract CSS to an external file. This can be
-done with any bundler that supports Babel, using the metadata generated by the
-StyleX plugin. See the API reference for more details on the
-`@stylexjs/babel-plugin` API.
-
-To make this easier for commonly used packages and meta-frameworks, StyleX
-provides (experimental) plugins for Webpack, Rollup, Next.js and esbuild.
+  ```tsx title=".babelrc.js"
+  module.exports = {
+    presets: [
+      ...
+    ],
+    plugins: [
+      ...,
+      [
+        "@stylexjs/babel-plugin",
+        {
+          dev: process.env.NODE_ENV === "development",
+          test: process.env.NODE_ENV === "test",
+          runtimeInjection: false,
+          genConditionalClasses: true,
+          treeshakeCompensation: true,
+          unstable_moduleResolution: {
+            type: "commonJS",
+          },
+        },
+      ],
+    ],
+  };
+  ```
+</details>
 
 <details>
   <summary>Rollup</summary>
@@ -163,56 +175,6 @@ provides (experimental) plugins for Webpack, Rollup, Next.js and esbuild.
 
 </details>
 
-<details>
-  <summary>Next.js</summary>
-
-  <DevInstallExample dev={[`@stylexjs/nextjs-plugin`, `@stylexjs/babel-plugin`, `rimraf`]} />
-
-  ```tsx title="package.json"
-  {
-    "scripts": {
-      ...,
-      "predev": "rimraf .next",
-      "prebuild": "rimraf .next"
-    }
-  }
-  ```
-
-  ```tsx title=".babelrc.js"
-  module.exports = {
-    presets: ["next/babel"],
-    plugins: [
-      [
-        "@stylexjs/babel-plugin",
-        {
-          dev: process.env.NODE_ENV === "development",
-          test: process.env.NODE_ENV === "test",
-          runtimeInjection: false,
-          genConditionalClasses: true,
-          treeshakeCompensation: true,
-          unstable_moduleResolution: {
-            type: "commonJS",
-            rootDir: __dirname,
-          },
-        },
-      ],
-    ],
-  };
-  ```
-
-  ```tsx title="next.config.mjs"
-  /** @type {import('next').NextConfig} */
-  import stylexPlugin from "@stylexjs/nextjs-plugin";
-
-  const nextConfig = {};
-
-  const __dirname = new URL(".", import.meta.url).pathname;
-  export default stylexPlugin({
-    rootDir: __dirname,
-  })(nextConfig);
-  ```
-</details>
-
 <details>
   <summary>esbuild</summary>
 
@@ -302,6 +264,9 @@ module.exports = {
   plugins: ["@stylexjs"],
   rules: {
     "@stylexjs/valid-styles": "error",
+    '@stylexjs/no-unused': "error",
+    '@stylexjs/valid-shorthands': "warning",
+    '@stylexjs/sort-keys': "warning"
   },
 };
 ```