icss-replace-symbols

What is icss-replace-symbols?

The icss-replace-symbols package is designed for handling Interoperable CSS (ICSS) by replacing symbols in CSS files with their corresponding values. This is particularly useful in the context of CSS Modules, where local class names and other identifiers need to be scoped locally to avoid conflicts. The package provides functionality to parse CSS files, identify symbols, and replace them with specified values, facilitating the modularization and encapsulation of CSS.

What are icss-replace-symbols's main functionalities?

Replacing symbols in CSS

This feature allows for the replacement of symbols within CSS strings. In the code sample, `icss-replace-symbols` is used to replace the symbol `header` with `header_a9x82` in a CSS string. This is useful for scoping class names locally in CSS Modules.

const replaceSymbols = require('icss-replace-symbols');
const css = ':export { header: header_c3b5x } .header { color: red; }';
const replacements = { header: 'header_a9x82' };
const result = replaceSymbols(css, replacements);
console.log(result);

Other packages similar to icss-replace-symbols

postcss-modules

Similar to icss-replace-symbols, postcss-modules is a PostCSS plugin that helps in transforming CSS with JS plugins and allows for local scoping of CSS by automatically renaming classes and other identifiers. It differs in that it is part of the PostCSS ecosystem, offering a broader range of transformations beyond symbol replacement.

css-loader

css-loader is a loader for webpack that interprets `@import` and `url()` like `import/require()` and will resolve them. It also offers modules functionality, which enables local scoping of CSS by default. While it provides similar functionality in terms of scoping CSS, it is specifically designed to work within webpack's module bundling system.

README

ICSS — Replace Symbols

Governs the way tokens are searched & replaced during the linking stage of ICSS loading.

This is broken into its own module in case the behaviour needs to be replicated in other PostCSS plugins (i.e. CSS Modules Constants)

API

import replaceSymbols from "icss-replace-symbols"
replaceSymbols(css, translations)

Where:

• css is the PostCSS tree you're working with
• translations is an JS object of symbol: "replacement" pairs, where all occurrences of symbol are replaced with replacement.

Behaviour

A symbol is a string of alphanumeric, - or _ characters. A replacement can be any string. They are replaced in the following places:

• In the value of a declaration, i.e. color: my_symbol; or box-shadow: 0 0 blur spread shadow-color
• In a media expression i.e. @media small {} or @media screen and not-large {}

License

ISC

Glen Maddern, 2015.