# cssstats

> High-level stats for stylesheets

Latest version **4.0.5** (published 2022-04-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install cssstats
pnpm add cssstats
yarn add cssstats
bun add cssstats
```

## 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 | 4.0.5 |
| Published | 2022-04-05 |
| First published | 2014-12-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 18 |
| Unpacked size | 2.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2814 |
| Author | Brent Jackson |
| Maintainers | johno, jxnblk |
| Keywords | CSS, Performance, Stats, cssstats |

## Links

- npm: https://www.npmjs.com/package/cssstats
- Repository: https://github.com/cssstats/cssstats
- Homepage: https://github.com/cssstats/cssstats#readme
- Issues: https://github.com/cssstats/cssstats/issues
- npm.io page: https://npm.io/package/cssstats

## Dependencies (18)

- [bytes](https://npm.io/package/bytes.md) ^3.1.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.20
- [postcss](https://npm.io/package/postcss.md) ^8.1.4
- [is-blank](https://npm.io/package/is-blank.md) ^2.1.0
- [gzip-size](https://npm.io/package/gzip-size.md) ^6.0.0
- [is-present](https://npm.io/package/is-present.md) ^1.0.0
- [specificity](https://npm.io/package/specificity.md) ^0.4.1
- [has-id-selector](https://npm.io/package/has-id-selector.md) ^4.0.0
- [has-pseudo-class](https://npm.io/package/has-pseudo-class.md) ^4.0.0
- [is-css-shorthand](https://npm.io/package/is-css-shorthand.md) ^1.0.1
- [has-class-selector](https://npm.io/package/has-class-selector.md) ^4.0.0
- [has-pseudo-element](https://npm.io/package/has-pseudo-element.md) ^4.0.0
- [is-vendor-prefixed](https://npm.io/package/is-vendor-prefixed.md) ^4.0.0
- [postcss-safe-parser](https://npm.io/package/postcss-safe-parser.md) ^5.0.2
- [css-shorthand-expand](https://npm.io/package/css-shorthand-expand.md) ^1.2.0
- [has-element-selector](https://npm.io/package/has-element-selector.md) ^4.0.0
- [css-selector-tokenizer](https://npm.io/package/css-selector-tokenizer.md) ^0.7.3
- [postcss-custom-properties](https://npm.io/package/postcss-custom-properties.md) ^12.1.6

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 4.0.5 (latest) — 2022-04-05
- 2.0.0-beta.4 (beta) — 2015-08-05
- 4.0.2 — 2021-02-24
- 4.0.1 — 2021-02-24
- 4.0.0 — 2020-12-08
- 3.5.0 — 2020-11-03
- 3.4.1 — 2020-02-18
- 3.4.0 — 2019-09-02
- 3.3.1 — 2019-07-26
- 3.3.0 — 2019-03-23
- 3.2.0 — 2018-01-23
- 3.1.0 — 2017-07-03
- 3.0.0 — 2016-11-11
- 3.0.0-beta.2 — 2016-08-26
- 3.0.0-beta.1 — 2016-04-22
- … 24 more at https://npm.io/package/cssstats/versions

## README

# cssstats

Parses stylesheets and returns an object with statistics.
This is the core module used in [cssstats.com](http://cssstats.com)

## Installation

```sh
npm i --save cssstats
```

## Usage

### Node

```js
var fs = require('fs')
var cssstats = require('cssstats')

var css = fs.readFileSync('./styles.css', 'utf8')
var stats = cssstats(css)
```

### PostCSS Plugin

CSS Stats can be used as a [PostCSS](https://github.com/postcss/postcss) plugin.
The stats will be added to PostCSS's messages array.

```js
var fs = require('fs')
var postcss = require('postcss')
var cssstats = require('cssstats')

var css = fs.readFileSync('./styles.css', 'utf8')
postcss()
  .use(cssstats())
  .process(css)
  .then(function (result) {
    result.messages.forEach(function (message) {
      console.log(message)
    })
  })
```

#### Options

Options may be passed as a second argument.

```js
var stats = cssstats(css, { mediaQueries: false })
```

- `safe` (boolean, default: `true`) - enables [PostCSS safe mode](https://github.com/postcss/postcss#safe-mode) for parsing CSS with syntax errors
- `mediaQueries` (boolean, default `true`) - determines whether or not to generate stats for each media query block
- `importantDeclarations` (boolean, default `false`) - include an array of declarations with `!important`

The following options add the results of helper methods to the returned object. This is helpful when using `JSON.stringify()`.

- `specificityGraph` (boolean, default `false`)
- `sortedSpecificityGraph` (boolean, default `false`)
- `repeatedSelectors` (boolean, default `false`)
- `propertyResets` (boolean, default `false`)
- `vendorPrefixedProperties` (boolean, default `false`)

### Returned Object

```js
// Example
{
  size: n,
  gzipSize: n,
  rules: {
    total: n,
    size: {
      graph: [n],
      max: n,
      average: n
    }
  },
  selectors: {
    total: n,
    id: n,
    class: n,
    type: n,
    pseudoClass: n,
    psuedoElement: n,
    values: [str],
    specificity: {
      max: n
      average: n
    },
    getSpecificityGraph(),
    getSpecificityValues(),
    getRepeatedValues(),
    getSortedSpecificity()
  },
  declarations: {
    total: n,
    unique: n,
    uniqueToTotalRatio: n,
    important: [obj],
    properties:
      prop: [str]
    },
    getPropertyResets(),
    getUniquePropertyCount(),
    getPropertyValueCount(),
    getVendorPrefixed(),
    getAllFontSizes(),
    getAllFontFamilies(),
  },
  mediaQueries: {
    total: n,
    unique: n,
    values: [str],
    contents: [
      {
        value: str,
        rules: {
          total: n,
          size: {
            graph: [n],
            max: n,
            average: n
          }
        },
        selectors: {
          total: n,
          id: n,
          class: n,
          type: n,
          pseudoClass: n,
          pseudoElement: n,
          values: [str],
          specificity: {
            max: n,
            average: n
          }
        },
        declarations: {
          total: n,
          unique: n,
          important: [obj],
          vendorPrefix: n,
          properties: {
            prop: [str]
          }
        }
      }
    ]
  }
}
```

#### `size` number

The size of the file in bytes

#### `gzipSize` number

The size of the stylesheet gzipped in bytes

#### `rules` object

- `total` number - total number of rules
- `size` object
  - `size.graph` array - ruleset sizes (number of declarations per rule) in source order
  - `size.max` number - maximum ruleset size
  - `size.average` number - average ruleset size

#### `selectors` object

- `total` number - total number of selectors
- `type` number - total number of type selectors
- `class` number - total number of class selectors
- `id` number - total number of id selectors
- `pseudoClass` number - total number of pseudo class selectors
- `pseudoElement` number - total number of pseudo element selectors
- `values` array - array of strings for all selectors
- `specificity` object
  - `specificity.max` number - maximum specificity as a base 10 number
  - `specificity.average` number - average specificity as a base 10 number
- `getSpecificityGraph()` function - returns an array of numbers for each selector’s specificity as a base 10 number
- `getSpecificityValues()` function - returns an array of selectors with base 10 specificity score in order
- `getRepeatedValues()` function - returns an array of strings of repeated selectors
- `getSortedSpecificity()` function - returns an array of selectors with base 10 specificity score, sorted from highest to lowest

#### `declarations` object

- `total` number - total number of declarations
- `unique` number - total unique declarations
- `uniqueToTotalRatio` number - ratio of unique declarations to total declarations
- `properties` object - object with each unique property and an array of that property’s values
- `getPropertyResets()` function - returns an object with the number of times margin or padding is reset for each property
- `getUniquePropertyCount(property)` function - returns the number of unique values for the given property
- `getPropertyValueCount(property, value)` function - returns the number of times a declaration occurs for the given property and value
- `getVendorPrefixed()` function - returns an array of declarations with vendor prefixed properties
- `getAllFontSizes()` function - returns an array of font sizes from both `font-size` and `font` shorthand declarations
- `getAllFontFamilies()` function - returns an array of font families from both `font-family` and `font` shorthand declarations
- `important` array (optional) - `!important` declaration objects with `property` and `value`

#### `mediaQueries` object

- `total` number - total number of media queries
- `unique` number - total unique media queries
- `values` array - array of values for each media query
- `contents` array - array of media query blocks with full stats object for each

See the `/test/results` folder for example JSON results.

### Usage examples

```js
var cssstats = require('cssstats')
var stats = cssstats(css)
```

#### Generate a [specificity graph](http://csswizardry.com/2014/10/the-specificity-graph/)

```js
var specificityGraph = stats.selectors.getSpecificityGraph()
```

#### Sort selectors by highest specificity

```js
var sortedSelectors = stats.selectors.getSortedSpecificity()
```

#### Get total number of unique colors

```js
var uniqueColorsCount = stats.declarations.getUniquePropertyCount('color')
```

#### `display: none` count

```js
var displayNoneCount = stats.declarations.getPropertyValueCount(
  'display',
  'none'
)
```

## 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

---
_Source: https://npm.io/package/cssstats · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._