# immutable-css
> A CSS linter for immutable selectors.
Latest version **1.1.2** (published 2016-06-03) · MIT license · 0 weekly downloads
## Install
```sh
npm install immutable-css
pnpm add immutable-css
yarn add immutable-css
bun add immutable-css
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.1.2 |
| Published | 2016-06-03 |
| First published | 2015-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| Author | John Otander |
| Maintainers | johno |
| Keywords | css, immutable, mutability, immutablecss, immutability, mutation, lint, linter |
## Links
- npm: https://www.npmjs.com/package/immutable-css
- Repository: https://github.com/johnotander/immutable-css
- Issues: https://github.com/johnotander/immutable-css/issues
- npm.io page: https://npm.io/package/immutable-css
## Dependencies (9)
- [glob](https://npm.io/package/glob.md) ^5.0.14
- [meow](https://npm.io/package/meow.md) ^3.3.0
- [is-css](https://npm.io/package/is-css.md) ^1.0.0
- [postcss](https://npm.io/package/postcss.md) ^5.0.10
- [file-exists](https://npm.io/package/file-exists.md) ^0.1.1
- [specificity](https://npm.io/package/specificity.md) ^0.1.4
- [extend-options](https://npm.io/package/extend-options.md) 0.0.1
- [get-css-classes](https://npm.io/package/get-css-classes.md) 1.1.0
- [has-class-selector](https://npm.io/package/has-class-selector.md) 1.0.0
## Alternatives
- [eslint-plugin-sonarjs](https://npm.io/package/eslint-plugin-sonarjs.md) — 2.9M weekly downloads
- [eslint-config-expo](https://npm.io/package/eslint-config-expo.md) — 1.5M weekly downloads
- [@matter/protocol](https://npm.io/package/@matter/protocol.md) — 63.5K weekly downloads
- [@eventcatalog/linter](https://npm.io/package/@eventcatalog/linter.md) — 24.8K weekly downloads
- [@inrupt/eslint-config-base](https://npm.io/package/@inrupt/eslint-config-base.md) — 4.5K weekly downloads
## Recent versions
- 1.1.2 (latest) — 2016-06-03
- 1.1.1 — 2016-02-19
- 1.1.0 — 2016-01-20
- 1.0.1 — 2015-10-26
- 1.0.0 — 2015-10-22
- 0.1.0 — 2015-08-21
- 0.0.3 — 2015-04-07
- 0.0.1 — 2015-03-25
## README
[](https://travis-ci.org/johnotander/immutable-css) [](https://github.com/feross/standard)
Best practices suggest avoiding overriding styles from vendor libraries to prevent unwanted side effects. Base library styles should not be altered – or as Harry Roberts describes, base styles should be treated as [Immutable CSS](http://csswizardry.com/2015/03/immutable-css/).
See the interactive [web app](http://immutablecss.com).
## Installation
```bash
npm install --save immutable-css
```
## Usage
`immutableCss.processFiles(immutableSourceCss, customCss, options)` takes two stylesheet paths, and ensures the custom CSS doesn't override any selectors contained within the immutable source.
This is typically best when comparing vendor CSS ([Bootstrap](http://getbootstrap.com), [Tachyons](http://tachyons.io), [Basscss](http://basscss.com), etc.) to your app's customizations.
```js
var immutableCss = require('immutable-css')
immutableCss.processFiles('css/vendor.css', 'css/app.css')
// => [...]
```
`immutableCss.processGlob(cssGlob, options)` takes a glob that matches CSS files and ensures that no stylesheet overrides selectors contained within another.
This is useful to ensure that CSS partials aren't mixing concerns by mutating selectors contained within another file.
```js
var immutableCss = require('immutable-css')
immutableCss.processGlob('src/css/**/*.css', { verbose: true })
```
### Using with [PostCSS](https://github.com/postcss/postcss)
Immutable CSS detects mutations among files by leveraging PostCSS sourcemaps. It is also best used as a PostCSS plugin in tandem with `postcss-import` and `postcss-reporter`.
```js
var fs = require('fs')
var postcss = require('postcss')
var import = require('postcss-import')
var reporter = require('postcss-reporter')
var immutableCss = require('immutable-css')
var css = fs.readFileSync('styles.css', 'utf8')
var mutations = postcss([import(), immutableCss(), reporter()])
.process(css, { from: 'styles.css' })
```
### Using with [Gulp](http://gulpjs.com)
```js
var gulp = require('gulp')
var postcss = require('gulp-postcss')
var import = require('postcss-import')
var reporter = require('postcss-reporter')
var immutableCss = require('immutable-css')
gulp.task('immutable', function () {
var processors = [
import,
immutableCss,
// If you want Immutable CSS to halt the gulp pipline if there are any warnings
// then set throwError to true
reporter({clearMessages: true, throwError: false})
]
gulp.src('assets/css/base.css')
.pipe(postcss(processors))
.pipe(gulp.dest('dist/css'))
})
```
#### Input
```css
@import 'basscss';
.button {}
.left {}
.something-else {}
```
#### Output
```sh
⚠ .button was mutated 2 times
[line 93, col 1]: /css/basscss.css
[line 3, col 1]: /css/custom.css
[immutable-css]
⚠ .left was mutated 2 times
[line 291, col 1]: /css/basscss.css
[line 4, col 1]: /css/custom.css
[immutable-css]
```
### Options
* `strict` (Boolean): Whether class mutations are allowed in the same file. Default: `false`.
* `ignoredClasses` (Array): List of classes to ignore for mutation violations.
Ex: `['.some-mutable-class']`
* `immutableClasses` (Array): List of classes to check against.
Ex: `['.button', '.foobar']`
* `immutablePrefixes` (Array): List of prefix regexes that are immutable.
Ex: `[/\.u\-/, /\.util\-/]`
* `callback` (Function): Callback that receives a mutations object.
Ex: `function (mutations) { console.log(mutations) }`
* `verbose` (Boolean): Whether mutations are logged (defaults to true with PostCSS).
#### Using the callback
Immutable CSS accepts an optional callback, which returns the mutations hash. The key is the mutated class name, the value is an array of mutating filenames.
```js
postcss([
import(),
immutableCss({ ignoredClasses: ['.button'] }, function(mutations) {
console.log(mutations)
// => { '.foobar': [] }
})
]).process(css, { from: cssFile })
```
### Using the [immutable-css-cli](https://github.com/johnotander/immutable-css-cli)
```sh
npm i -g immutable-css-cli
```
```sh
immutable-css css/main.css
⚠ .button was mutated 2 times
[line 93, col 1]: /css/_basscss.css
[line 11, col 1]: /css/_custom.css
[immutable-css]
⚠ .left was mutated 2 times
[line 291, col 1]: /css/_basscss.css
[line 15, col 1]: /css/_custom.css
[immutable-css]
```
## Dependencies
*
*
*
## Related Reading
*
*
*
*
*
## License
MIT
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
Crafted with <3 by [@jxnblk](https://twitter.com/jxnblk) & [@4lpine](https://twitter.com/4lpine).
***
> This package was initially generated with [yeoman](http://yeoman.io) and the [p generator](https://github.com/johnotander/generator-p.git).
---
_Source: https://npm.io/package/immutable-css · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._