cssstats

Visualize various stats about your CSS

Showing:

Popularity

Downloads/wk

6.5K

GitHub Stars

2.7K

Maintenance

Last Commit

7mos ago

Contributors

33

Package

Dependencies

18

Size (min+gzip)

80.9KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

cssstats

Parses stylesheets and returns an object with statistics. This is the core module used in cssstats.com

Installation

npm i --save cssstats

Usage

Node

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 plugin. The stats will be added to PostCSS's messages array.

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.

var stats = cssstats(css, { mediaQueries: false })
  • safe (boolean, default: true) - enables 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

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

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

Generate a specificity graph

var specificityGraph = stats.selectors.getSpecificityGraph()

Sort selectors by highest specificity

var sortedSelectors = stats.selectors.getSortedSpecificity()

Get total number of unique colors

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

display: none count

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial