From 3cb64cc83acd541cd2ded17e4fc72feef6c25acb Mon Sep 17 00:00:00 2001 From: SassNinja Date: Fri, 29 Jun 2018 12:09:30 +0200 Subject: [PATCH] update readme Due to the rework of the plugin component and the latest support of other plugins, the readme needed some update. --- README.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 455907a..651e842 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Media Query Plugin +[![Build Status](https://travis-ci.com/SassNinja/media-query-plugin.svg?branch=master)](https://travis-ci.com/SassNinja/media-query-plugin) + Have you ever thought about extracting your media queries from your CSS so a mobile user doesn't have to load desktop specific CSS? If so this plugin is what you need! @@ -53,7 +55,7 @@ yarn add media-query-plugin --dev ### 1. Loader -The plugin comes together with a loader which takes care of the CSS extraction from the source and provides it for the injection afterwards. You are able to override the plugin options via the loader options. But usually this shouldn't be necessary and can be left empty. +The plugin comes together with a loader which takes care of the CSS extraction from the source and provides it for the injection afterwards. **Important:** make sure the loader receives plain CSS so place it between the css-loader and the sass-loader/less-loader. @@ -80,8 +82,7 @@ module.exports = { ### 2. Plugin -Add the plugin to your webpack config. It will inject the extracted CSS of the loader after the compilation. -The two options `include` and `queries` are required for the plugin to work and get explained later. +Add the plugin to your webpack config. It will inject the extracted CSS of the loader after the compilation. To identify the target file for the injection it'll look for `[name]-[query]`. So if CSS with the query `desktop` is extracted from `example.scss`, it'll look for `example-desktop` to do the injection. In case there's no match the extracted CSS gets simply emited as CSS file (it doesn't disappear in nirvana :wink:). ```javascript const MediaQueryPlugin = require('./plugins/media-query-plugin'); @@ -100,40 +101,38 @@ module.exports = { }; ``` -### 3. Extracted Files - -If you use dynamic imports, webpack will try to resolve that import and throw an error if the file does not exist. Thus you have to create those empty files manually in the same folder(s) as the source file which generates the CSS. +### 3. Use Extracted Files -**Important:** the names of those files must follow the pattern `[source name]-[query name]` so an example file could be `example-desktop.scss`. If you don't do this the plugin will extract the specified media queries from the source file but not inject them anywhere. +If you import the extracted CSS (mostly as dynamic import with viewport condition), webpack will try to resolve that import and throw an error if the file does not exist. Thus you have to create those files manually before running webpack. Empty files as placeholder do the job (the get filled later by the plugin). -Afterwards you can simply do this in your JavaScript and webpack will take care of the rest for you +**Important:** as mentioned above the name of those files must follow the pattern `[name]-[query]` so an example file could be `example-desktop.scss` ```javascript -import(/* webpackChunkName: 'example' */ './example.scss'); +import './example.scss'; -if (window.innerWidth >= 1200) { +if (window.innerWidth >= 960) { import(/* webpackChunkName: 'example-desktop' */ './example-desktop.scss'); } ``` ## Options -As mentioned earlier there are two options required (either via plugin or via loader options) +There are only two options available which are both mandatory. ### include Each chunk (which uses the loader) gets checked if its name matches this option. In case of a match each query specified in the `queries` options gets extracted from the chunk. Possible types -- array (e.g. `[example]`) +- array (e.g. `['example']`) - regex (e.g. `/example/`) - boolean (e.g. `true`) ### queries -This option tells the plugin which media queries are supposed to get extracted. If a media query doesn't match it'll stay untouched. Otherwise it gets extracted and afterwards injected into the chunk with the name `[source name]-[query name]`. +This option tells the plugin which media queries are supposed to get extracted. If a media query doesn't match it'll stay untouched. Otherwise it gets extracted and afterwards injected. -**Important:** make sure the keys match 100% the source CSS excl the `@media`. +**Important:** make sure the queries match 100% the source CSS rule excl the `@media`. **Tip:** you can use the same name for different media queries to concatenate them (e.g. desktop portrait and desktop landscape) @@ -144,6 +143,18 @@ queries: { } ``` +## Other Webpack Plugins + +This plugin plays together well with the following other webpack plugins. + +### mini-css-extract-plugin + +If you don't want the CSS included in your JS but emit it as external files, you can use the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin). The media query plugin automatically recognizes the additional CSS chunks and even takes over the plugins filename option! + +### html-webpack-plugin + +If you're using the hash feature of webpack (e.g. `[name].[hash].js`) chances are high you're also using the [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) to inject the hashed files into your templates. Good news – the media query plugin supports it! It hooks into the plugin and makes sure the extracted files are available in your HTML template via `htmlWebpackPlugin.files.js` or `htmlWebpackPlugin.files.css`. + ## Not using webpack? This plugin is built for webpack only and can't be used with other module bundlers (such as [FuseBox](https://fuse-box.org/)) or task runners (such as [Gulp](https://gulpjs.com/)). However if you can't or don't want to use webpack but nevertheless want to extract media queries you should check out my [PostCSS plugin](https://github.com/SassNinja/postcss-extract-media-query) which supports much more tools. @@ -153,7 +164,7 @@ So it's highly recommended to use this webpack plugin instead of the PostCSS alt ## Contribution -This plugin has been built because I wasn't able to find a webpack solution for such a trivial task of loading media queries async. It works for my use cases by I'm pretty sure it can get more improved. So if you miss any feature don't hesitate to create an issue as feature request or to create a PR to do the job. +This plugin has been built because I wasn't able to find a webpack solution for such a trivial task of splitting files by media query and loading them async. It works for my use cases by I'm pretty sure it can get more improved. So if you miss any feature don't hesitate to create an issue as feature request or to create a PR to do the job. **And last but not least, if you like this plugin please give it a star on github and share it!**