@hone-ui/sx

Build plugin that compiles the sx prop to static CSS, so no styling code runs in the browser.

<Box sx={{ p: 2, color: 'primary.main', '&:hover': { opacity: 0.8 } }} />

becomes a class backed by a generated stylesheet:

.hn-sx-k3J9aQ2x {
  padding: calc(2 * var(--hn-spacing));
  color: var(--hn-palette-primary-main);
}
.hn-sx-k3J9aQ2x:hover {
  opacity: 0.8;
}

Setup

Vite:

// vite.config.ts
import react from '@vitejs/plugin-react';
import sx from '@hone-ui/sx/vite';
import { defineConfig } from 'vite';

// List sx() before react(), and keep react() so Fast Refresh works.
export default defineConfig({
  plugins: [sx(), react()],
});

Delete the Vite template's src/index.css and App.css, or put them in an earlier layer. Their unlayered rules override the library.

Next.js, with Turbopack or webpack:

// next.config.ts
import { withSx } from '@hone-ui/sx/next';

// Pass your existing config object, such as create-next-app's, instead of {}.
// optimizePackageImports keeps `next build --webpack` from shipping every component.
export default withSx({
  experimental: { optimizePackageImports: ['@hone-ui/react'] },
});

Import app/globals.css before the look CSS in app/layout.tsx, and put its resets in @layer reset, hone-ui;. Unlayered CSS beats the library and sx.

Rollup, esbuild and webpack use @hone-ui/sx/rollup, @hone-ui/sx/esbuild and @hone-ui/sx/webpack the same way as Vite.

Options

| Option | Default | Purpose | | --------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | breakpoints | { values: { xs: 0, sm: 600, md: 900, lg: 1200, xl: 1536 } } | Breakpoint names and widths, in the shape createTheme takes (values, unit). Share one object with your theme. | | palette | {} | Your theme's palette object. Each object-valued key, such as neutral: { main }, is a palette key. Share one object with your theme. | | paletteKeys | [] | Extra palette keys, such as ['brand'], so 'brand.500' resolves to a theme variable. main, light, dark and contrastText work for any key without it. Merged with palette. | | spacing | none | Your theme's spacing array, such as [0, 4, 8, 16], so p: 3 compiles to 16px. | | importSources | ['@hone-ui/react'] | Packages whose components take sx. Components from local paths and the same file are always compiled. | | include | /\.[jt]sx$/ | Files to transform. | | cacheDir | 'node_modules/.cache/hone-ui-sx' | Where generated CSS files go. | | editor | true | In dev, stamps components with data-hn-source for the visual editor. Production ignores it. |

What compiles

Static values, theme values, breakpoint objects and arrays, nested selectors, @media, @container and @supports blocks all compile to CSS. Values that change at runtime, such as width: size, compile to a CSS variable that the component sets. Conditional entries, such as sx={[base, active && { color: 'red' }]}, compile to one class per combination, up to three conditions. Members of const style objects in the same file, such as sx={styles.root}, compile too.

The plugin compiles sx on components from @hone-ui/react, on components from your own files, and on wrappers of those such as memo(Box). Another library's component, even wrapped in styled(...) or memo(...), keeps its sx untouched.

A function of the theme, such as sx={(theme) => ({ zIndex: theme.zIndex.drawer + 1 })}, needs the theme at runtime. The plugin leaves it alone, without a warning, and the component calls it with the current theme. In an array, entries before the first function compile. The function and every entry after it stay inline, so later entries still override it. A function result becomes inline styles, so it can't hold selectors or media queries. The plugin can't tell Server Components apart, so it doesn't check where a function sits; write function sx in a file marked 'use client'.

The plugin warns with the file and line when it can't compile an sx prop: getters and methods, spreads it can't read, a runtime typography value, or more than three conditions. Those props fall back to inline styles, which can't hold selectors or media queries.

Matching your theme

Media queries and spacing arrays can't read CSS variables, so the plugin needs the theme values that live outside them. Pass the same values your createTheme call uses:

sx({
  breakpoints, // the object you pass to createTheme
  palette, // the palette you pass to createTheme; its object keys count as palette keys
  spacing: [0, 4, 8, 16, 32],
  paletteKeys: ['brand'],
});

A numeric spacing needs nothing: factors multiply --hn-spacing, which ThemeProvider sets. A function scale can't be passed to the plugin. Write it out as an array.