Build plugins for Astryx source builds. In the webpack and Vite setups, its babel, PostCSS, and Vite integrations compile Astryx library and product code with separate class name prefixes, which enables independent CSS layers:
reset < astryx-base (library, astryx prefix) < astryx-theme < product (app, x prefix)
Under Turbopack, withAstryx() and @astryxdesign/build/next/postcss compile Astryx the way its prebuilt stylesheets are compiled: the same class names, in @layer astryx-base.
StyleX generates atomic CSS: same declaration = same class name. Without separate prefixes, library and product classes collide and can't be placed in independent CSS layers, which breaks theme overrides.
In the webpack and Vite setups, @astryxdesign/build solves this by:
- Compiling Astryx library code with
astryxprefix (.astryx78zum5) - Compiling product code with default
xprefix (.x78zum5) - Placing each group in its own CSS
@layer - Rejecting unsupported StyleX declarations instead of silently omitting them
| Export | Purpose | Platform |
|---|---|---|
@astryxdesign/build/babel |
Babel plugin: splits class prefixes per file | Next.js, any babel pipeline |
@astryxdesign/build/postcss |
PostCSS plugin: compiles + splits CSS layers | Next.js (webpack) |
@astryxdesign/build/next |
withAstryx(): the Next.js config helper |
Next.js (webpack, Turbopack) |
@astryxdesign/build/next/postcss |
PostCSS plugin: @astryx; |
Next.js (Turbopack) |
@astryxdesign/build/vite |
Vite plugin: wraps unplugin + splits layers | Vite, Storybook |
npm install -D @astryxdesign/build @stylexjs/babel-plugin @babel/coreFor Vite, also install:
npm install -D @stylexjs/unpluginUnder Turbopack, the default bundler since Next.js 16, withAstryx() compiles the
Astryx modules your app imports from source as the prebuilt stylesheets are compiled,
and @astryxdesign/build/next/postcss emits each source-built package's prebuilt
stylesheet from that source: the same rules and selectors, in the same order, inside
@layer astryx-base. Installed and workspace-linked packages both work; Astryx needs
no Babel config.
-
next.config.mjs, around your config and its ownturbopack.rules:import {withAstryx} from '@astryxdesign/build/next'; export default withAstryx({/* your Next.js config */});
-
postcss.config.js, beside any plugin your app already uses:module.exports = {plugins: {'@astryxdesign/build/next/postcss': {}}};
-
Your global stylesheet, with
@astryx;in place ofastryx.css,lab.css,charts.cssandrichtext.css(every installed package with a prebuilt stylesheet builds from source, so import none of them: the build fails on one):@import '@astryxdesign/core/reset.css'; @import '@astryxdesign/theme-neutral/theme.css'; @astryx;
Each package's rules start with the
reset, astryx-base, astryx-themelayer order, asreset.cssand the theme do, so the order holds in any chunk order without a line of your own.
Your own Turbopack rules are kept off Astryx source. Your Babel config file is not,
and Babel's ignore cannot exclude Astryx: to keep it off, set
experimental.turbopackUseBuiltinBabel: false and run babel-loader from a
turbopack.rules entry, which withAstryx() keeps off Astryx source like any rule.
These steps run under next dev --webpack and next build --webpack.
const path = require('path');
module.exports = {
presets: ['next/babel'],
plugins: [
[
'@astryxdesign/build/babel',
{
dev: process.env.NODE_ENV !== 'production',
runtimeInjection: false,
propertyValidationMode: 'throw',
treeshakeCompensation: true,
enableInlinedConditionalMerge: true,
aliases: {
'@astryxdesign/core/*': [
path.join(__dirname, 'node_modules/@astryxdesign/core/*'),
],
'@astryxdesign/core': [
path.join(__dirname, 'node_modules/@astryxdesign/core'),
],
},
unstable_moduleResolution: {type: 'commonJS'},
},
],
],
};A custom Babel config turns off Next.js's SWC compiler, and next/font needs SWC. Remove next/font from your layout (a fresh create-next-app layout imports next/font/google), or the build fails with "next/font" requires SWC although Babel is being used.
const path = require('path');
module.exports = {
plugins: {
'@astryxdesign/build/postcss': {
appDir: 'src',
babelPlugins: [
[
'@stylexjs/babel-plugin',
{
dev: process.env.NODE_ENV !== 'production',
runtimeInjection: false,
treeshakeCompensation: true,
enableInlinedConditionalMerge: true,
aliases: {
'@astryxdesign/core/*': [
path.join(__dirname, 'node_modules/@astryxdesign/core/*'),
],
'@astryxdesign/core': [
path.join(__dirname, 'node_modules/@astryxdesign/core'),
],
},
unstable_moduleResolution: {type: 'commonJS'},
},
],
],
},
},
};Or withAstryx() from @astryxdesign/build/next, which sets both of these for you. Use withAstryx() when the app has a swizzled copy with an astryx-swizzle.json marker: this manual config does not rebuild the copy when its marker appears or goes.
Either way the work happens in the webpack hook, so the build has to run with
--webpack — see the note at the top of this section.
const nextConfig = {
transpilePackages: ['@astryxdesign/core', '@astryxdesign/theme-neutral'],
webpack: config => {
// Resolve to source TypeScript instead of dist
config.resolve.conditionNames = ['source', 'import', 'require', 'default'];
return config;
},
};
export default nextConfig;src/app/layers.css:
@layer reset, astryx-base, astryx-theme, product;src/app/globals.css:
@import './layers.css';
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/theme-neutral/theme.css';
@stylex;
layers.cssmust be a separate file because webpack hoists@importcontent above inline CSS.
{
"browserslist": ["last 1 Chrome version"]
}import {astryxStylex} from '@astryxdesign/build/vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [
...astryxStylex({
stylexOptions: {
dev: process.env.NODE_ENV === 'development',
runtimeInjection: false,
propertyValidationMode: 'throw',
treeshakeCompensation: true,
unstable_moduleResolution: {
type: 'commonJS',
rootDir: __dirname,
},
},
}),
react(),
],
resolve: {
alias: {
'@astryxdesign/core': path.resolve(
__dirname,
'node_modules/@astryxdesign/core/src',
),
},
},
optimizeDeps: {
exclude: ['@astryxdesign/core', '@astryxdesign/theme-neutral'],
},
});Wraps @stylexjs/babel-plugin with two internal instances: one with classNamePrefix: 'astryx' for library files, one with default 'x' for product files. Routes each file to the correct instance based on its path.
Library patterns (configurable):
packages/core/packages/themes/node_modules/@astryxdesign/
A swizzled copy is library code too. The Babel, PostCSS, and Vite integrations compile every module under a folder that holds an astryx-swizzle.json marker with the library prefix into @layer astryx-base, so a theme's component overrides reach the copy as they reach the package component. astryx swizzle writes the marker into an output folder it owns (one the copy creates, an empty one, or one it marked before), naming each package the folder's copies came from and its version, such as {"packages": {"@astryxdesign/core": "0.7.10"}}. To mark a folder that holds only swizzled copies by hand, add that file to it; the build reads only whether the file is there. Keep the product's own components out of a marked folder. Under webpack, use withAstryx() with a marked copy: it makes each app module depend on the marker paths above it, so a dev session or a cached build recompiles a copy when its marker appears or disappears. In another setup that caches transforms, restart the dev server and delete that cache after adding or removing a marker. Turbopack builds do not read the marker yet.
Compiles StyleX from both library and product source files in two separate passes with different prefixes. Wraps the results in named @layer blocks:
- Library rules →
@layer astryx-base - Product rules →
@layer product
Wraps @stylexjs/unplugin and intercepts the dev CSS endpoint (/virtual:stylex.css). Partitions the collected rules by file path and serves split-layer CSS. Production builds write those rules to one cache-safe shared stylesheet and link it from every emitted HTML entry, without cross-loading entry-owned CSS.
Unsupported declarations fail the build by default with StyleX's replacement guidance. Set propertyValidationMode explicitly in stylexOverrides (modern API) or stylexOptions (legacy API) only when a migration needs the upstream warn or silent behavior.
A production build also checks the StyleX stylesheet for generated custom properties (--<prefix><hash>) that it reads but no stylesheet in the build declares, which browsers drop: a .stylex.ts export read in a style that is not a defineVars/defineConsts value, or one whose module never reached the build. It warns, naming the variable and the rule that reads it. Only stylesheets count as declarations, so a property the app sets at runtime (an inline style) is reported too: give it a name outside the StyleX class-name prefixes.
[
'@astryxdesign/build/babel',
{
// Patterns to identify library files (default shown)
libraryPatterns: [
'packages/core/',
'packages/themes/',
'node_modules/@astryxdesign/',
],
// Class name prefix for library styles (default: 'astryx')
libraryPrefix: 'astryx',
// Class name prefix for product styles (default: 'x')
classNamePrefix: 'x',
// ... all @stylexjs/babel-plugin options
},
];'@astryxdesign/build/postcss': {
appDir: 'src', // Your app source directory
babelPlugins: [...], // StyleX babel plugin config
libraryPrefix: 'astryx', // Prefix for library CSS (default: 'astryx')
extraInclude: [...], // Additional glob patterns
layers: { // Layer names (defaults shown)
library: 'astryx-base',
product: 'product',
},
}- example-nextjs-source: full Next.js source build example
@stylexjs/babel-plugin: the underlying StyleX compiler