CSS Modules: Structural, Not Conventional, Scoping

A file named with the .module.css convention (or configured equivalent) is processed by a build step that scans every class selector and rewrites it into a name guaranteed unique across the entire build — typically incorporating the component's filename and a content hash, like .Card_card__a1b2c. The build tool also emits a JavaScript object (often accessed by importing the CSS file directly) mapping your original, readable class name (card) to the generated hashed one, so your component code references styles.card and never needs to know or hardcode the actual hash.

This is a genuinely different kind of safety than BEM's naming convention: BEM reduces collision risk through disciplined naming that developers have to apply correctly and consistently; CSS Modules eliminate collision risk structurally, since two completely differently-authored components can both use the literal class name .card with zero actual collision, because the build tool guarantees each gets a distinct hashed output.

CSS Modules' default behavior — every class scoped locally and hashed — covers the overwhelming majority of real component styling needs. But some cases genuinely require targeting a real, unhashed global class name: styling markup rendered by a third-party library whose class names you don't control and can't hash, or intentionally applying a style globally across the whole application.

:global(.some-class) is the explicit, deliberate escape hatch for exactly this — it tells the build tool 'don't hash this specific selector, treat it as a genuine global class name'. Because this is an explicit, visible marker in the source rather than an accidental default, it keeps the intentional global exceptions clearly distinguishable from the safely-scoped majority of a file's rules.

The composes keyword lets a local class declare that it also includes another class's styles — composes: button; inside .primaryButton doesn't merge or inherit CSS declarations the way Sass's @extend or the cascade might; instead, the build tool resolves it into applying *both* hashed class names (button's and primaryButton's) together on the actual rendered element. Both rule sets' styles genuinely apply, completely independent of any specificity or source-order consideration, since it's not going through the cascade at all — it's a build-time composition of which classes end up on the element.

This makes composes a genuinely different, arguably cleaner sharing mechanism than cascade-based approaches: there's no risk of a specificity conflict between the composed and composing styles, since both are simply applied as separate, co-existing classes on the same element, exactly as if you'd manually written className="button primaryButton" yourself, but generated safely and automatically by the build tool.

Build-Time Scoping, Automated. BEM solves CSS's global scoping problem through naming discipline — a convention humans have to follow correctly, every time. CSS Modules solve the exact same problem differently: a build tool automatically rewrites every class name into something guaranteed unique, making naming collisions structurally impossible rather than merely unlikely.

Automatic Class Name Hashing. A CSS Modules build step transforms .card { } written in a .module.css file into something like .Card_card__a1b2c at build time, and generates a corresponding JavaScript object mapping your original class name to the hashed one — you import and use styles.card in your component, never needing to know or write the actual generated hash yourself.

How Class Hashing Works. Why does automatic class name hashing make naming collisions structurally impossible, rather than just less likely?

• →It's still just a naming convention, so collisions remain possible if not followed correctly
• →The build tool generates a genuinely unique hash for every class, tied to its specific file and declaration, so two components can use the identical original class name with zero actual collision risk
• →There's no real difference from a naming convention like BEM

Local Scope By Default, Global When Needed. Every class in a .module.css file is scoped locally by default — hashed and unreachable from outside its own component's JavaScript import. The :global() escape hatch explicitly opts a specific selector out of this scoping when you genuinely need to target something outside the module's own boundary, like styling a third-party library's markup.

The :global() Escape Hatch. What does wrapping a selector in :global() inside a CSS Module file do?

• →It gives the rule !important priority
• →It explicitly opts that specific selector out of the automatic local hashing, targeting a real, unhashed global class name instead
• →It has no functional effect, purely documentation

composes: Sharing Styles Without Duplication Or Cascade Reliance. The composes keyword lets one local class inherit another local class's (or an imported class's) styles directly, resolved at build time into the final class list applied to the element — a form of style composition that doesn't rely on the cascade or inheritance at all, avoiding the specificity concerns those mechanisms can introduce.

Understanding composes. What does composes: button; inside .primaryButton actually produce in the final rendered HTML?

• →primaryButton's CSS rule set inherits button's declarations via the cascade
• →Both the hashed .button and .primaryButton class names get applied together on the element, so both rule sets' styles apply
• →It renames .primaryButton to .button entirely

CSS Modules Mastered. You now understand how CSS Modules solve global scoping structurally through automatic build-time class hashing, how :global() provides a deliberate escape hatch for the rare genuinely-global case, and how composes shares styles between local classes without relying on the cascade or inheritance.

Style A Module-Scoped Class. CSS Modules append a unique suffix to each class name to guarantee it's scoped to one component.