@underglass/css-compiler weekly downloads statistics

Underglass build-time CSS compiler

Experimental @underglass/css-compiler, the opt-in build-time route of Underglass. Explicitly selected animations compile to literal WebGPU compositor programs and matching numeric native-geometry samplers during the application build. Ordinary CSS, browser layout, React state and the original controls are retained. This is not a general CSS translator or a custom React renderer.

Live examples: underglass.dev · Source, guide and API: github.com/RaananW/underglass

npm install --save-dev @underglass/css-compiler   # beside @underglass/react, with Vite 8 or webpack 5

Configuration

Place underglass.config.json in the application root:

{
  "version": 1,
  "target": "webgpu",
  "unsupported": "error",
  "entries": [
    {
      "id": "card",
      "stylesheet": "@my-library/card/styles.scss",
      "selector": ".card",
      "animations": ["float"]
    }
  ]
}

Use a real exported package stylesheet or an explicit local path such as ./src/card.module.scss. The application's bundler resolves it; dependency files are never rewritten. A component must expose both usable styles and a public ref/enrollment boundary. Packages without those cannot be automatically adapted. schema.json provides an editor schema; unknown JSON fields (including $schema) are currently refused. Configuration accepts 1..32 targets. The output holds one per-layer compositor program that the runtime draws once per layer, so it does not limit the layer count; maxLayers is still accepted for compatibility and has no effect.

Vite

import { defineConfig } from "vite";
import { underglass } from "@underglass/css-compiler/vite";

export default defineConfig({
  plugins: [underglass({ configFile: "underglass.config.json" })],
});

The adapter uses Vite's preprocessing, configured PostCSS plugins and CSS Modules mapping, then substitutes generated code before final chunk emission. Chunk source maps are preserved. This is a production-build integration; vite dev, HMR and watch compilation are deliberately refused when the virtual module is requested.

webpack

import { UnderglassPlugin } from "@underglass/css-compiler/webpack";

export default {
  plugins: [new UnderglassPlugin({ configFile: "underglass.config.json" })],
  module: {
    rules: [{
      test: /\.scss$/,
      use: [
        { loader: "css-loader", options: {
          sourceMap: true, modules: { namedExport: false },
        } },
        { loader: "postcss-loader", options: { sourceMap: true } },
        { loader: "sass-loader", options: { sourceMap: true } },
      ],
    }],
  },
};

The adapter uses webpack's public resolver and importModule to run the real loader chain at build time. It currently requires one processed css-loader array part per stylesheet. Aggregated CSS imports, style-loader, MiniCssExtractPlugin and other injection/extraction outputs are not supported. The application must deliver the returned ordinary CSS itself:

import styles from "@my-library/card/styles.scss";
const sheet = document.createElement("style");
sheet.textContent = styles.toString();
document.head.append(sheet);
const cardClass = styles.locals.card;

This native stylesheet is essential for fallback. The integration does not invent a second CSS delivery pipeline. Sass @use partials and configured PostCSS transforms are exercised in the installed-package fixture; other preprocessors/loader chains require separate qualification.

Runtime enrollment

/// <reference types="@underglass/css-compiler/client" />
import compiled from "virtual:underglass/compiled";
import { mountCanvasApp, useSurfaceRef } from "@underglass/react";

function App() {
  const ref = useSurfaceRef({ id: "card" });
  return <Card ref={ref} className={cardClass} />;
}

const controller = mountCanvasApp({
  ordinaryHost, captureHost, outputCanvas,
  compiled, budgets: { layers: 2, pixels: 1_000_000 },
  onStatus: message => { diagnostics.textContent = message; },
}, <App />);
const motion = controller.ownCompiledAnimation("card", "card/float");
await controller.enable();

The three hosts must satisfy the existing stable sibling/root mount contract. Enrollment must reference the original direct root child, not a cloned control or a ref hidden inside a third-party component. Set transform-origin: 0 0; avoid competing inline transforms/opacity, individual transform properties or other animation owners.

Ownership checks the actual browser animation against the compiled descriptor before changing it. Only the enrolled animation is suppressed. Generated WGSL samples motion/opacity; a generated JS sampler synchronizes native affine hit geometry. Playback supports play, pause, seek and release. Disable, failure or disposal restores ordinary CSS behavior and the current time/play state without replacing React's original controls. The browser may recreate the CSSAnimation object; Animation-object identity is not guaranteed. Later authored declarations that differ from Underglass's owned values are preserved on restoration. Reassigning an identical value/priority is not distinguishable from the ownership lease's existing write.

Supported subset and boundaries

One unconditional top-level .class or #id rule, one named CSS keyframe animation, 2..32 increasing offsets spanning 0..1, and complete transform and opacity in every frame. Transforms use none or translate(px[, px]) rotate(deg) scale(number[, number]), with positive bounded scales. Timing supports positive duration, nonnegative delay, integer/infinite iterations, normal/alternate direction and both fill. Easing supports linear, named CSS easing and non-overshooting cubic-bezier control points in [0,1].…