Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
Due to the rework of the plugin component and the latest support of other plugins, the readme needed some update.
  • Loading branch information
SassNinja committed Jun 29, 2018
1 parent 751fe2b commit 3cb64cc
Showing 1 changed file with 26 additions and 15 deletions.
41 changes: 26 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -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!

Expand Down Expand Up @@ -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.

Expand All @@ -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');
Expand All @@ -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)

Expand All @@ -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.
Expand All @@ -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!**

0 comments on commit 3cb64cc

Please sign in to comment.