PostCSS plugin to extract all media query from CSS and emit as separate files.
npm install postcss-extract-media-queryIf 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 dynamically import based on the user's viewport (recommended) or load with lower priority (less performance gain) as
Before
- example.css
``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
`css`
.foo {
color: red;
}
.bar {
font-size: 1rem;
}
- example-desktop.css
`css`
@media screen and (min-width: 1024px) {
.foo {
color: green;
}
.bar {
font-size: 2rem;
}
}
`javascript`
// simple example for dynamically loading desktop specific CSS based on viewport width
if (window.innerWidth >= 1024) {
const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = '/assets/css/example-desktop.css';
document.head.append(link);
}
- npm
`bash`
npm install postcss postcss-extract-media-query --save-dev
- yarn
`bash`
yarn add postcss postcss-extract-media-query --dev
Simply 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 |
| src.path | 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 emitted filenames by using output.name. [path] is the relative path of the original CSS file relative to root, [name] is the filename of the original CSS file, [query] the key of the extracted media query and [ext] the original file extension (mostly css). Those three placeholders get replaced by the plugin later.
> :warning: by emitting 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!
`javascript`
'postcss-extract-media-query': {
output: {
path: path.join(__dirname, 'dist'), // emit to 'dist' folder in root
name: '[name]-[query].[ext]' // pattern of emitted files
}
}
By default the plugin flattens the file structure meaning the original folder structure won't be preserved which might be problem if you're using the same file name across multiple folders. This can easily be fixed with the [path] placeholder
`
name: '[path]/[name]-[query].[ext]'
In rare cases where you need more control, you may pass a name function which receive all placeholders as args
`
name: ({ path, name, query, ext }) => {
return
}
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).
`javascript`
'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.
`javascript`
'postcss-extract-media-query': {
extractAll: false
}
By default the plugin displays in your terminal / command prompt which files have been emitted. If you don't want to see it just set this option false.
`javascript`
'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.
`javascript`
'postcss-extract-media-query': {
entry: path.join(__dirname, 'some/path/example.css')
}
> [!NOTE]
> This option is only relevant if you're using the path placeholder in output.name
By default the plugin determines the root by looking for the package.json file and uses it as srcPath (if there's no app or src folder) to compute the relative path.
In case the automatically determined srcPath doesn't suit you, it's possible to override it with this option.
`javascript`
'postcss-extract-media-query': {
output: {
path: path.join(__dirname, 'dist'),
name: '[path]/[name]-[query].[ext]'
},
src: {
// from: example/nested/src/components/button.css
// to: dist/components/button-xxxxx.css
path: path.join(__dirname, 'example/nested/src')
}
}
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.
`javascript`
'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.
`javascript`
'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.
`bash`
npm install postcss --save-dev
Both 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.
`bash`
npm install postcss postcss-combine-media-query cssnano --save-dev
`javascript``
plugins: {
'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.