160 lines
8.4 KiB
Markdown
160 lines
8.4 KiB
Markdown
|
# minify-html-literals
|
||
|
|
|
||
|
|
_Minify HTML markup inside JavaScript template literal strings._
|
||
|
|
|
||
|
|
[](https://www.npmjs.com/package/minify-html-literals)
|
||
|
|
[](https://travis-ci.com/asyncLiz/minify-html-literals)
|
||
|
|
[](https://coveralls.io/github/asyncLiz/minify-html-literals?branch=master)
|
||
|
|
|
||
|
|
## Why?
|
||
|
|
|
||
|
|
Template literals are often used in JavaScript to write HTML and CSS markup (ex. [lit-html](https://www.npmjs.com/package/lit-html)). This library allows a developer to minify markup that is normally ignored by JavaScript minifiers.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { minifyHTMLLiterals } from 'minify-html-literals';
|
||
|
|
// const minifyHTMLLiterals = require('minify-html-literals').minifyHTMLLiterals
|
||
|
|
|
||
|
|
const result = minifyHTMLLiterals(
|
||
|
|
`function render(title, items) {
|
||
|
|
return html\`
|
||
|
|
<style>
|
||
|
|
.heading {
|
||
|
|
color: blue;
|
||
|
|
}
|
||
|
|
</style>
|
||
|
|
<h1 class="heading">\${title}</h1>
|
||
|
|
<ul>
|
||
|
|
\${items.map(item => {
|
||
|
|
return getHTML()\`
|
||
|
|
<li>\${item}</li>
|
||
|
|
\`;
|
||
|
|
})}
|
||
|
|
</ul>
|
||
|
|
\`;
|
||
|
|
}`,
|
||
|
|
{
|
||
|
|
fileName: 'render.js'
|
||
|
|
}
|
||
|
|
);
|
||
|
|
|
||
|
|
console.log(result.code);
|
||
|
|
// function render(title, items) {
|
||
|
|
// return html`<style>.heading{color:#00f}</style><h1 class=heading>${title}</h1><ul>${items.map(item => {
|
||
|
|
// return getHTML()`<li>${item}</li>`;
|
||
|
|
// })}</ul>`;
|
||
|
|
// }
|
||
|
|
|
||
|
|
console.log(result.map);
|
||
|
|
// {
|
||
|
|
// "version": 3,
|
||
|
|
// "file": "render.js.map",
|
||
|
|
// "sources": ["render.js"],
|
||
|
|
// "sourcesContent": [null],
|
||
|
|
// "names": [],
|
||
|
|
// "mappings": "AAAA;gBACgB,qDAMU,QAAQ,SAE1B;2BACmB,IACX,OAAO,KACb;WACC,KAEP;"
|
||
|
|
// }
|
||
|
|
```
|
||
|
|
|
||
|
|
### ES5 Transpiling Warning
|
||
|
|
|
||
|
|
Be sure to minify template literals _before_ transpiling to ES5. Otherwise, the API will not be able to find any template literal (`` `${}` ``) strings.
|
||
|
|
|
||
|
|
## Supported Source Syntax
|
||
|
|
|
||
|
|
- JavaScript
|
||
|
|
- TypeScript
|
||
|
|
|
||
|
|
## Options
|
||
|
|
|
||
|
|
### Basic
|
||
|
|
|
||
|
|
The following options are common to typical use cases.
|
||
|
|
|
||
|
|
| Property | Type | Default | Description |
|
||
|
|
| --------------------------- | -------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
|
| `fileName` | string | | _Required._ The name of the file, used for syntax parsing and source maps. |
|
||
|
|
| `minifyOptions?` | [html-minifier options](https://www.npmjs.com/package/html-minifier#options-quick-reference) | `defaultMinifyOptions` | Defaults to production-ready minification. |
|
||
|
|
| `minifyOptions?.minifyCSS?` | [clean-css options](https://www.npmjs.com/package/clean-css#constructor-options) | `defaultMinifyCSSOptions` | Uses clean-css defaults. |
|
||
|
|
| `shouldMinify?` | function | `defaultShouldMinify` | A function that determines whether or not an HTML template should be minified. Defaults to minify all tagged templates whose tag name contains "html" (case insensitive). |
|
||
|
|
| `shouldMinifyCSS?` | function | `defaultShouldMinifyCSS` | A function that determines whether or not a CSS template should be minified. Defaults to minify all tagged templates whose tag name contains "css" (case insensitive). |
|
||
|
|
|
||
|
|
### Advanced
|
||
|
|
|
||
|
|
All aspects of the API are exposed and customizable. The following options will not typically be used unless you need to change how a certain aspect of the API handles a use case.
|
||
|
|
|
||
|
|
| Property | Type | Default | Description |
|
||
|
|
| ----------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
|
| `generateSourceMap?` | boolean or `(ms: MagicString, fileName: string) => SourceMap | undefined` | `defaultGenerateSourceMap` | Set to `false` to disable source maps, or a custom function to control how source maps are generated from a `MagicString` instance. |
|
||
|
|
| `strategy?` | object | `defaultStrategy` | An object with methods defining how to minify HTML. The default strategy uses [html-minifier](https://www.npmjs.com/package/html-minifier). |
|
||
|
|
| `validate?` | boolean or object | `defaultValidation` | Set to `false` to disable strategy validation checks, or to a custom set of validation functions. This is only useful when implementing a custom strategy. |
|
||
|
|
| `parseLiterals?` | function | [parse-literals](https://www.npmjs.com/package/parse-literals) | Override the function used to parse template literals from a source string. |
|
||
|
|
| `parseLiteralsOptions?` | object | | Additional options to pass to `parseLiterals()` |
|
||
|
|
| `MagicString?` | function | [MagicString](https://www.npmjs.com/package/magic-string) | Override the MagicString-like constructor to use for manipulating the source string and generating source maps. |
|
||
|
|
|
||
|
|
## Customization Examples
|
||
|
|
|
||
|
|
### Minify non-tagged templates
|
||
|
|
|
||
|
|
> This is particularly useful for libraries that define templates without using tags, such as Polymer's `<dom-module>`.
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { minifyHTMLLiterals, defaultShouldMinify } from 'minify-html-literals';
|
||
|
|
|
||
|
|
minifyHTMLLiterals(
|
||
|
|
`
|
||
|
|
template.innerHTML = \`
|
||
|
|
<dom-module id="custom-styles">
|
||
|
|
<style>
|
||
|
|
html {
|
||
|
|
--custom-color: blue;
|
||
|
|
}
|
||
|
|
</style>
|
||
|
|
</dom-module>
|
||
|
|
\`;
|
||
|
|
`,
|
||
|
|
{
|
||
|
|
fileName: 'render.js',
|
||
|
|
shouldMinify(template) {
|
||
|
|
return (
|
||
|
|
defaultShouldMinify(template) ||
|
||
|
|
template.parts.some(part => {
|
||
|
|
return part.text.includes('<dom-module>');
|
||
|
|
})
|
||
|
|
);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
);
|
||
|
|
```
|
||
|
|
|
||
|
|
### Do not minify CSS
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { minifyHTMLLiterals, defaultMinifyOptions } from 'minify-html-literals';
|
||
|
|
|
||
|
|
minifyHTMLLiterals(source, {
|
||
|
|
fileName: 'render.js',
|
||
|
|
minifyOptions: {
|
||
|
|
...defaultMinifyOptions,
|
||
|
|
minifyCSS: false
|
||
|
|
},
|
||
|
|
shouldMinifyCSS: () => false
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### Modify generated SourceMap
|
||
|
|
|
||
|
|
```js
|
||
|
|
minifyHTMLLiterals(source, {
|
||
|
|
fileName: 'render.js',
|
||
|
|
generateSourceMap(ms, fileName) {
|
||
|
|
return ms.generateMap({
|
||
|
|
file: `${fileName}-converted.map`, // change file name
|
||
|
|
source: fileName,
|
||
|
|
includeContent: true // include source contents
|
||
|
|
});
|
||
|
|
}
|
||
|
|
});
|
||
|
|
```
|