postcss-simple-vars

postcss-simple-vars is a PostCSS plugin that adds Sass-style $variable declarations to plain CSS. Variables can be used inside declaration values, selectors, at-rule parameters, and even comments, and they resolve at build time through PostCSS’s transform pipeline rather than requiring a separate preprocessor step.

Beyond simple substitution, it supports a $(name) interpolation syntax for embedding variables inside words (like margin-$(dir)), configurable handling of undefined variables (throw, warn, or silently pass through), and a callable variables option so tools like webpack can push updated values in during hot reload. It also plays well with other PostCSS plugins such as postcss-mixins, postcss-for, and postcss-each, since variable definitions and lookups happen through the same node-scoped resolution regardless of which plugin authored the surrounding at-rule.

What You Get

• A single dependency-light PostCSS plugin for Sass-style $variable substitution
• Variable support across declaration values, property names, selectors, at-rule parameters, and comments
• Configurable handling of undefined variables — throw an error, warn, stay silent, or restrict to an allow-list via only
• Bundled TypeScript type definitions (index.d.ts) for editor autocomplete

Common Use Cases

• Centralizing design tokens (colors, spacing, breakpoints) in one JS config and injecting them into CSS
• Porting a legacy Sass $variable codebase to a PostCSS-only build without rewriting syntax
• Building reusable, parameterized CSS patterns alongside postcss-for, postcss-each, and postcss-mixins
• Live-reloading theme variables during development via a callable variables function

Under The Hood

Architecture The plugin is a single-file (index.js, ~200 lines) factory function returning a PostCSS 8 plugin object with a prepare() lifecycle hook that closes over a variables map built from the caller’s options. It registers visitor handlers (AtRule, Comment, Declaration, OnceExit, Rule) following PostCSS’s helpers-based plugin API exactly. A repeat() helper re-runs regex substitution until no $ remains, which handles nested expansion (e.g. calc(4 * $column)), and an IGNORE symbol tracks per-node exclusion lists so arguments introduced by postcss-mixins aren’t treated as globals. There are no internal module boundaries — every concern (definition, variable lookup, simple syntax, string-interpolation syntax, per-node-type handlers) is a small top-level function, all funneling through one central variable() resolver; changing that resolver would affect every consumer (values, props, selectors, at-rule params, comments) at once.

Tech Stack Plain CommonJS JavaScript with a peer dependency on postcss@^8.2.1, using the modern helpers-based visitor API rather than the older PostCSS 7 style. TypeScript consumers get hand-authored declarations via index.d.ts. Tooling is uvu for tests, c8 for coverage (with a 100% line-coverage gate configured in package.json), ESLint with @logux/eslint-config, Prettier (config inlined in package.json), pnpm for dependency management, and clean-publish to strip dev-only fields before publishing. GitHub Actions CI runs a full install-and-test job on the latest Node plus a quick matrix across Node 18–24.

Code Quality index.test.js uses uvu with its own assert module and exercises interop with postcss-mixins, postcss-for, and postcss-each alongside direct substitution in values, selectors, at-rule params, and comments, plus backslash/unicode escape handling. c8’s check-coverage: true with lines: 100 enforces full line coverage as a hard CI gate — a strong quality signal for a package this size. There’s no internal TypeScript, so there’s no compiler-enforced type safety in the implementation itself, though the bundled .d.ts gives typed consumers a checked surface. Errors are raised via PostCSS’s own node.error() mechanism rather than custom error classes, which is idiomatic for the ecosystem. Naming is terse but consistent, mirroring PostCSS’s own vocabulary (Declaration/Rule/AtRule/Comment).

API Design The module exports a single factory function, matching how every other PostCSS plugin is consumed — drop require('postcss-simple-vars') straight into a plugins array with zero extra boilerplate beyond installing the peer dependency. Options are a flat object (variables, onVariables, unknown, silent, only, keep) with sensible defaults (throw on unknown variable, don’t retain the declaration), so the common case needs no configuration at all. Two variable syntaxes — plain $name for values/selectors and $(name) for interpolation inside larger words, property names, or comments — cover a real CSS authoring gap (you can’t write margin-$dir unambiguously) without inventing a parallel templating language. The README documents every syntax variant with runnable before/after CSS examples, including escape-sequence edge cases.