Skip to content

Latest commit

 

History

History
262 lines (206 loc) · 8.45 KB

README.md

File metadata and controls

262 lines (206 loc) · 8.45 KB
Raw

trapcss

npm version

trapcss removes unused selectors from CSS files to achieve maximum optimisation. Can be used as an API function or with CLI.

It is a fork which is "An exceptionally fast, thorough and tiny unused-CSS cleaner", but has a binary and has been optimised with Closure Compiler.

yarn add trapcss
npm install -D trapcss

Introduction

TrapCSS takes your HTML and CSS as input and returns only the used CSS as output. Its custom HTML and CSS parsers are highly optimized for the 99% use case and thus avoid the overhead of handling malformed markup or stylesheets, so well-formed input is required. There is minimal handling for complex escaping rules, so there will always exist cases of valid input that cannot be processed by TrapCSS; for these infrequent cases, please start a discussion. While the HTML spec allows html, head, body and tbody to be implied/omitted, TrapCSS makes no such assumptions; selectors will only be retained for tags that can be parsed from provided markup.

It's also a good idea to run your CSS through a structural optimizer like clean-css, csso, cssnano or crass to re-group selectors, merge redundant rules, etc. It probably makes sense to do this after TrapCSS, which can leave redundant blocks, e.g. .foo, .bar { color: red; } .bar { width: 50%; } -> .bar { color: red; } .bar { width: 50%; } if .foo is absent from your markup.

More on this project's backstory & discussions: v0.1.0 alpha: /r/javascript, Hacker News and v1.0.0 release: /r/javascript.

📙 READ WIKI PAGES

Table Of Contents

API

The package is available by importing its default function:

import trapcss from 'trapcss'

trapcss(
  config: Config,
): Return

Parses the supplied HTML and CSS and removes unused selectors. Also removes empty CSS rules.

  • config* Config: The options for TrapCSS.

Config: Options for the program.

Name Type Description Default
html* string The input HTML. -
css* string The CSS to drop selectors from. -
keepAlternate boolean Whether to keep the @alternate comment for
Closure Stylesheets.		 false
shouldDrop (sel: string) => boolean Whether TrapCSS should remove this selector.
The shouldDrop hook is called for every CSS selector
that could not be matched in the html. Return false
to retain the selector or true to drop it.		 -

Return: Return Type.

Name Type Description
css* string The dropped CSS.
sels* !Set<string> The used selectors. 
import trapcss from 'trapcss'

let html = `
    <html>
        <head></head>
        <body>
            <p>Hello World!</p>
        </body>
    </html>
`

let css = `
    html {
      background: yellow;
      /* @alternate */
      background: green;
    }
    .card {
      padding: 8px;
    }
    p:hover a:first-child {
      color: red;
    }
`

const whitelist = /#foo|\.bar/

let dropped = new Set()

let cleaned = trapcss({
  html,
  css,
  shouldDrop(sel) {
    if (whitelist.test(sel))
      return false
    else {
      dropped.add(sel)
      return true
    }
  },
})

console.log(cleaned.css)

console.error(dropped)
html{background: yellow;background: green;}
Set { '.card', 'p:hover a:first-child' }

CLI

The package can also be used from the CLI.

Argument Short Description
input The HTML files to read.
--css -c The CSS file to drop selectors from.
--output -o The destination where to save output. If not passed, prints to stdout.
--help -h Print the help information and exit.
--version -v Show the version's number and exit.

For example, having these two files, we can use trapcss from the command line:

HTML file CSS file 
<html>
  <head>
    <title>TrapCSS ftw</title>
  </head>
  <body>
      <p>Hello World!</p>
  </body>
</html>
 
html {
  background: yellow;
  /* @alternate */
  background: green;
}
.card {
  padding: 8px;
}
p:hover a:first-child {
  color: red;
}
 
trapcss:~$ trapcss example/cli/index.html -c example/cli/style.css
html{background: yellow;background: green;}

The help can be accessed with the -h command:

Remove unused CSS

  trapcss input.html[,n.html,...] -c style.css [-o output] [-hv]

	input        	The HTML files to read.
	--css, -c    	The CSS file to drop selectors from.
	--output, -o 	The destination where to save output.
	             	If not passed, prints to stdout.
	--help, -h   	Print the help information and exit.
	--version, -v	Show the version's number and exit.

  Example:

    trapcss index.html example.html -c style.css -o style-dropped.css

Copyright & License

GNU Affero General Public License v3.0

Original work on DropCSS package by Leon Sorokin under MIT license found in COPYING.

artdecocode © Art Deco™ 2020