From 1608c894bf26d7100962e4d3f28f8c45c1038b5b Mon Sep 17 00:00:00 2001 From: Naman Goel Date: Fri, 3 Jan 2025 02:06:11 +0300 Subject: [PATCH] docs: v0.10.0 releate notes (#830) * docs: v0.10.0 releate notes * missing PostCSS plugin documentation * chore: fix typos --- apps/docs/blog/2025-01-02-Release-v0.10.0.mdx | 89 ++++++++++ .../docs/api/configuration/babel-plugin.mdx | 1 + apps/docs/docs/learn/03-installation.mdx | 152 ++++++++---------- packages/babel-plugin/src/visitors/imports.js | 2 +- packages/dev-runtime/src/index.js | 2 +- 5 files changed, 155 insertions(+), 91 deletions(-) create mode 100644 apps/docs/blog/2025-01-02-Release-v0.10.0.mdx 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 new file mode 100644 index 000000000..b097d7895 --- /dev/null +++ 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 index 810b74a90..da064fba5 100644 --- 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 index d31a5c505..2b14aa6f9 100755 --- a/apps/docs/docs/learn/03-installation.mdx +++ b/apps/docs/docs/learn/03-installation.mdx @@ -22,54 +22,75 @@ 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. +
+ PostCSS - + 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, - }, + + + ```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. + ```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", + }, + }, + ], + ], + }; + ``` + + Finally, ensure that your app imports a global CSS file that includes the following declaration: + + ```css + @stylex; + ``` -To make this easier for commonly used packages and meta-frameworks, StyleX -provides (experimental) plugins for Webpack, Rollup, Next.js and esbuild. + The PostCSS plugin will replace the delaration with the generated StyleX styles. + Make sure that you only include this declaration once in your app. +
Rollup @@ -163,56 +184,6 @@ provides (experimental) plugins for Webpack, Rollup, Next.js and esbuild.
-
- Next.js - - - - ```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); - ``` -
-
esbuild @@ -302,6 +273,9 @@ module.exports = { plugins: ["@stylexjs"], rules: { "@stylexjs/valid-styles": "error", + '@stylexjs/no-unused': "error", + '@stylexjs/valid-shorthands': "warning", + '@stylexjs/sort-keys': "warning" }, }; ``` diff --git a/packages/babel-plugin/src/visitors/imports.js b/packages/babel-plugin/src/visitors/imports.js index cdab88b23..4213eeb7e 100644 --- a/packages/babel-plugin/src/visitors/imports.js +++ b/packages/babel-plugin/src/visitors/imports.js @@ -11,7 +11,7 @@ import * as t from '@babel/types'; import type { NodePath } from '@babel/traverse'; import StateManager from '../utils/state-manager'; -// Read imports of react and remember the name of the local varsiables for later +// Read imports of react and remember the name of the local variables for later export function readImportDeclarations( path: NodePath, state: StateManager, diff --git a/packages/dev-runtime/src/index.js b/packages/dev-runtime/src/index.js index 500baa33f..cbab5f51b 100644 --- a/packages/dev-runtime/src/index.js +++ b/packages/dev-runtime/src/index.js @@ -85,7 +85,7 @@ function themeNameUUID(): string { } // TODO: memoize the function to: -// return the same result if the some confirguration is passed in again +// return the same result if the some configuration is passed in again export default function inject({ insert = defaultInsert, ...config