Not Parents' Money

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

    1.38.1 • Public • Published

    PostCSS Prefix Wrap

    CI GitHub Pipeline SAST GitHub Pipeline 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 v14, v15, v16, v17, v18
    PostCSS v7, v8

    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?

    💡 Hi there! If you have a problem that you have used this plugin for, I would like to hear so I can list it here to share with the community.

    Embedding content within an existing site

    You may be asked to develop a piece of interactivity that needs to live within a content management system that you do not control. You may find that your styles are impacted by the CSS already on the site, or that your newly included CSS now impacts the rest of the page it is embedded in.

    PostCSS Prefix Wrap solves this problem by prefixing your CSS selectors so that they only apply to HTML contained within a parent containing element. Your styles will now take precedence over those of the parent page.

    On the flip side, your styles wont negatively impact the site your content is hosted on as its scoped to that parent container.

    This is in fact the origin story for this plugin, for developing interactive content to live within the Blackboard LMS.

    🤔 You might wonder why its necessary to use this plugin when you could just prefix your styles yourself. Yes, this is correct, but does not apply to any 3rd party code you include such as a CSS framework like Bootstrap.

    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.

    Install

    npm i postcss-prefixwrap

    DownloadsWeekly Downloads

    7,349

    Version

    1.38.1

    License

    MIT

    Unpacked Size

    41.9 kB

    Total Files

    24

    Last publish

    Collaborators

    • dbtedman