postcss-normalize

What is postcss-normalize?

The postcss-normalize package integrates the normalize.css library with PostCSS, allowing developers to include normalize.css in their projects as a PostCSS plugin. This package helps in ensuring that browsers render all elements more consistently and in line with modern standards. It automatically imports the parts of normalize.css that you need, based on your project's browserlist configuration.

What are postcss-normalize's main functionalities?

Browser normalization

Automatically includes the relevant parts of normalize.css based on the browsers specified in your project's browserlist. This feature ensures that your CSS behaves more consistently across different browsers.

postcss([ require('postcss-normalize')() ])

Customizable through browserlist

Allows customization of which parts of normalize.css to include by specifying browser versions in the browserlist. This helps in tailoring the normalization to only the necessary browsers, potentially reducing the CSS size.

postcss([ require('postcss-normalize')({ browsers: 'last 2 versions' }) ])

Other packages similar to postcss-normalize

sanitize.css

Similar to postcss-normalize, sanitize.css is a CSS library that provides consistent, cross-browser default styling for HTML elements. However, unlike postcss-normalize, it does not automatically adjust based on browserlist and must be included manually in your CSS.

modern-normalize

modern-normalize is another CSS reset library that normalizes styles for a wide range of elements. It is similar to postcss-normalize but does not integrate directly with PostCSS as a plugin and must be included separately in your project.

README

PostCSS Normalize

PostCSS Normalize lets you use the parts of normalize.css or sanitize.css that you need from your browserslist.

@import "normalize.css";

@import "sanitize.css";

PostCSS Normalize uses a non-opinionated version of normalize.css, but an opinionated version may also be used.

@import "normalize.css/opinionated.css";

Examples

Here is a sample of what normalize.css looks like when the browserslist is ie >= 9:

/**
 * Add the correct display in IE 9-.
 */

audio,
video {
  display: inline-block;
}

/**
 * Remove the border on images inside links in IE 10-.
 */

img {
  border-style: none;
}

And here is the same sample when the browserslist is ie >= 10:

/**
 * Remove the border on images inside links in IE 10-.
 */

img {
  border-style: none;
}

Usage

Add PostCSS Normalize to your project:

npm install postcss-normalize --save-dev

Add a browserslist entry in package.json:

{
  "browserslist": "last 2 versions"
}

Use PostCSS Normalize to process your CSS:

const postcssNormalize = require('postcss-normalize')

postcssNormalize.process(YOUR_CSS /*, processOptions, pluginOptions */)

Or use it as a PostCSS plugin:

const postcss = require('postcss')
const postcssNormalize = require('postcss-normalize')

postcss([
  postcssNormalize(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */)

PostCSS Normalize runs in all Node environments, with special instructions for:

Node	PostCSS CLI	Webpack	Create React App	Gulp	Grunt

PostCSS Import Usage

PostCSS Normalize includes a postcssImport function to configure PostCSS Import and allow you to continue using the @import syntax.

const postcss = require('postcss')
const postcssImport = require('postcss-import')
const postcssNormalize = require('postcss-normalize')

postcss([
  postcssImport(
    postcssNormalize(
      /* pluginOptions (for PostCSS Normalize) */
    ).postcssImport(
      /* pluginOptions (for PostCSS Import) */
    )
  )
]) // now you can use @import "normalize.css", etc. again

Alternatively, use @import-normalize or @import-sanitize to avoid conflicts with @import transforms.

@import-normalize;

@import-normalize "opinionated.css";

@import-sanitize;

Options

allowDuplicates

The allowDuplicates option determines whether multiple, duplicate insertions of CSS libraries are allowed. By default, duplicate libraries are omitted.

postcssNormalize({ allowDuplicates: true })

forceImport

The forceImport option defines CSS libraries that will be inserted at the beginning of the CSS file. Unless overriden by allowDuplicates, duplicate CSS libraries would still be omitted.

postcssNormalize({ forceImport: true })

Specific CSS libraries may be defined.

postcssNormalize({
  forceImport: 'sanitize.css'
})

browsers

The browsers option defines an override of the project’s browserslist for PostCSS Normalize. This option should be avoided in leui of a browserslist file.

postcssNormalize({ browsers: 'last 2 versions' })

CSS Libraries

PostCSS Normalize can include normalize.css or sanitize.css and configure either with the following combinations:

@import "normalize"; /* also, @import "normalize.css" */
@import "normalize/opinionated"; /* also, @import "normalize.css/opinionated.css", @import "normalize.css/*" */
@import "sanitize"; /* also, @import "sanitize.css" */
@import "sanitize/assets"; /* also, @import "sanitize.css/assets.css" */
@import "sanitize/forms"; /* also, @import "sanitize.css/forms.css" */
@import "sanitize/reduce-motion"; /* also, @import "sanitize.css/reduce-motion.css" */
@import "sanitize/system-ui"; /* also, @import "sanitize.css/system-ui.css" */
@import "sanitize/typography"; /* also, @import "sanitize.css/typography.css" */
@import "sanitize/ui-monospace"; /* also, @import "sanitize.css/ui-monospace.css" */
@import "sanitize/*"; /* also, @import "sanitize.css/*" (sanitize + all additions) */