@jdlanglois/css-props

Define CSS custom properties in TypeScript, inject them while developing, and compile the same configuration to static CSS for production.

Install

npm install @jdlanglois/css-props

Configure

// css-props.config.ts
import { defineProps, ref, scale } from "@jdlanglois/css-props";

export default defineProps({
  prefix: "app",
  tokens: {
    colors: {
      blue: { 500: "#2878ff" },
      action: ref("colors.blue.500"),
      surface: "#ffffff",
    },
    fonts: {
      sans: 'Inter, system-ui, sans-serif',
    },
    spacing: scale({ base: "0.25rem", steps: 8 }),
  },
  themes: {
    dark: {
      selector: '[data-theme="dark"]',
      tokens: {
        colors: { surface: "#111111" },
      },
    },
  },
});

Token object paths become kebab-case custom properties such as --app-colors-action and --app-spacing-2.

Runtime

import config from "./css-props.config";
import { mountProps } from "@jdlanglois/css-props/runtime";

const props = mountProps(config);
props.update(nextConfig); // useful for editors and hot reload
props.dispose();

mountProps reuses a single identified style element. Pass { id, nonce } to use multiple configurations or comply with a nonce-based CSP.

Production build

npx css-props build ./css-props.config.ts --out ./public/css-props.css

The CLI bundles and evaluates the TypeScript configuration, then writes the result of the same compile() function used by the runtime adapter.

The examples/open-props.config.ts example recreates the Open Props 1.7.23 spacing, color, font, shadow, border, and radius tokens while retaining their original custom-property names. Build it with:

npx css-props build ./examples/open-props.config.ts --out ./open-props.css

You can also use the compiler directly:

import { compile } from "@jdlanglois/css-props";

const { css, variables } = compile(config);