Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
7 changed files
with
380 additions
and
232 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,14 +1,9 @@ | ||
sudo: false | ||
# https://docs.travis-ci.com/user/travis-lint | ||
|
||
language: node_js | ||
matrix: | ||
include: | ||
- node_js: '5' | ||
- node_js: '4' | ||
- node_js: '0.12' | ||
env: NO_ESLINT=true | ||
|
||
script: "[[ $NO_ESLINT == true ]] && npm run test-012 || npm test" | ||
node_js: | ||
- 4 | ||
|
||
after_success: | ||
- './node_modules/.bin/nyc report --reporter=text-lcov | ./node_modules/.bin/coveralls' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,132 +1,243 @@ | ||
# [postcss][postcss]-use [![Build Status](https://travis-ci.org/postcss/postcss-use.svg?branch=master)][ci] | ||
# PostCSS Use [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss] | ||
|
||
> Enable PostCSS plugins directly in your stylesheet. | ||
[![NPM Version][npm-img]][npm-url] | ||
[![Build Status][cli-img]][cli-url] | ||
[![Gitter Chat][git-img]][git-url] | ||
|
||
## Install | ||
[PostCSS Use] lets you require PostCSS plugins from within CSS. | ||
|
||
With [npm](https://npmjs.org/package/postcss-use) do: | ||
```css | ||
@use postcss-discard-comments; | ||
|
||
/* test */ | ||
|
||
h1 { | ||
color: red | ||
} | ||
|
||
/* becomes */ | ||
|
||
h1 { | ||
color: red | ||
} | ||
``` | ||
npm install postcss-use --save | ||
|
||
## Usage | ||
|
||
Add [PostCSS Use] to your build tool: | ||
|
||
```bash | ||
npm install postcss-use --save-dev | ||
``` | ||
|
||
## Example | ||
#### Node | ||
|
||
Both hash maps and arrays are supported; note that functions are not, for | ||
security reasons. A hash map uses the CSS format of | ||
`option: value; option2: value2`, but please note that *values* must be valid | ||
JSON syntax. For example if a module takes a string option, it must be wrapped | ||
in quotation marks. | ||
Use [PostCSS Use] to process your CSS: | ||
|
||
### Input | ||
```js | ||
import use from 'postcss-use'; | ||
|
||
#### Standard syntax | ||
use.process(YOUR_CSS); | ||
``` | ||
|
||
With [postcss-discard-comments]: | ||
#### PostCSS | ||
|
||
```css | ||
@use postcss-discard-comments(removeAll: true); | ||
/*! test */ | ||
h1 { | ||
color: red | ||
} | ||
Add [PostCSS] to your build tool: | ||
|
||
```bash | ||
npm install postcss --save-dev | ||
``` | ||
|
||
#### Alternative syntax | ||
Use [PostCSS Use] as a plugin: | ||
|
||
You may also use configuration blocks that are more *CSS-like*. Note that array | ||
options cannot be parsed by this method. | ||
```js | ||
import postcss from 'gulp-postcss'; | ||
import use from 'postcss-use'; | ||
|
||
```css | ||
@use postcss-discard-comments { | ||
removeAll: true | ||
} | ||
postcss([ | ||
use() | ||
]).process(YOUR_CSS); | ||
``` | ||
|
||
### Output | ||
#### Webpack | ||
|
||
```css | ||
h1 { | ||
color: red | ||
} | ||
Add [PostCSS Loader] to your build tool: | ||
|
||
```bash | ||
npm install postcss-loader --save-dev | ||
``` | ||
|
||
## API | ||
Add [PostCSS Use] to your `webpack.config.js`: | ||
|
||
### use(options) | ||
```js | ||
import use from 'postcss-use'; | ||
|
||
module.exports = { | ||
module: { | ||
rules: [ | ||
{ | ||
test: /\.css$/, | ||
use: [ | ||
'style-loader', | ||
{ loader: 'css-loader', options: { importLoaders: 1 } }, | ||
{ loader: 'postcss-loader', options: { plugins: () => [ use ] } } | ||
] | ||
} | ||
] | ||
} | ||
} | ||
``` | ||
|
||
#### options | ||
#### Gulp | ||
|
||
##### modules | ||
Add [Gulp PostCSS] to your build tool: | ||
|
||
Type: `array|string` | ||
*Required option*. | ||
```bash | ||
npm install gulp-postcss --save-dev | ||
``` | ||
|
||
You must specify this array of postcss plugins to use, for security purposes. | ||
This prevents malicious usage of postcss-use in browser environments. | ||
Add [PostCSS Use] to your Gulpfile: | ||
|
||
```js | ||
postcss([ use({ modules: ['autoprefixer', 'cssnano', 'cssnext']}) ]); | ||
import postcss from 'gulp-postcss'; | ||
import use from 'postcss-use'; | ||
|
||
gulp.task('css', () => gulp.src('./src/*.css').pipe( | ||
postcss([ | ||
use() | ||
]) | ||
).pipe( | ||
gulp.dest('.') | ||
)); | ||
``` | ||
|
||
Note that you may also set this option to `'*'` to disable whitelisting of | ||
modules. This is not recommended for environments where you may be accepting | ||
arbitrary user input; use at your own risk. | ||
#### Grunt | ||
|
||
##### resolveFromFile | ||
Add [Grunt PostCSS] to your build tool: | ||
|
||
Type: `boolean` (default: `false`) | ||
```bash | ||
npm install grunt-postcss --save-dev | ||
``` | ||
|
||
Set this to true in order to resolve plugins relative to the file that | ||
referenced them. This enables the usage of different versions of the same | ||
plugin, for instance. | ||
Add [PostCSS Use] to your Gruntfile: | ||
|
||
```js | ||
postcss([ use({ resolveFromFile: true, modules: '*' }) ]); | ||
import use from 'postcss-use'; | ||
|
||
grunt.loadNpmTasks('grunt-postcss'); | ||
|
||
grunt.initConfig({ | ||
postcss: { | ||
options: { | ||
use: [ | ||
use() | ||
] | ||
}, | ||
dist: { | ||
src: '*.css' | ||
} | ||
} | ||
}); | ||
``` | ||
|
||
##### options | ||
## Passing Options into Plugins | ||
|
||
Options may be passed into plugins as a JSON object, an array, a hash map, or | ||
as declarations. Hash maps will follow the format of | ||
`option: value, option2: value2`. | ||
|
||
```css | ||
/* the following examples are equivalent */ | ||
|
||
@use postcss-preset-env(removeAll: true); | ||
|
||
@use postcss-discard-comments(removeAll: true); | ||
|
||
Type: `object` (default: `{}`) | ||
@use postcss-discard-comments({ removeAll: true }); | ||
|
||
Default options for plugins, keyed by plugin name. If both the default and the specified options are objects, they are merged. Otherwise, the options specified in the CSS are used. | ||
@use postcss-discard-comments { removeAll: true } | ||
``` | ||
|
||
## Options | ||
|
||
### modules | ||
|
||
The `modules` option specifies a list of allowable PostCSS Plugins, expressed | ||
as a `String`, `Array`, or `RegExp`. By default, all plugins are disabled in | ||
order to prevent malicious usage in browser environments. | ||
|
||
```js | ||
postcss([ | ||
use({ | ||
modules: '*', | ||
options: { | ||
autoprefixer: { | ||
browsers: ['> 1%', 'IE 7'] | ||
} | ||
} | ||
}) | ||
]); | ||
use({ | ||
// allow plugins starting with autoprefixer, postcss, precss, and cssnano | ||
modules: [ | ||
/^autoprefixer/, | ||
/^postcss/, | ||
/^precss/, | ||
/^cssnano/ | ||
] | ||
}) | ||
``` | ||
|
||
## Usage | ||
```js | ||
use({ | ||
// allow autoprefixer, postcss-preset-env, and postcss-flexbugs-fixes | ||
modules: [ 'autoprefixer', 'postcss-preset-env', 'postcss-flexbugs-fixes' ] | ||
}) | ||
``` | ||
|
||
See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for | ||
examples for your environment. | ||
Setting the option to `"*"` will allow PostCSS Use to require any plugins. This | ||
is not recommended for environments where you may be accepting arbitrary user | ||
input; use at your own risk. | ||
|
||
## Contributors | ||
```js | ||
use({ | ||
// allow any plugin | ||
modules: '*' | ||
}) | ||
``` | ||
|
||
Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)): | ||
### resolveFromFile | ||
|
||
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> | ||
| [<img src="https://avatars.githubusercontent.com/u/1282980?v=3" width="100px;"/><br /><sub>Ben Briggs</sub>](http://beneb.info)<br />[💻](https://github.com/postcss/postcss-use/commits?author=ben-eb) [📖](https://github.com/postcss/postcss-use/commits?author=ben-eb) 👀 [⚠️](https://github.com/postcss/postcss-use/commits?author=ben-eb) | [<img src="https://avatars.githubusercontent.com/u/188426?v=3" width="100px;"/><br /><sub>Jonathan Neal</sub>](//jonathantneal.com)<br />[💻](https://github.com/postcss/postcss-use/commits?author=jonathantneal) [⚠️](https://github.com/postcss/postcss-use/commits?author=jonathantneal) | [<img src="https://avatars.githubusercontent.com/u/2784308?v=3" width="100px;"/><br /><sub>一丝</sub>](www.iyunlu.com/view)<br />[💻](https://github.com/postcss/postcss-use/commits?author=yisibl) | [<img src="https://avatars.githubusercontent.com/u/157534?v=3" width="100px;"/><br /><sub>Maxime Thirouin</sub>](https://moox.io/)<br />[📖](https://github.com/postcss/postcss-use/commits?author=MoOx) | [<img src="https://avatars.githubusercontent.com/u/5635476?v=3" width="100px;"/><br /><sub>Bogdan Chadkin</sub>](https://github.com/TrySound)<br />[📖](https://github.com/postcss/postcss-use/commits?author=TrySound) 👀 | [<img src="https://avatars.githubusercontent.com/u/48200?v=3" width="100px;"/><br /><sub>Espen Hovlandsdal</sub>](https://espen.codes/)<br />[💻](https://github.com/postcss/postcss-use/commits?author=rexxars) [⚠️](https://github.com/postcss/postcss-use/commits?author=rexxars) | [<img src="https://avatars.githubusercontent.com/u/19343?v=3" width="100px;"/><br /><sub>Andrey Sitnik</sub>](http://sitnik.ru)<br />👀 | | ||
| :---: | :---: | :---: | :---: | :---: | :---: | :---: | | ||
<!-- ALL-CONTRIBUTORS-LIST:END --> | ||
The `resolveFromFile` option specifies whether plugins should be resolved | ||
relative to the file that referenced them. This may be used to enable the usage | ||
of different versions of the same plugin. By default, it is disabled. | ||
|
||
This project follows the [all-contributors] specification. Contributions of | ||
any kind welcome! | ||
```js | ||
use({ | ||
resolveFromFile: true | ||
}) | ||
``` | ||
|
||
## License | ||
### options | ||
|
||
MIT © [Ben Briggs](http://beneb.info) | ||
The `options` option specifies individual options for specific plugins by | ||
plugin name. | ||
|
||
```js | ||
use({ | ||
options: { | ||
'postcss-preset-env': { | ||
stage: 0, | ||
browsers: 'last two versions' | ||
} | ||
} | ||
}) | ||
``` | ||
|
||
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> | ||
| [<img src="https://avatars.githubusercontent.com/u/1282980?v=3" width="100px;"/><br /><sub>Ben Briggs</sub>](http://beneb.info)<br />[💻](https://github.com/postcss/postcss-use/commits?author=ben-eb) [📖](https://github.com/postcss/postcss-use/commits?author=ben-eb) 👀 [⚠️](https://github.com/postcss/postcss-use/commits?author=ben-eb) | [<img src="https://avatars.githubusercontent.com/u/188426?v=3" width="100px;"/><br /><sub>Jonathan Neal</sub>](//jonathantneal.com)<br />[💻](https://github.com/postcss/postcss-use/commits?author=jonathantneal) [⚠️](https://github.com/postcss/postcss-use/commits?author=jonathantneal) | [<img src="https://avatars.githubusercontent.com/u/2784308?v=3" width="100px;"/><br /><sub>一丝</sub>](www.iyunlu.com/view)<br />[💻](https://github.com/postcss/postcss-use/commits?author=yisibl) | [<img src="https://avatars.githubusercontent.com/u/157534?v=3" width="100px;"/><br /><sub>Maxime Thirouin</sub>](https://moox.io/)<br />[📖](https://github.com/postcss/postcss-use/commits?author=MoOx) | [<img src="https://avatars.githubusercontent.com/u/5635476?v=3" width="100px;"/><br /><sub>Bogdan Chadkin</sub>](https://github.com/TrySound)<br />[📖](https://github.com/postcss/postcss-use/commits?author=TrySound) 👀 | [<img src="https://avatars.githubusercontent.com/u/48200?v=3" width="100px;"/><br /><sub>Espen Hovlandsdal</sub>](https://espen.codes/)<br />[💻](https://github.com/postcss/postcss-use/commits?author=rexxars) [⚠️](https://github.com/postcss/postcss-use/commits?author=rexxars) | [<img src="https://avatars.githubusercontent.com/u/19343?v=3" width="100px;"/><br /><sub>Andrey Sitnik</sub>](http://sitnik.ru)<br />👀 | | ||
| :---: | :---: | :---: | :---: | :---: | :---: | :---: | | ||
<!-- ALL-CONTRIBUTORS-LIST:END --> | ||
|
||
[all-contributors]: https://github.com/kentcdodds/all-contributors | ||
[ci]: https://travis-ci.org/postcss/postcss-use | ||
[postcss]: https://github.com/postcss/postcss | ||
[postcss-discard-comments]: https://github.com/ben-eb/postcss-discard-comments | ||
[npm-url]: https://www.npmjs.com/package/postcss-use | ||
[npm-img]: https://img.shields.io/npm/v/postcss-use.svg | ||
[cli-url]: https://travis-ci.org/postcss/postcss-use | ||
[cli-img]: https://img.shields.io/travis/postcss/postcss-use/master.svg | ||
[git-url]: https://gitter.im/postcss/postcss | ||
[git-img]: https://img.shields.io/badge/chat-gitter-blue.svg | ||
|
||
[PostCSS]: https://github.com/postcss/postcss | ||
[PostCSS Use]: https://github.com/postcss/postcss-use | ||
[PostCSS Loader]: https://github.com/postcss/postcss-loader | ||
[Gulp PostCSS]: https://github.com/postcss/gulp-postcss | ||
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss |
Oops, something went wrong.