Git Product home page Git Product logo

postcss-safe-important's Introduction

PostCSS Safe Important

Build Status Npm Downloads Total Node Version Npm

PostCSS plugin that adds !important to style declarations safely.

Why would I need it?

You should probably look at shadow dom and web components first.

Quoted from Cleanslate

When there are existing CSS styles on a page, and you want to prevent those styles cascading into some part of the page. This is not a stylesheet to use when developing your own website (for that, try Eric Meyer’s classic “Reset CSS” or the “HTML5 Doctors’ adaptation”.

The stylesheet can be useful when distributing content (e.g. a widget, or syndicated news) to third-party websites. The CSS rules in the host site may be unknown and unpredictable, or may change in future without notice, or there may be so many websites you need to distribute to that it is impractical to write specific CSS that overrides the styles in each one. In such situations, the Cleanslate stylesheet will aggressively reset your portion of the content (and nothing else) back to some reasonable default values that you can then build from.

Why not just use an iframe?

Third-party content is often distributed in iframes. Because JavaScript within an iframe can be prevented from accessing the host page, iframes are particularly useful when the host site has security concerns and does not explicitly trust the third-party content.

However, iframes have some drawbacks:

  • You cannot display content outside of the box of the iframe.
  • It is tricky to resize the iframe to match the size of its contents.
  • Your content will be unable to interact with the host page, even if it is trusted.
  • Search engines like Google will not see the content on the host page. Content that is syndicated from a partner website can avoid this by being directly included in the host page.

Whether you work with extreme CSS reset stylesheet like Cleanslate or simply just want to give maximum weight for all your declarations, don't do it manually! Use postcss-safe-important to keep your source styles clean and portable.

Safe?

Adding !important to every declarations might break your style. For example, declarations in a keyframe that are qualified with !important are ignored.

postcss-safe-important will skip unnecessary declarations. You can also set your own exclusions through options or comments (see examples below).

/* Input example */
.foo {
    width: 100px;
    color: #000; /* no !important */ }

.bar {
    /* no important */
    color: ##fff;
    width: 100px; }
/* Output example */
.foo {
    width: 100px !important;
    color: #000; }

.bar {
    color: ##fff;
    width: 100px; }

Usage

$ npm install postcss-safe-important --save-dev

Example

var safeImportant = require("postcss-safe-important");

postcss([
    safeImportant({
        // options
        excludeSelectors: "#bar", // config with string
        excludeDeclarations: /color/, // config with regex
        excludeCSSVariables: ["--width", "--height"], // config with array of string
        excludeAtRules: (atRule) => atRule === "media", // config with function
        excludePaths: p => p.startsWith(path.resolve(__dirname, "../node_modules")), // exclude paths
        disableDefaultExcludes: false, // disable default exclusion lists
        keepComments: true, // all the `no important` comments will be erased
    }),
]);

See tests for more examples.

Comments

You can use either /* no !important */ or /* no important */ to indicate no changing.

If the comment is right inside a rule(be the first child node of the rule), the whole rule will not change.

/* Input example */
.foo {
    /* no important */
    width: 100px;
    color: #000; }

.bar { /* no !important */
    width: 100px;
    color: #000; }
/* Output example */
.foo {
    width: 100px;
    color: #000; }

.bar {
    width: 100px;
    color: #000; }

If the comment is right behind(or below) a declaration, then only the declaration will remain the same.

/* Input example */
.foo {
    width: 100px;
    color: #000; /* no important */}
/* Output example */
.foo {
    width: 100px !important;
    color: #000; }

Options

Exclusions

  • excludeSelectors: exclude selectors. Default empty (default exclusions still applies unless options.disableDefaultExcludes = true)
  • excludeDeclarations: exclude declarations. Default empty (default exclusions still applies unless options.disableDefaultExcludes = true)
  • excludeAtRules: exclude atrules(e.g. @font-face). Default empty (default exclusions still applies unless options.disableDefaultExcludes = true)
  • excludeCSSVariables: exclude CSS variables. Default excludes all CSS Variables.
  • excludePaths. exclude style paths. Default empty.

You can pass either a string, a regexp, an iterable, or a shouldExclude(rule: string): boolean function.

var safeImportant = require("postcss-safe-important");

postcss([
    safeImportant({
        // options
        excludeSelectors: "#bar", // config with string
        excludeDeclarations: /color/, // config with regex
        excludeCSSVariables: ["--width", "--height"], // config with array of string
        excludeAtRules: (atRule) => atRule === "media", // config with function
        excludePaths: p => p.startsWith(path.resolve(__dirname, "../node_modules")), // exclude paths
    }),
]);

If you want styles in node_modules left untouched, let's say your postcss config file is at project root, you can:

var safeImportant = require("postcss-safe-important");
var path = require("path");

postcss([
    safeImportant({
        excludePaths: p => p.startsWith(path.resolve(__dirname, "./node_modules")),
    }),
]);

Keep /* no important */ comments

  • keepComments: bool, default false.

Disable Default Declarations

  • disableDefaultExcludes: bool, default false.

Disable the default exclusion list below.

Default Exclusions

Variables

All CSS variables.

Atrules

  • keyframes
  • font-face

Declarations

  • animation
  • animation-name
  • animation-duration
  • animation-timing-function
  • animation-delay
  • animation-iteration-count
  • animation-direction
  • animation-fill-mode
  • animation-play-state

See PostCSS docs for examples for your environment.

MIT

postcss-safe-important's People

Contributors

adam-lynch avatar crimx avatar dependabot[bot] avatar eddie avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

Forkers

eddie adam-lynch

postcss-safe-important's Issues

Full Example of usage

I would like a full example where I give the plugin a .css file path and outputs a string.

I do not understand what is happening in the example.

It should be inside a file.js that I will run from the command line with 'node file.js'.

Exclude directory option required

I need to apply !important to the styles that originated from src/ while keeping any imported styles from node_modules/ intact. Is it possible to add such an option to the plugin? Is this easier to approach by having 2 different webpack loaders for src/ and module_modules/ styles?

What breaking changes were there in 2.0.0?

I'd like to upgrade but I can't find a changelog, migration notes, or a GitHub release either here or on NPM. Could you please advise what the breaking change was so I can check if I need to make any change after bumping the version?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.