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) */
UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): TypeError: Cannot read property 'indexOf' of undefined
First of all, thanks for your work @jonathantneal
I'd like to report a bug I'm facing while trying to integrate your plugin. Here's my script: https://github.com/ec-europa/ecl-toolkit/blob/8f38812e4675dc7c7df63715109671a7137a2ee9/packages/ecl-builder/scripts/styles.js#L20
If I remove the lines 20-22 (those adding the postcss-normalize plugin), all works fine. Any idea?
Error message:
I use Node.js v6.9.5
Thanks!
Uncareted `sanitize.css` dependency causing failure while requiring `postcss-normalize`
[email protected]removes filepage.css, which is directly referenced incssMap.js:https://github.com/csstools/postcss-normalize/blob/5b80f53e46d43d297d7deaec4704c044fa38fb69/src/lib/cssMap.js#L16
As
sanitize.cssis installed at version*rather than something like12.0.0or^12.0.0,npmusers are auto-upgraded into this breakingsanitize.cssversion. This includes users ofcreate-react-app'sreact-scripts.Error: Cannot find module '@csstools/normalize.css'
That's closely related to this (locked) issue here: https://github.com/facebook/create-react-app/issues/6886
With the difference that I'm not using create-react-app but a custom setup (that is somewhat similar to CRA) and I'm still getting this error after upgrading from 7.0.1 to 8.0.0. I've already removed node_modules and re-installed everything again as it was suggested in the other issue but it's still not working with the same error:
Cannot find module '@csstools/normalize.css'.Can be reproduced by cloning this repo, upgrading postcss-normalize to 8.0.0 and then running
yarn start.Any idea what else I have to change to make postcss and postcss-loader find the normalize.css file?
Compatibility with PostCSS 8
Thanks for your PostCSS plugin!
As you probably know, PostCSS 8 was released a few days ago. It would be great if you could make this plugin compatible with the latest version. The creators of the project have even released this migration guide.
Injects normalize.css multiple times
I am using this with module-css with ExtractTextPlugin and it's injecting the normalize.css before every single css file I have in my project above each file's contents. Which means my stitched together css has numerous copies of normalize.css.
How do I ensure it only includes it one time at the top of the style.css file?
Feature/postcss 8
This pull request upgrade to
postcss@8The test will fail because the current version of
postcss-browser-commentsstill usepostcss@7should be merged after https://github.com/csstools/postcss-browser-comments/pull/4
Related Issue
postcss-browser-commentshttps://github.com/csstools/postcss-browser-comments/issues/5create-react-appcannot upgrade topostcss@8https://github.com/facebook/create-react-app/issues/9664Severe performance degradation caused by postcss-browser-comments
After profiling my webpack builds multiple times I have noticed that postcss-browser-comments is present in almost every task that I zoomed into. After disabling postcss-normalize my build time sped up by 5 times. It seems that postcss-browser-comments performs highly unoptimized transformations on every single CSS file. This side effect is not really explicit in the readme and probably should be dealt with. I will create a similar issue in the postcss-browser-comments repo. (in case it can be fixed in that repo, otherwise I'd prefer having a setting to disable it completely)
Attaching my performance snapshots:
profiles.zip
The slow one is with postcss-normalize enabled and the fast one is without.
Perhaps postcss-browser-comments should be run only on the reset.css, instead of every input it gets.
Custom Import breaks SCSS imports
In the past I've loved using your plugin for this, but I'm currently running into an issue (specifically in this case with laraval mix, but would apply to any precompiled versions of CSS) where the custom import declaration breaks builds for SASS/SCSS due to the fact that its not recognizing the import signature.
I get that its a postCSS tool, but there are lots of people who use PostCSS in conjunction with other formats of CSS processing. Thoughts on how to make it so that it works not only in the PostCSS landscape, but also with other precompiled formats?
normalize disapears after second compilation
I've included this lib and the first time webpack builds, normalize is included fine, but after a second compile (after a css change somewhere else), normalize is no longer imported.
Any ideas?
Optional insertion point?
First of all whoa, love what you've done with this plugin @jonathantneal!
What do you think about providing an optional insertion point hook for the Normalize styles? It's common for buildsteps to operate on multiple CSS files and since postcss-normalize blindly injects into everything it finds you could easily end up with duplicated code without realising, which defeats the purpose of saving bytes with browserlist. This is especially true of more complex SPAs and the like.
Of course you can mitigate this with a dedicated buildstep just for postcss-normalize, but it seems like a gotcha for users.
Maybe something like
Then if it doesn't find the
@normalizerule in a given document it doesn't inject anything. Also gives this method with the current standard of importing Normalize.css withpostcss-import, ie:Anyway to have single insertion across multiple compiles?
I'm using vue, configured the
vue-loaderto render the.vuefile's<style>section to use postcss.As each component get its own
<style>, this plugin would inject itself multiple times. I would like to have a configuration such that it only inject when@import-normalizeis found. So that I can control it to appear only on top-level component. Like:I can workaround it by download the
normalize.cssand usepostcss-import, but it that way I cannot benefit from thebrowserlistto output a smaller file to my targeted browser.Fix resolution of @csstools/normalize.css path when using ESM
When using the postcss-normalize ESM export, the resolution of the @csstools/normalize.css package location fails for me with an
Error: Cannot find module '@csstools/normalize.css'.Not entirely sure if this is due to using yarn workspaces or a Node version incompatibility, but using the official
module.createRequire()andrequireResolve()APIs instead of undocumented internals fixes the issue. Confirmed to work on Node v18, but the APIs are available all the way down to Node v12, so this shouldn't break anything.Also had to fix the tests to reflect changes in @csstools/normalize.css v12.0.0.
Yarn 2 with PnP error
I'm using Next.js with a Custom PostCSS config adding this package as well as installing all with Yarn 2. The problem I'm facing is when i try to run
yarn devit gives me this error:I also ran
yarn dlx @yarnpkg/doctorand it gave me this:I'm new to the Yarn 2 package handling approach, so am I in the right place? Thanks.
Reconsider asterisk-versioning of @csstools/normalize.css and sanitize.css
Context
[email protected]introduced support for normalize and sanitze.css via https://github.com/csstools/postcss-normalize/pull/43.This generous version range broke v10 and v9 ecosystems when
sanitize.cssremoved a file thatpostcss-normalizeimported.https://github.com/csstools/postcss-normalize/pull/60 resolved the issue for v10, but this is not addressing the root cause, only fixing the problem until it breaks again. The changelog even alludes to the uncomfortable position we are in.
Question
Are you in theory amenable to work to remove asterisk-based versioning for direct dependencies, whether done yourself or contributed from the community? Previous comments linked above in #58 seem to indicate yes.
V9: Cannot find module 'sanitize.css/page.css'
Related: #60
Can we also have a 9.0.1 patch please ?
I'm stuck with PostCSS 7 in my project and it looks like postcss-normalize 9.0.0 now breaks every project build with this error:
Thanks
Node 10 support
Hi there, we're upgrading dependencies in CRA and we see that you've dropped support for Node 10, which we're still supporting today (although we plan to deprecated).
It looks like this isn't an issue for PostCSS 8, so I wondered if it was that changes you made mean this no longer works in Node 10.x, or if this was around support only?
If it's the latter, would you consider reverting that - or if not, would it be OK if we fork this until we drop Node 10 if that's OK?
Use PostCSS 8 events
Using
Onceis a bad practice, because it doesn't guarantee plugin comparability (for instance, if@postcss-normalizewill be inserted by mixin).For this plugin
AtRuleis much better event.