@stylexswc/nextjs-plugin 0.17.0 → 0.17.1-rc.1

package/README.md

@@ -1,55 +1,47 @@
-# Next.js plugin with NAPI-RS StyleX compiler integration
-
-> Part of the [StyleX SWC Plugin](https://github.com/Dwlad90/stylex-swc-plugin#readme) workspace
-
-Next.js plugin for an unofficial
-[`napi-rs`](https://github.com/dwlad90/stylex-swc-plugin/tree/develop/crates/stylex-rs-compiler)
-compiler that includes the StyleX SWC code transformation under the hood.
-
-## Overview
-
-This package combines two solutions to enhance your Next.js development
-experience with StyleX:
-
-### StyleX SWC Plugin
-
-- Integrates StyleX with the SWC compiler, potentially leading to faster build
-  times compared to using Babel.
-- Maintains high compatibility with official StyleX tests, ensuring a reliable
-  experience.
-- Integrates seamlessly with Next.js SWC Compiler for a streamlined workflow.
-
-### StyleX NAPI-RS Compiler
-
-- Utilizes NAPI-RS to compile StyleX code, offering advantages over the SWC
-  plugin approach.
-- Provides access to StyleX metadata and source maps, enabling advanced plugin
-  and tool development.
-
-## Why choose this approach?
-
-- Leverage SWC's speed: Benefit from Next.js's default SWC compiler for
-  potentially faster build times.
-- Maintain StyleX familiarity: The usage of StyleX remains unchanged for
-  developers.
+# @stylexswc/nextjs-plugin
+
+> StyleX plugin for Next.js, powered by a Rust compiler (NAPI-RS + SWC).
+> Supports Webpack, Rspack, and Turbopack builds. Part of the
+> [StyleX SWC Plugin](https://github.com/Dwlad90/stylex-swc-plugin#readme)
+> workspace.
+
+This plugin integrates [StyleX](https://stylexjs.com) into Next.js using
+[`@stylexswc/rs-compiler`](https://www.npmjs.com/package/@stylexswc/rs-compiler),
+a Rust implementation of the StyleX transform, instead of the official Babel
+plugin. That means you keep Next.js's fast SWC toolchain — no `.babelrc`, no
+Babel fallback — and your StyleX code stays exactly the same. Per-file
+transforms are 2x to 5x faster than with Babel — see
+[performance](https://github.com/Dwlad90/stylex-swc-plugin#performance).
+
+This is a community project and is not affiliated with Meta. It tracks the
+official StyleX releases
+<!-- stylex-compatibility:start -->(currently compatible with StyleX v0.19.0)<!-- stylex-compatibility:end -->,
+requires Node.js 20 or newer, and supports Next.js 15+ (App Router and Pages
+Router).
 
 ## Installation
 
-To install the package, run the following command:
-
 ```bash
 npm install --save-dev @stylexswc/nextjs-plugin
 ```
 
+Your application still needs the StyleX runtime:
+
+```bash
+npm install @stylexjs/stylex
+```
+
 ## Usage
 
-This plugin supports Webpack, Rspack, and Turbopack configurations in Next.js.
+The plugin supports all three Next.js bundlers. Pick the export that matches
+your setup.
 
 ### Using with Webpack
 
 For standard Next.js Webpack builds, use the default import:
 
-```javascript
+```js
+// next.config.js
 const stylexPlugin = require('@stylexswc/nextjs-plugin');
 
 module.exports = stylexPlugin({
@@ -61,11 +53,12 @@ module.exports = stylexPlugin({
 
 ### Using with Rspack
 
-For Next.js with [Rspack](https://rspack.rs), use the `/rspack` export. It applies the
-experimental [`next-rspack`](https://www.npmjs.com/package/next-rspack) adapter for you —
-no manual `withRspack` composition needed:
+For Next.js with [Rspack](https://rspack.rs), use the `/rspack` export. It
+applies the experimental
+[`next-rspack`](https://www.npmjs.com/package/next-rspack) adapter for you — no
+manual `withRspack` composition needed:
 
-```typescript
+```ts
 import stylexPlugin from '@stylexswc/nextjs-plugin/rspack';
 
 module.exports = stylexPlugin({
@@ -76,27 +69,33 @@ module.exports = stylexPlugin({
 ```
 
 > [!NOTE]
-> Run `next dev` and `next build` without the `--webpack`/`--turbopack` flags. For
-> `next start`, set `NEXT_RSPACK=true` in the environment (the production server only
-> serves prebuilt output, but it still evaluates the config).
-
-The Rspack integration extracts StyleX CSS from both Server and Client Components, with
-the same options as the Webpack plugin, plus `stylexPackages` from
+> Run `next dev` and `next build` without the `--webpack`/`--turbopack`
+> flags. For `next start`, set `NEXT_RSPACK=true` in the environment (the
+> production server only serves prebuilt output, but it still evaluates the
+> config).
+
+The Rspack integration extracts StyleX CSS from both Server and Client
+Components, with the same options as the Webpack plugin, plus `stylexPackages`
+from
 [`@stylexswc/rspack-plugin`](https://github.com/Dwlad90/stylex-swc-plugin/tree/develop/packages/rspack-plugin).
 
 > [!NOTE]
-> Packages listed in `transpilePackages` are automatically added to the `stylexPackages`
-> allowlist, so StyleX source shipped in `node_modules` (e.g. `@stylexjs/open-props`) is
-> picked up without extra configuration.
+> Packages listed in `transpilePackages` are automatically added to the
+> `stylexPackages` allowlist, so StyleX source shipped in `node_modules` (e.g.
+> `@stylexjs/open-props`) is picked up without extra configuration.
 
 ### Using with Turbopack
 
 > [!IMPORTANT]
-> **Turbopack Limitation**: Turbopack does not support webpack plugins ([see Next.js docs](https://nextjs.org/docs/app/api-reference/turbopack#webpack-plugins)). When using Turbopack, the loader only compiles StyleX code but **does not extract CSS**.
+> Turbopack does not support webpack plugins
+> ([see Next.js docs](https://nextjs.org/docs/app/api-reference/turbopack#webpack-plugins)).
+> When using Turbopack, the loader only compiles StyleX code but does not
+> extract CSS.
 >
-> **You must configure the PostCSS plugin for CSS extraction.** Install `@stylexswc/postcss-plugin` and configure it in `postcss.config.js`:
+> You must configure the PostCSS plugin for CSS extraction. Install
+> `@stylexswc/postcss-plugin` and configure it in `postcss.config.js`:
 >
-> ```javascript
+> ```js
 > // postcss.config.js
 > module.exports = {
 >   plugins: {
@@ -112,26 +111,22 @@ the same options as the Webpack plugin, plus `stylexPackages` from
 
 For Next.js with Turbopack, use the `/turbopack` export:
 
-```typescript
+```ts
 import withStylexTurbopack from '@stylexswc/nextjs-plugin/turbopack';
 
 export default withStylexTurbopack({
-  // StyleX options here same as postcss-plugin
+  // StyleX options here, same as postcss-plugin
   rsOptions: {
-      dev: process.env.NODE_ENV === 'development',
+    dev: process.env.NODE_ENV === 'development',
   },
 })({
   // Next.js config here
-  experimental: {
-    turbopack: {
-      // Additional Turbopack configuration if needed
-    },
-  },
 });
 ```
 
 > [!NOTE]
-> When using Turbopack, the following options are not supported and will be ignored:
+> When using Turbopack, the following options are not supported and will
+> be ignored:
 >
 > - `useCSSLayers`
 > - `nextjsMode`
@@ -146,20 +141,20 @@ export default withStylexTurbopack({
 
 - Type: `Partial<StyleXOptions>`
 - Optional
-- Description: StyleX compiler options that will be passed to the NAPI-RS
-  compiler. For standard StyleX options, see the
+- Description: StyleX compiler options passed to `@stylexswc/rs-compiler`. For
+  the standard options, see the
   [official StyleX documentation](https://stylexjs.com/docs/api/configuration/babel-plugin/).
 
 > [!NOTE]
-> **New Features:** The `include` and `exclude` options are exclusive to this NAPI-RS compiler implementation and are not available in the official StyleX Babel plugin.
+> The `include` and `exclude` options are exclusive to the Rust compiler
+> and are not available in the official StyleX Babel plugin.
 
 ##### `rsOptions.include`
 
 - Type: `(string | RegExp)[]`
 - Optional
-- Description: **RS-compiler Only** An array of glob patterns or regular
-  expressions to include specific files for StyleX transformation. When
-  specified, only files matching at least one of these patterns will be
+- Description: Glob patterns or regular expressions selecting the files to
+  transform. When specified, only files matching at least one pattern are
   transformed. Patterns are matched against paths relative to the current
   working directory.
 
@@ -167,31 +162,32 @@ export default withStylexTurbopack({
 
 - Type: `(string | RegExp)[]`
 - Optional
-- Description: **RS-compiler Only** An array of glob patterns or regular
-  expressions to exclude specific files from StyleX transformation. Files
-  matching any of these patterns will not be transformed, even if they match an
-  `include` pattern. Patterns are matched against paths relative to the current
-  working directory.
+- Description: Glob patterns or regular expressions excluding files from the
+  transform. A file matching any exclude pattern is skipped even if it matches
+  an `include` pattern. Patterns are matched against paths relative to the
+  current working directory.
 
 #### `stylexImports`
 
 - Type: `Array<string | { as: string, from: string }>`
 - Default: `['stylex', '@stylexjs/stylex']`
-- Description: Specifies where StyleX will be imported from. Supports both
-  string paths and import aliases.
+- Description: Specifies where StyleX is imported from. Supports both string
+  paths and import aliases.
 
 #### `useCSSLayers`
 
 - Type: `UseLayersType`
 - Default: `false`
-- Description: Enables CSS cascade layers support for better style isolation.
+- Description: Wraps the generated CSS in cascade layers for better style
+  isolation.
 
 #### `extractCSS`
 
 - Type: `boolean`
 - Optional
 - Default: `true`
-- Description: Controls whether CSS should be extracted into a separate file
+- Description: Controls whether the generated CSS is extracted into a separate
+  file. Set to `false` when `@stylexswc/postcss-plugin` owns extraction.
 
 ### Advanced Options
 
@@ -200,20 +196,19 @@ export default withStylexTurbopack({
 - Type:
   `(css: string, filePath: string | undefined) => string | Buffer | Promise<string | Buffer>`
 - Optional
-- Description: Custom CSS transformation function. Since the plugin injects CSS
-  after all loaders, use this to apply PostCSS or other CSS transformations.
+- Description: Custom CSS post-processing. The plugin injects CSS after all
+  loaders have run, so use this to apply PostCSS or other CSS transformations.
 
 ### Example Configuration
 
 #### Webpack Configuration
 
-```javascript
+```js
 const path = require('path');
 const stylexPlugin = require('@stylexswc/nextjs-plugin');
 const rootDir = __dirname;
 
 module.exports = stylexPlugin({
-  // Add any StyleX options here
   rsOptions: {
     dev: process.env.NODE_ENV !== 'production',
     // Include only specific directories
@@ -252,14 +247,13 @@ module.exports = stylexPlugin({
 
 #### Turbopack Configuration
 
-```typescript
+```ts
 import path from 'path';
 import withStylexTurbopack from '@stylexswc/nextjs-plugin/turbopack';
 
 const rootDir = __dirname;
 
 export default withStylexTurbopack({
-  // Add any StyleX options here
   rsOptions: {
     dev: process.env.NODE_ENV !== 'production',
     aliases: {
@@ -272,28 +266,20 @@ export default withStylexTurbopack({
   stylexImports: ['@stylexjs/stylex'],
 })({
   transpilePackages: ['@stylexjs/open-props'],
-  experimental: {
-    turbopack: {
-      // Additional Turbopack configuration if needed
-    },
-  },
   // Optionally, add any other Next.js config below
 });
 ```
 
-##### Required: PostCSS Configuration for CSS Extraction
+Required PostCSS configuration for CSS extraction under Turbopack:
 
-```javascript
+```js
 // postcss.config.js
 const path = require('path');
 
 module.exports = {
   plugins: {
     '@stylexswc/postcss-plugin': {
-      include: [
-        'app/**/*.{js,jsx,ts,tsx}',
-        'components/**/*.{js,jsx,ts,tsx}',
-      ],
+      include: ['app/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}'],
       rsOptions: {
         aliases: {
           '@/*': [path.join(__dirname, '*')],
@@ -311,9 +297,9 @@ module.exports = {
 
 ### Path Filtering Examples
 
-**Include only specific directories:**
+Include only specific directories:
 
-```javascript
+```js
 stylexPlugin({
   rsOptions: {
     include: ['app/**/*.tsx', 'components/**/*.tsx'],
@@ -321,19 +307,19 @@ stylexPlugin({
 });
 ```
 
-**Exclude test and build files:**
+Exclude test files and API routes:
 
-```javascript
+```js
 stylexPlugin({
   rsOptions: {
-    exclude: ['**/*.test.*', '**/*.spec.*', '**/dist/**', '**/node_modules/**'],
+    exclude: ['**/*.test.*', '**/*.stories.*', '**/__tests__/**', 'app/api/**'],
   },
 });
 ```
 
-**Using regular expressions:**
+Using regular expressions (exclude always takes precedence over include):
 
-```javascript
+```js
 stylexPlugin({
   rsOptions: {
     include: [/app\/.*\.tsx$/, /components\/.*\.tsx$/],
@@ -342,31 +328,19 @@ stylexPlugin({
 });
 ```
 
-**Combined include and exclude (exclude takes precedence):**
-
-```javascript
-stylexPlugin({
-  rsOptions: {
-    include: ['app/**/*.{ts,tsx}', 'components/**/*.{ts,tsx}'],
-    exclude: ['**/__tests__/**', '**/__mocks__/**', 'app/api/**'],
-  },
-});
-```
-
-**Exclude node_modules except specific packages:**
+Exclude `node_modules` except specific packages (negative lookahead):
 
-```javascript
+```js
 stylexPlugin({
   rsOptions: {
-    // Exclude all node_modules except @stylexjs/open-props
     exclude: [/node_modules(?!\/@stylexjs\/open-props)/],
   },
 });
 ```
 
-**Transform only specific packages from node_modules:**
+Transform only specific packages from `node_modules`:
 
-```javascript
+```js
 stylexPlugin({
   rsOptions: {
     include: [
@@ -380,6 +354,35 @@ stylexPlugin({
 });
 ```
 
+## FAQ
+
+### Which bundler mode should I pick?
+
+Webpack (the default export) is the most battle-tested path and supports every
+option. Turbopack gives the fastest dev server but needs the PostCSS plugin for
+CSS extraction. Rspack is experimental in Next.js itself but works end to end
+through the `/rspack` export.
+
+### Do I still need `@stylexjs/babel-plugin` or a `.babelrc`?
+
+No — that is the point of this plugin. StyleX is compiled by the Rust compiler
+inside the SWC pipeline, so Next.js never falls back to Babel.
+
+### My styles from `@stylexjs/open-props` (or another library) are missing
+
+Add the package to `transpilePackages` in your Next.js config. It is then
+transpiled by Next.js and automatically allowlisted for the StyleX transform.
+
+### Does this work with React Server Components?
+
+Yes. Styles are extracted at build time from both Server and Client Components
+into static CSS, so there is no runtime cost either way.
+
+### Is this an official StyleX package?
+
+No. It is a community-maintained alternative to the official tooling and is not
+affiliated with or supported by Meta.
+
 ## Examples
 
 - [Example repo](https://github.com/Dwlad90/nextjs-app-dir-stylex)
@@ -387,8 +390,8 @@ stylexPlugin({
 
 ## Documentation
 
-- [StyleX Documentation](https://stylexjs.com)
-- [NAPI-RS compiler for StyleX](https://github.com/Dwlad90/stylex-swc-plugin/tree/develop/crates/stylex-rs-compiler)
+- [StyleX documentation](https://stylexjs.com)
+- [`@stylexswc/rs-compiler` compiler options](https://github.com/Dwlad90/stylex-swc-plugin/tree/develop/crates/stylex-rs-compiler)
 
 ## Acknowledgments
 
@@ -397,4 +400,5 @@ This plugin was inspired by
 
 ## License
 
-MIT — see [LICENSE](https://github.com/Dwlad90/stylex-swc-plugin/blob/develop/LICENSE)
+MIT — see
+[LICENSE](https://github.com/Dwlad90/stylex-swc-plugin/blob/develop/LICENSE)

package/package.json

@@ -1,29 +1,10 @@
 {
   "name": "@stylexswc/nextjs-plugin",
-  "description": "StyleX NextJS plugin with NAPI-RS compiler",
-  "version": "0.17.0",
-  "config": {
-    "scripty": {
-      "path": "../../scripts/packages"
-    }
-  },
-  "dependencies": {
-    "@stylexswc/rs-compiler": "0.17.0",
-    "@stylexswc/rspack-plugin": "0.17.0",
-    "@stylexswc/turbopack-plugin": "0.17.0",
-    "@stylexswc/webpack-plugin": "0.17.0",
-    "next-rspack": "^16.2.9"
-  },
-  "devDependencies": {
-    "@stylexswc/eslint-config": "0.17.0",
-    "@stylexswc/typescript-config": "0.17.0",
-    "@types/node": "^26.1.0",
-    "next": "^16.2.9",
-    "postcss": "^8.5.16",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "webpack": "^5.108.3"
-  },
+  "description": "StyleX plugin for Next.js powered by a Rust NAPI-RS/SWC compiler. Supports Webpack, Rspack, and Turbopack builds with CSS extraction.",
+  "version": "0.17.1-rc.1",
+  "private": false,
+  "license": "MIT",
+  "sideEffects": false,
   "exports": {
     "./turbopack": {
       "types": "./dist/turbopack.d.ts",
@@ -45,31 +26,64 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "config": {
+    "scripty": {
+      "path": "../../scripts/packages"
+    }
+  },
+  "dependencies": {
+    "@stylexswc/rs-compiler": "0.17.1-rc.1",
+    "@stylexswc/rspack-plugin": "0.17.1-rc.1",
+    "@stylexswc/turbopack-plugin": "0.17.1-rc.1",
+    "@stylexswc/webpack-plugin": "0.17.1-rc.1",
+    "next-rspack": "^16.2.9"
+  },
+  "devDependencies": {
+    "@stylexswc/eslint-config": "0.17.1-rc.1",
+    "@stylexswc/typescript-config": "0.17.1-rc.1",
+    "@types/node": "^26.1.0",
+    "next": "^16.2.9",
+    "postcss": "^8.5.16",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "webpack": "^5.108.3"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "next-rspack": "^16.2.9"
+  },
+  "bugs": "https://github.com/Dwlad90/stylex-swc-plugin/issues",
+  "homepage": "https://github.com/Dwlad90/stylex-swc-plugin/tree/develop/packages/nextjs-plugin#readme",
   "keywords": [
+    "app-router",
+    "atomic-css",
+    "css-in-js",
+    "napi-rs",
     "next",
     "nextjs",
     "nextjs-plugin",
+    "react",
+    "rspack",
+    "rust",
     "stylex",
-    "swc"
+    "swc",
+    "turbopack"
   ],
-  "license": "MIT",
   "main": "dist/index.js",
-  "peerDependencies": {
-    "next": ">=15.0.0",
-    "next-rspack": "^16.2.9"
-  },
   "peerDependenciesMeta": {
     "next-rspack": {
       "optional": true
     }
   },
-  "private": false,
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dwlad90/stylex-swc-plugin.git",
+    "directory": "packages/nextjs-plugin"
   },
-  "repository": "https://github.com/Dwlad90/stylex-swc-plugin",
-  "sideEffects": false,
   "scripts": {
     "build": "scripty --ts",
     "check:artifacts": "scripty",