If page speed is important to you chances are high you're already doing code splitting. If your CSS is built mobile-first (in particular if using a framework such as Bootstrap or Foundation) chances are also high you're loading more CSS than the current viewport actually needs.
It would be much better if a mobile user doesn't need to load desktop specific CSS, wouldn't it?
That's the use case I've written this PostCSS plugin for! It lets you extract all @media rules from your CSS and emit them as separate files which you can load as <link rel="stylesheet" media="screen and (min-width: 1024px)" href="desktop.css"> or as dynamic import.
Before
- example.css
.foo {
color: red;
}
@media screen and (min-width: 1024px) {
.foo {
color: green;
}
}
.bar {
font-size: 1rem;
}
@media screen and (min-width: 1024px) {
.bar {
font-size: 2rem;
}
}After
- example.css
.foo {
color: red;
}
.bar {
font-size: 1rem;
}- example-desktop.css
@media screen and (min-width: 1024px) {
.foo {
color: green;
}
.bar {
font-size: 2rem;
}
}- npm
npm install postcss postcss-extract-media-query --save-dev- yarn
yarn add postcss postcss-extract-media-query --devSimply add the plugin to your PostCSS config. If you're not familiar with using PostCSS you should read the official PostCSS documentation first.
You can find complete examples here.
| option | default |
|---|---|
| output.path | path.join(__dirname, '..') |
| output.name | '[name]-[query].[ext]' |
| queries | {} |
| extractAll | true |
| stats | true |
| entry | null |
By default the plugin will emit the extracted CSS files to your root folder. If you want to change this you have to define an absolute path for output.path.
Apart from that you can customize the emited filenames by using output.name. [name] is the filename of the original CSS file, [query] the key of the extracted media query and [ext] the orignal file extension (mostly css). Those three placeholders get replaced by the plugin later.
⚠️ by emiting files itself the plugin breaks out of your bundler / task runner context meaning all your other loaders / pipes won't get applied to the extracted files!
'postcss-extract-media-query': {
output: {
path: path.join(__dirname, 'dist'), // emit to 'dist' folder in root
name: '[name]-[query].[ext]' // pattern of emited files
}
}By default the params of the extracted media query is converted to kebab case and taken as key (e.g. screen-and-min-width-1024-px). You can change this by defining a certain name for a certain match. Make sure it exactly matches the params (see example below).
'postcss-extract-media-query': {
queries: {
'screen and (min-width: 1024px)': 'desktop'
}
}By default the plugin extracts all media queries into separate files. If you want it to only extract the ones you've defined a certain name for (see queries option) you have to set this option false. This ignores all media queries that don't have a custom name defined.
'postcss-extract-media-query': {
extractAll: false
}By default the plugin displays in your terminal / command prompt which files have been emited. If you don't want to see it just set this option false.
'postcss-extract-media-query': {
stats: true
}By default the plugin uses the from value from the options of the loader or of the options you define in postcss().process(css, { from: ... }). Usually you don't need to change it but if you have to (e.g. when using the plugin standalone) you can define an absolute file path as entry.
'postcss-extract-media-query': {
entry: path.join(__dirname, 'some/path/example.css')
}By default the plugin looks for a postcss.config.js file in your project's root (read node-app-root-path to understand how root is determined) and tries to apply all subsequent PostCSS plugins to the extracted CSS.
In case this lookup doesn't suite you it's possible to specify the config path yourself.
'postcss-extract-media-query': {
config: path.join(__dirname, 'some/path/postcss.config.js')
}It's also possible to pass the config as object to avoid any file resolution.
'postcss-extract-media-query': {
config: {
plugins: {
'postcss-extract-media-query': {}
'cssnano': {}
}
}
}PostCSS has been updated to 8.x (which is the minimum required version now) and is no longer packaged with this plugin but has become a peer dependency. What does this mean for you? If you're using npm >= v7 it's automatically installed, otherwise you need to install it yourself.
npm install postcss --save-devBoth options, combine and minimize, have been removed in v2 because the plugin parses your postcss.config.js now and applies all subsequent plugins to the extracted files as well.
So if you have used them you simply need to install appropriate PostCSS plugins (see below for example) and add them to your PostCSS config.
npm install postcss postcss-combine-media-query cssnano --save-devplugins: {
'postcss-combine-media-query': {},
'postcss-extract-media-query': {},
'cssnano': {},
}If you're using this plugin via the api (e.g. for your own plugin) you should note it has changed from sync to async in v2. This was necessary in the course of going with promises. I'm not going to keep support of the sync api because it would make the code more complex than necessary and it's officially recommended to use async. Please check the tests to see how it has to be done now!
If you're using webpack you should use media-query-plugin which is built for webpack only and thus comes with several advantages such as applying all other loaders you've defined and hash support for caching.
If this plugin is helpful to you it'll be great when you give me a star on github and share it. Keeps me motivated to continue the development.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent