https://github.com/artdecocode/trapcss
Removes unused selectors from CSS files to achieve maximum optimisation. Can be used as an API function or with CLI.
https://github.com/artdecocode/trapcss
browser css minifier web
Last synced: 11 months ago
JSON representation
Removes unused selectors from CSS files to achieve maximum optimisation. Can be used as an API function or with CLI.
- Host: GitHub
- URL: https://github.com/artdecocode/trapcss
- Owner: artdecocode
- License: agpl-3.0
- Created: 2020-01-29T13:48:22.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-05-30T01:40:12.000Z (about 5 years ago)
- Last Synced: 2025-07-01T01:07:28.770Z (12 months ago)
- Topics: browser, css, minifier, web
- Language: HTML
- Homepage: https://art-deco.github.io/trapcss
- Size: 453 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: COPYING
Awesome Lists containing this project
README
# trapcss
[](https://www.npmjs.com/package/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](https://github.com/leeoniya/dropcss) which is _"An exceptionally fast, thorough and tiny unused-CSS cleaner"_, but has a binary and has been optimised with Closure Compiler.
```sh
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](https://github.com/leeoniya/dropcss/issues). 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](https://github.com/jakubpawlowicz/clean-css), [csso](https://github.com/css/csso), [cssnano](https://github.com/cssnano/cssnano) or [crass](https://github.com/mattbasta/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](https://old.reddit.com/r/javascript/comments/b3mcu8/dropcss_010_a_minimal_and_thorough_unused_css/), [Hacker News](https://news.ycombinator.com/item?id=19469080) and v1.0.0 release: [/r/javascript](https://old.reddit.com/r/javascript/comments/bb7im2/dropcss_v100_an_exceptionally_fast_thorough_and/).
📙 [READ WIKI PAGES](../../wiki)
## Table Of Contents
- [Introduction](#introduction)
- [Table Of Contents](#table-of-contents)
- [API](#api)
- [`trapcss(config: Config): Return`](#trapcssconfig-config-return)
* [`Config`](#type-config)
* [`Return`](#type-return)
- [CLI](#cli)
- [Copyright & License](#copyright--license)
## API
The package is available by importing its default function:
```js
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. |
```js
import trapcss from 'trapcss'
let html = `
Hello World!
`
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)
```
```css
html{background: yellow;background: green;}
```
```js
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
TrapCSS ftw
Hello World!
```
```css
html {
background: yellow;
/* @alternate */
background: green;
}
.card {
padding: 8px;
}
p:hover a:first-child {
color: red;
}
```
```console
trapcss:~$ trapcss example/cli/index.html -c example/cli/style.css
```
```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_](https://github.com/leeoniya/dropcss) package
by [Leon Sorokin](https://github.com/leeoniya) under MIT license found in [COPYING](COPYING).
© Art Deco™ 2020
