postcss-prefixwrap
TypeScript icon, indicating that this package has built-in type declarations

1.45.0 • Public • Published

PostCSS Prefix Wrap

CI GitHub Pipeline SAST GitHub Pipeline Latest Release NPM Downloads Per Week

A PostCSS plugin which prepends a selector to CSS styles to constrain their effect on parent elements in a page.

Supports Versions
NodeJS v18, v19, v20, v21
PostCSS v7, v8

⚠️ PostCSS v7 support is no longer validated in automated test cases, and will be removed entirely in a future release.

How to use this plugin?

⚠️ These instructions are only for this plugin. See the PostCSS website for framework information.

Install

Package Manager Command
NPM npm install postcss-prefixwrap --save-dev --save-exact
PNPM pnpm add postcss-prefixwrap --save-dev --save-exact
Yarn yarn add postcss-prefixwrap --dev --exact

Configure

Add to your PostCSS configuration.

const PostCSS = require("gulp-postcss");
const PrefixWrap = require("postcss-prefixwrap");

PostCSS([PrefixWrap(".my-custom-wrap")]);

Container

Add the container to your markup.

<div class="my-custom-wrap"><!-- Your existing markup. --></div>

View

View your CSS, now prefix-wrapped.

Before

p {
    color: red;
}

body {
    font-size: 16px;
}

After

.my-custom-wrap p {
    color: red;
}

.my-custom-wrap {
    font-size: 16px;
}

What options does it have?

Minimal

The minimal required configuration is the prefix selector, as shown in the above example.

PrefixWrap(".my-custom-wrap");

Ignored Selectors

You may want to exclude some selectors from being prefixed, this is enabled using the ignoredSelectors option.

PrefixWrap(".my-custom-wrap", {
    ignoredSelectors: [":root", "#my-id", /^\.some-(.+)$/],
});

Prefix Root Tags

You may want root tags, like body and html to be converted to classes, then prefixed, this is enabled using the prefixRootTags option.

PrefixWrap(".my-container", {
    prefixRootTags: true,
});

With this option, a selector like html will be converted to .my-container .html, rather than the default .my-container.

File Whitelist

In certain scenarios, you may only want PrefixWrap() to wrap certain CSS files. This is done using the whitelist option.

⚠️ Please note that each item in the whitelist is parsed as a regular expression. This will impact how file paths are matched when you need to support both Windows and Unix like operating systems which use different path separators.

PrefixWrap(".my-custom-wrap", {
    whitelist: ["editor.css"],
});

File Blacklist

In certain scenarios, you may want PrefixWrap() to exclude certain CSS files. This is done using the blacklist option.

⚠️ Please note that each item in the blacklist is parsed as a regular expression. This will impact how file paths are matched when you need to support both Windows and Unix like operating systems which use different path separators.

If whitelist option is also included, blacklist will be ignored.

PrefixWrap(".my-custom-wrap", {
    blacklist: ["colours.css"],
});

Nesting

When writing nested css rules, and using a plugin like postcss-nested to compile them, you will want to ensure that the nested selectors are not prefixed. This is done by defining the nested property and setting the value to the selector prefix being used to represent nesting, this is most likely going to be "&".

PrefixWrap(".my-custom-wrap", {
    nested: "&",
});

As an example, in the following CSS that contains nested selectors.

.demo {
    &--lite {
        color: red;
    }
}

❌ Without the nested configuration option defined:

.my-custom-wrap .my-custom-wrap .demo--lite {
    color: red;
}

✅ With the tested configuration defined:

.my-custom-wrap .demo--lite {
    color: red;
}

What problems can it solve?

PostCSS Prefix Wrap can be used to solve multiple different problems. The following articles give some concrete examples:

How to contribute?

Read our Contributing Guide to learn more about how to contribute to this project.

Is this project secure?

SAST GitHub Pipeline OpenSSF Scorecard OpenSSF Best Practices

Read our Security Guide to learn how security is considered during the development and operation of this plugin.

License

The MIT License is used by this project.

Package Sidebar

Install

npm i postcss-prefixwrap

Weekly Downloads

62,996

Version

1.45.0

License

MIT

Unpacked Size

43.7 kB

Total Files

24

Last publish

Collaborators

  • dbtedman