# purgecss-custom-extractor

> Tool to create a custom extractor for Purgecss

Latest version **0.2.4** (published 2018-07-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install purgecss-custom-extractor
pnpm add purgecss-custom-extractor
yarn add purgecss-custom-extractor
bun add purgecss-custom-extractor
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.4 |
| Published | 2018-07-15 |
| First published | 2018-07-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 13.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | n1kk |
| Maintainers | n1kk |
| Keywords | purgecss, purge css, extractor, custom extractor, plugin, css |

## Links

- npm: https://www.npmjs.com/package/purgecss-custom-extractor
- Repository: https://github.com/n1kk/purgecss-custom-extractor
- Homepage: https://github.com/n1kk/purgecss-custom-extractor#readme
- Issues: https://github.com/n1kk/purgecss-custom-extractor/issues
- npm.io page: https://npm.io/package/purgecss-custom-extractor

## Dependencies (1)

- [html-tags](https://npm.io/package/html-tags.md) ^2.0.0

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 0.2.4 (latest) — 2018-07-15
- 0.2.3 — 2018-07-14
- 0.2.2 — 2018-07-14
- 0.2.1 — 2018-07-14
- 0.1.5 — 2018-07-13
- 0.1.4 — 2018-07-13
- 0.1.3 — 2018-07-13
- 0.1.2 — 2018-07-13
- 0.1.1 — 2018-07-12
- 0.1.0 — 2018-07-12

## README

A tool to easily create custom extractors for [purgecss](https://github.com/FullHuman/purgecss).

- [Install](#install)
- [Usage](#usage)
- [API](#api)

## Install
```bash
npm i purgecss-custom-extractor
```

## Usage
Accepts regex as a RegExp or a string with it (`'\w+'`, `'/\w+/g'`)
First argument can be a regex or an array of regex and match processor or a list with a mix of both.
```javascript
const purgeCss = new Purgecss({
  content: ['**/*.html'],
  css: ['**/*.css'],
  extractors: [{
      // 'g' flag will be enforced.
      extractor: Extractor.custom(/[a-zA-Z0-9\-_]+/),
      extensions: ['html']
    }]
})
```

By default purgecss treats every word in text as potential selector. But what if you're using some selectors that contain a non standard characters, like in [TailwindCSS](https://tailwindcss.com/) framework (`w-1/2`, `hover:bg-blue`). Or your code contains a lot of static text, then you can get lots of selectors you don't really use. You can create a simple regular expression to only keep selectors that are mentioned in `class` attribute of html tags. If you pass an array of `[regex, matchProcessor]` then each match will go through that passed function.

```javascript
// getting all the tags with class attribute
// taking first group in each match that contains
// class list and splitting it by ' '
Extractor.custom([ /<[\w]+.*?class="(.*?)".*?>/mg, m => m[1].split(' ') ])
```

If you want you can get rid of html comments `<!-- -->` to ignore class names in commented code. To do this you can define `contentProcessor` and remove html comments before looking for matches.

```javascript
// Extractor.regex.comment() == /<!--([\s\S]*?)-->/mg
Extractor.custom({
  regex: [ /<[\w]+.*?class="(.*?)".*?>/mg, m => m[1].split(' ') ],
  contentProcessor: c => c.replace(Extractor.regex.comment(), '')
})
```

You can also trim text to a content of a specific html tag. This also can be useful when working with VueJS single file components, you can isolate `<template>` tag and look for matches only there.

```javascript
Extractor.custom({
  regex: [ /<[\w]+.*?class="(.*?)".*?>/mg, m => m[1].split(' ') ],
  contentProcessor: content => {
    // generate regexp for lazy template tag
    let regex = Extractor.regex.lazyTag('template')
    let match = regex.exec(content)
    // if match found use second group for tags content
    // for reference see api -> regex
    let res = match ? match[2] : content
    return res
  }
})
```

## API

#### `custom(regex | {regex, matchProcessor, contentProcessor})`
Function to create custom extractor

First argument can be either of these: 
- `regex`: a regex, array of regex and match processor or a mixed list of both
  ```javascript
  custom(regex);
  custom([regex, eachMatch]);
  custom([
    [regex, eachMatch],
    [regex],
    regex
  ]);
  custom({regex, matchProcessor, contentProcessor});
  ```
- `opts`: object with options:
  - `regex`: see above
  - _`matchProcessor`_: [optional] will receive result of each match and will return processed value, can return string or array of strings (`m => m[1]`)
  - _`contentProcessor`_: [optional] will receive content before looking for matches (`c => c.toLowerCase()`)
  - __`returns`__: extractor object for purgecss

### `matchAll(re, text, matchProcessor)`
Function to get all the matches from given string

- `re`: RegExp or string with it (`'\w+'`, `'/\w+/g'`)
- `text`: text to match in
- _`matchProcessor`_: [optional] will receive result of each match and will return processed value, can return string or array of strings (`m => m[1]`)
- __`returns`__: array of all the matched strings

### `regex`
Object containing methods to create predefined regular expressions.

- `simple()`: returns regex for simple css selector (`/[a-zA-Z0-9\-_]+/g`) </br>
- `extended()`: returns regex for css selector with `:` and `\` characters (`/[a-zA-Z0-9\-_:\/]+/g`) such css selectors are being used in some frameworks, like [TailwindCSS](https://tailwindcss.com/)</br>
- `lazyTag(tagName)`: returns regex to match multiline html tag with it's content (`/<div(.*?)>([\s\S]*?)<\/divs*>/mg`) group 1 - attributes, group 2 - content</br>
- `greedyTag(tagName)`: same as above but greedy for content group (`/<div(.*?)>([\s\S]*)<\/divs*>/mg`) </br>
- `comment()`: returns regex to match html comments (`/<!--([\s\S]*?)-->/mg`) </br>

### `whitelist`
Object containing whitelist presets

- `htmltags`: array of html tag names </br>

### `simple()`
Predefined Extractor with regex.simple().
```javascript
() => custom({regex: regex.simple()})
```

### `extended()`
Predefined Extractor with regex.extended().
```javascript
() => custom({regex: regex.extended()})
```

---
_Source: https://npm.io/package/purgecss-custom-extractor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._