Skip to main content

Waku

examples/example-waku integrates StyleX into a Waku app through the Vite layer using @stylexjs/unplugin. The plugin compiles StyleX modules, aggregates the generated CSS, and appends it to the emitted CSS assets so the browser only downloads one stylesheet.

Waku/Vite configuration​

// waku.config.ts
import react from '@vitejs/plugin-react';
import stylex from '@stylexjs/unplugin';
import { defineConfig } from 'waku/config';

export default defineConfig({
  vite: {
    plugins: [
      stylex.vite({
        useCSSLayers: true,
        devMode: 'css-only',
        devPersistToDisk: true,
        runtimeInjection: false,
      }),
      react({ babel: { plugins: ['babel-plugin-react-compiler'] } }),
    ],
  },
});
  • devMode: 'css-only' serves /virtual:stylex.css in dev without injecting the JS runtime.
  • devPersistToDisk lets multiple Waku environments share collected rules while developing.

CSS entrypoint​

Ensure that there is one CSS file that is imported from your root layout component or JS entry point.

Ensure that the virtual CSS file and script for hot reloading styles are part of your bundle to enable hot reloading during development.

The easiest way to do this is by using an encapsulated helper that can also be used to insert a link tag for your production CSS.

// src/DevStyleXInject.tsx
'use client';
import { useEffect } from 'react';

function DevStyleXInjectImpl() {
  useEffect(() => {
    if (import.meta.env.DEV) {
      import('virtual:stylex:runtime');
    }
  }, []);
  return <link rel="stylesheet" href="/virtual:stylex.css" />;
}

export function DevStyleXInject({ cssHref }: { cssHref: string }) {
  return import.meta.env.DEV ? (
    <DevStyleXInjectImpl />
  ) : (
    cssHref && <link rel="stylesheet" href={cssHref} />
  );
}

Render <DevStyleXInject cssHref="/stylex.css" /> in your HTML shell component.

// src/pages/_layout.tsx (excerpt)
import { DevStyleXInject } from '../components/DevStyleXInject';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <>
    <head>
      <DevStyleXInject cssHref="/stylex.css" />
    </head>
    <body>
    <div>
      {children}
    </div>
    </>
  );
}