Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

2.5 KB
Raw Blame

CssVarsDeclarationPlugin

Rspack plugin that generates .d.css declaration files from TypeScript source files. It's primarily oriented towards VSCode-based IDEs which in combination with CSS Variable Autocomplete extension provide autocomplete functionality for all CSS variables declared in .d.css files across the codebase.

Why

CSS variables defined in TypeScript (object keys, union types) are invisible to CSS tooling. This plugin extracts those definitions at build time and writes .d.css files that IDEs can pick up for autocomplete.

When it runs

  • Dev mode only — added conditionally in rspack.main.config.js
  • Once per build — hooks into compiler.hooks.environment (no re-runs on HMR)

Config API

Each entry in CSS_VAR_CONFIGS generates one .d.css file:

{
  // Source file whose .d.css sibling will be generated (file.ts → file.d.css)
  path: "metabase/path/to/file.ts",

  // Optional static variable names to include as-is
  staticVars: ["--mb-some-var"],

  // Optional extraction sources — where to read variable names from
  sources: [
    {
      // Source file to parse. Defaults to path if omitted.
      file: "metabase/path/to/other-file.ts",

      // Extraction method:
      //   "objectKeys" — extract --mb-* keys from object literal properties
      //   "unionType"  — extract string literals from a union type alias
      type: "objectKeys",

      // Variable or type alias names to extract from
      names: ["SOME_OBJECT", "ANOTHER_OBJECT"],

      // Optional prefix added to each extracted value
      varPrefix: "--mb-color-",
    },
  ],
}

Adding a new source

Add an entry to CSS_VAR_CONFIGS in the plugin file. Simplest case:

{
  path: "metabase/path/to/new-file.ts",
  sources: [{ type: "objectKeys", names: ["MY_CSS_VARS_MAP"] }],
}

Output format

Since most CSS variables we want to expose are declared dynamically, we can't properly derive their values at the build step. But having just the names is enough for IDEs to provide autocomplete. In future if we want to support extracting static values from the source files, autocomplete would be able to provide preview for actual values.

/* Auto-generated by CssVarsDeclarationPlugin. Do not edit. */
:root {
  --mb-color-brand: ;
  --mb-color-danger: ;
}

Warnings

The plugin prints warnings to the console when:

  • A source file listed in the config doesn't exist on disk
  • A variable or type alias name isn't found in the source file