postcss-modules-local-by-default

What is postcss-modules-local-by-default?

The postcss-modules-local-by-default npm package is a PostCSS plugin that modifies CSS class names to be locally scoped by default. This is part of CSS Modules, which helps avoid class name collisions and ensures styles are encapsulated to specific components only. It rewrites all class names in CSS files to be scoped locally unless explicitly specified otherwise.

What are postcss-modules-local-by-default's main functionalities?

Local Scoping of Class Names

Automatically transforms global CSS class names into locally scoped names. This prevents class name collisions across different components or sections of a web application.

/* Input CSS */
.className {
  color: red;
}

/* Output CSS after processing with postcss-modules-local-by-default */
._className_xkpkl_1 {
  color: red;
}

Selective Global Scoping

Allows developers to selectively keep some class names global. This is useful for overriding styles or for styles that are meant to be consistent across various components.

/* Input CSS */
:global(.globalClassName) {
  color: blue;
}

/* Output CSS remains unchanged */
.globalClassName {
  color: blue;
}

Other packages similar to postcss-modules-local-by-default

postcss-modules-scope

Similar to postcss-modules-local-by-default, this package helps in scoping CSS class names locally. However, postcss-modules-scope provides more customizable options for generating scoped names, making it more flexible in projects that require a specific naming convention.

postcss-modules-values

This package is part of the CSS Modules ecosystem and allows sharing values between CSS files, such as variables. While it doesn't handle scoping of class names, it complements postcss-modules-local-by-default by managing shared values, enhancing the modularity of CSS.

README

CSS Modules: Local by Default

Transformation examples:

Selectors (mode local, by default)::

.foo { ... } /* => */ :local(.foo) { ... }

.foo .bar { ... } /* => */ :local(.foo) :local(.bar) { ... }

/* Shorthand global selector */

:global .foo .bar { ... } /* => */ .foo .bar { ... }

.foo :global .bar { ... } /* => */ :local(.foo) .bar { ... }

/* Targeted global selector */

:global(.foo) .bar { ... } /* => */ .foo :local(.bar) { ... }

.foo:global(.bar) { ... } /* => */ :local(.foo).bar { ... }

.foo :global(.bar) .baz { ... } /* => */ :local(.foo) .bar :local(.baz) { ... }

.foo:global(.bar) .baz { ... } /* => */ :local(.foo).bar :local(.baz) { ... }

Declarations (mode local, by default):

.foo {
  animation-name: fadeInOut, global(moveLeft300px), local(bounce);
}

.bar {
  animation: rotate 1s, global(spin) 3s, local(fly) 6s;
}

/* => */ 

:local(.foo) {
  animation-name: :local(fadeInOut), moveLeft300px, :local(bounce);
}

:local(.bar) {
  animation: :local(rotate) 1s, spin 3s, :local(fly) 6s;
}

Pure Mode

In pure mode, all selectors must contain at least one local class or id selector

To ignore this rule for a specific selector, add the a /* cssmodules-pure-ignore */ comment in front of the selector:

/* cssmodules-pure-ignore */
:global(#modal-backdrop) {
  ...;
}

or by adding a /* cssmodules-pure-no-check */ comment at the top of a file to disable this check for the whole file:

/* cssmodules-pure-no-check */

:global(#modal-backdrop) {
  ...;
}

:global(#my-id) {
  ...;
}

Building

$ npm install
$ npm test

• Build:
• Lines:
• Statements:

Development

$ yarn test:watch

License

MIT

With thanks

• Tobias Koppers
• Glen Maddern

---

Mark Dalgleish, 2015.

Changelog

4.2.0 - 2024-12-11

• feat: add support a /* cssmodules-pure-no-check */ comment