trapcss
v1.2.0
Published
Removes unused selectors from CSS files to achieve maximum optimisation. Can be used as an API function or with CLI.
Downloads
5
Readme
trapcss
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 trapcssIntroduction
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.
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 forClosure Stylesheets. | false |
| shouldDrop | (sel: string) => boolean | Whether TrapCSS should remove this selector.The shouldDrop hook is called for every CSS selectorthat could not be matched in the html. Return falseto 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.
For example, having these two files, we can use trapcss from the command line:
<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.csshtml{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.cssCopyright & License
GNU Affero General Public License v3.0
Original work on DropCSS package by Leon Sorokin under MIT license found in COPYING.