1.2.0 • Published 12 months ago

trapcss v1.2.0

Weekly downloads
4
License
AGPL-3.0
Repository
github
Last release
12 months ago

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.

NameTypeDescriptionDefault
html*stringThe input HTML.-
css*stringThe CSS to drop selectors from.-
keepAlternatebooleanWhether to keep the @alternate comment forClosure Stylesheets.false
shouldDrop(sel: string) => booleanWhether 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.

NameTypeDescription
css*stringThe 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.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.

1.2.0

12 months ago

0.0.0-pre

1 year ago

1.1.0

1 year ago

1.0.0

1 year ago