postcss-redirect-import v2.0.0

postcss-redirect-import

It is decoration for plugin postcss-import, which helps to create resolve rules.

Installation

$ npm install postcss-redirect-import --D

Usage

First, you should learn how to use post-import, because the plugin uses its functionality and acts in the same way, with one exception: in the options you can specify the instructions for the path substitution.

// dependencies
var fs = require("fs")
var postcss = require("postcss")
var subImport = require("postcss-redirect-import")

// css to be processed
var css = fs.readFileSync("css/input.css", "utf8")

// process css
postcss()
  .use(subImport([
    {
      match: {
        base: /components/
      },
      use: {
        base: '<root>/custom/<folder>'
      }
    }
  ]))
  .process(css, {
    // `from` option is required so relative import can work from input dirname
    from: "css/input.css"
  })
  .then(function (result) {
    var output = result.css

    console.log(output)
  })

How it works

The rule consists of two parts:

1. Conditions in which cases a rule should work. To do this, you specify a regular expression for request (query string) and/or base (path to module which requires resource).

For example, you have style.css inside directory app/components/Button, which imports colors.css.

@import "colors.css";

Button {
  background-color: $bgColor;
}

Here:

• colors.css is request;
• ./app/components/Button is base;

Use regular expressions to create the condition, based on these values:

subImport([{
  match: {
    request: /colors\.css/,
    base: /components\/Button/,
  },
  use: {
    ...
  }
}]);

Next property specify a new values of request and/or base.

Use a property to when you want to specify a particular file.

subImport([{
  match: {
    request: /colors\.css/,
    base: /components\/Button/,
  },
  use: {
    request: "./customized/components/Button/colors.css",
    base: "<root>"
  }
}]);

This way will give you:

/* content of ./customized/components/colors.css
instead of ./app/components/Button/colors.css */

Button {
  background-color: $bgColor;
}

Using substrings

You can use the substrings retrieved from request or base by the regular expression to form the path. To insert a substring of a concrete source there are special aliases, that are created based on the pattern <{source}:{index}>.

subImport([
  {
    match: {
      request: /([a-z0-9\.\-]*\.css)$/i,
      base: /components/([a-z0-9]*)\/assets\/([a-z0-9]*)$/i,
    },
    use: {
      request: '~/theme/components/<base:1>/assets/<base:2>/<request:1>'
    }
  }
]);

In this case, we get the three aliases:

• ([a-z0-9\.\-]*\.css) will become <request:1> and will contain required filename;
• First ([a-z0-9]*) will become <base:1> and will contain component name;
• Second ([a-z0-9]*) will become <base:2> and will contain some directory inside assets.

Usage of approach of the regular expression is limited only by your imagination.

In addition, you can use predefined placeholders, such as <root>, <id>, <basename> (read Predefined placeholders).

Not strict substitution

A nice feature of the plugin is the fact that if the overridden path does not exists, it will use the standard method of file resolving. It allows you to create an environment in which any style can work fine without substitution (for example, in the case of using the classic postcss-import plugin). When you replace postcss-import to postcss-redirect-import, you have the opportunity to customize the styles without spoiling the original sources.

Appending

In some cases, it is important not to replace imported resource, and to add to the default. For these cases, there is an option append.

subImport([
    {
      match: {
        request: /variables\.css/,
      },
      use: {
        request: "<root>/global/style.css",
      },
      append: true
    }
])

The added resource will work exactly the same as if you add it as a second import.

@import "variables.css";
@import "style.css"; /* Appended style */

Properties of rules

• match {object} The values for matching:
  • request {RegExp} Regular expression to match and test request;
  • base {RegExp} Regular expression to match and test base.
• use {object} The substituted values:
  • request {string} Path to target file;
  • base {string} Path of directory to resolve with.
• append {bool} Enable append mode.

Designation

• request The string passed to import; @import "it_is_id";
• base The absolute path to the directory, relative to which the file will be resolved.

Predefined placeholders

"~": root, "": request, "": root, "": base, "": path.parse(request).base, "": basename,

• <root>, ~ Root directory of the project (process.cwd() by default);
• <request> The string passed to import;
• <id> The name of requested file;
• <base> The path to the folder where an import was performed from;
• <basename> The name of the folder where an import was performed from.

Using original postcss-import options

You can define original postcss-import options as well as the usual. But in this case, the rules for a postcss-redirect-import is specified in the property sub.

subImport({
    root: path.join(process.cwd(), 'app'),
    redirect: {
      match: {...},
      use: {...}
    }
});

If you wanna to specify your own resolve function, keep in mind that your function will be called only in case of failure of sub.

Examples

Common theme

Append to all theme.css common theme.

git clone https://github.com/morulus/postcss-redirect-import.git
cd postcss-redirect-import/examples/common-theme
npm install
npm start

License

Under MIT license, 2016-2017, Vladimir Kalmykov vladimirmorulus@gmail.com