style-mod

style-mod is a tiny, dependency-free library for generating CSS rules from JavaScript objects and mounting them onto a document or shadow root. Instead of a build-time compiler, it lets you define a StyleModule from a plain object spec — camelCase properties, &-based sub-selector nesting, and @-block support for media queries and keyframes — and attach the resulting rules at runtime with a single mount call.

Written by Marijn Haverbeke (also the author of CodeMirror and ProseMirror), style-mod is best known as the CSS engine underneath CodeMirror 6, where it powers per-editor-instance theming without global stylesheet collisions. Its implementation fits in one small file, keeping it easy to audit, and it supports both classic <style>-tag injection and modern Constructable/Adopted StyleSheets for shadow DOM contexts.

What You Get

• StyleModule class - build a set of CSS rules from a plain JS object spec, with camelCase properties automatically converted to kebab-case
• & sub-selector nesting - extend the current selector with pseudo-classes or child combinators using a & placeholder, including multi-selector expansion
• @-block support - wrap style declarations in @media, @keyframes, or other at-rules directly from the same object spec
• Dual mounting strategy - falls back between Constructable StyleSheets (adoptedStyleSheets) for shadow roots and a plain <style> tag for documents
• Deduplication and ordering - StyleModule.mount tracks which modules are already mounted per root and only reorders rules when necessary
• TypeScript typings included - ships its own .d.ts defining StyleModule and the recursive StyleSpec type

Common Use Cases

• Theming a code editor - CodeMirror 6 uses style-mod internally to scope per-instance editor themes without leaking styles onto the rest of the page
• Shadow DOM component styling - mount styles into a custom element’s shadow root using Constructable StyleSheets rather than injecting a <style> tag per instance
• Dynamic CSS-in-JS without a build step - generate rule sets computed at runtime from a plain JavaScript object, with no compiler or bundler plugin required
• Media query and keyframe styling from JS - define responsive breakpoints or CSS animations alongside the rest of a component’s style object

Under The Hood

Architecture The implementation is a single small file exporting one public class, StyleModule, alongside an internal, unexported StyleSet helper and a module-level cache used to dedupe Constructable StyleSheets per document. The constructor recursively walks the spec object through a local render closure, building rule strings into an internal rules array. Mounting is deliberately decoupled from construction: StyleModule.mount looks up (or lazily creates) a StyleSet keyed off a private symbol stashed directly on the DOM root, so mounted state lives on the DOM node itself rather than in a separate registry. StyleSet’s mount logic reconciles the previously mounted module list against the newly requested one, splicing and re-inserting only the modules whose position actually changed, keeping rule order stable across repeated calls. There is no dependency injection and no build-time step; the only state beyond the DOM itself is the private per-document cache used for shared adopted stylesheets, so the one place a change would ripple outward is the recursive per-property dispatch that decides whether a key is a selector, an & nesting, an @-block, or a plain declaration.

Tech Stack The package has zero runtime dependencies — everything under dependencies is absent, with only dev tooling declared: a small ES2015 transpiler for producing the CommonJS build, a docs generator that regenerates the README from source comments, a lightweight assertion library, and a mocha-based test runner. Source is authored as native ESM with a hand-written TypeScript declaration file sitting alongside the plain JS (no tsc compilation step). The build pipeline transpiles the ESM source and post-processes it into a CommonJS bundle, exposed through a dual exports map for both import and require consumers — a lightweight, tool-minimal dual-package strategy. The only runtime API surface touched is standard DOM: element creation, CSSStyleSheet, and adoptedStyleSheets.

Code Quality A single test suite covers rule rendering, &-nesting, multi-selector expansion, @media/@keyframes blocks, the selector-rewrite hook, and duplicate-property handling — solid behavioral coverage of the rendering logic, though the DOM-mounting half has no visible tests in a shallow clone of the repo. Naming is terse, consistent with the author’s minimalist style seen across their other projects, and error handling is limited to a single explicit thrown error for a misused property. There is no linter or formatter configuration and no CI workflow visible in the repository, and because the implementation itself is plain JS rather than TypeScript, there is no static type-checking of the logic — only the accompanying declaration file describes the public shape.

API Design The entire public surface is one class with two static methods and one instance method, keeping the learning curve close to zero — a plain nested object literal plus a single mount call is enough to get started. The &-substitution convention for sub-selectors and the @-prefix convention for at-rules let one object shape express selectors, pseudo-classes, media queries, and keyframes without a second DSL or template-tag step, at the cost of being fully string/property-name driven, so a typo in a key silently becomes malformed CSS rather than a validation error. The dedup-by-reference mounting model — passing the same module object again is a no-op — is a distinctive design choice suited to being embedded inside another library, where callers construct modules once at load time and repeatedly re-mount them per instance without accumulating duplicate rules.