@localnerve/web-component-build
v1.5.0
Published
A library to help build web components
Downloads
194
Maintainers
Readme
Web Component Build
Assembles a web component from css, html, and js parts, assists user build flexibility
Assembles a web component from its parts, allows developers to author the component's parts in separate files.
The parts are processed and written to an output directory, then exposed to a calling build process.
Why This Exists
- Author web components in separate JS, CSS, and HTML files
- Expose CSS for the web component to builds for computing CSP hashes
- Expose HTML for the web component to builds for companion templates and/or DSD for SSR builds
- Enable/ease paying these conveniences forward in web component distribution packages
Processing Map
The following is a table of some of the possible input, processing, and output combos. See options for detailed explanations.
| input | processing | output | | ----- | ---------- | ------ | | javascript | minify javascript | javascript | | css | minify css | css | | html | minify html | html | | css, html | minify css, prepend style tag to html, minify html | css, html | | css, html, cssHref | minfy css, prepend style tag to html, prepend link tag to html, minify html | css, html | | cssHref, html | prepend link tag to html, minify html | html | | javascript, css | minify css, merge style tag into javascript, minify javascript | css, javascript | | javascript, css, html | minify css, prepend style tag to html, minify html, merge into javascript, minify javascript | css, html, javascript | | javascript, css, html, cssHref | minify css, prepend style tag to html, prepend link tag to html, minify html, merge into javascript, minify javascript | css, html, javascript | | javascript, html | minify html, merge into javascript, minify javascript | html, javascript | | javascript, html, cssHref | prepend link tag to html, minify html, merge into javascript, minify javascript | html, javascript | | javascript, cssHref | add link tag to javascript, minify javascript | javascript |
By default, html minification minifies any css found therein.
Usage
// Sample usage, all options specified
import {build} from '@localnerve/web-component-build';
const outputDir = 'some/path/output';
const result = await build(outputDir, {
cssPath: '/some/path/file.css',
cssLinkHref: '//some/path/file.css',
jsPath: '/some/path/file.js',
htmlPath: '/some/path/file.html',
jsReplacement: '__REPLACEMENT_IN_JS__',
terserOptions: { /* terser options */ },
htmlminOptions: { /* html-minifier options */ },
cleancssOptions: { /* clean-css options */ },
minifySkip: false
});
// html, js, and css written to `outputDir`
// Retrieve processed content
const [js, css, html] = await Promise.all([
result.getJs(), result.getCss(), result.getHtml()
]);
// Retrieve output paths
const [jsPath, cssPath, htmlPath] = [result.jsPath, result.cssPath, result.htmlPath];
API
This library exports a single function that takes an output directory and processing options, returns a result object.
build (outputDir, options): Result
outputDir {String}, required
Full path to the output directory where css, html, and javascript output are written.
Options {Object}, optional*
* Not really. One or more of cssPath
, jsPath
, and/or htmlPath
must be supplied. They have no default, so if no options are supplied, this library throws an exception.
cssPath {String} - Full path to the input css file
If supplied:- css will be minified using
cleancssOptions
- css will be wrapped in a
style
tag - css will be inserted into the javascript file if
jsReplacement
andjsPath
are supplied and nohtmlPath
supplied - css will be prepended to the html file if
htmlPath
is supplied
- css will be minified using
cssLinkHref {String} - link href to a stylesheet resource to be referenced by the web component
If supplied:- href will be wrapped in a
link
tag - resulting
link
will be prepended to the html file ifhtmlPath
supplied - resulting
link
will be inserted into the javascript file if nohtmlPath
supplied andjsReplacement
andjsPath
supplied
- href will be wrapped in a
htmlPath {String} - Full path to the input html file
If supplied:- css will be prepended in a
style
tag - cssLinkHref will be prepended in a
link
tag - html will be inserted into the javascript file if
jsReplacement
andjsPath
is supplied
- css will be prepended in a
jsPath {String} - Full path to the input javascript file
jsReplacement {String|RegExp} - The replacement pattern for the css or html in the javascript file. See pattern for full documentation
If supplied:- A replacement will be attempted in the javascript file,
jsPath
must also be supplied - If not supplied or falsy, No replacement will be attempted and all assets are just copied to
outputDir
- A replacement will be attempted in the javascript file,
terserOptions {Object} - The javascript minifier options object
Defaults:{ ecma: 2022 }
htmlminOptions {Object} - The html minifier options object
Defaults:{ minifyJS: true, minifyCSS: true, collapseWhitespace: true, removeAttributeQuotes: true, removeComments: true }
cleancssOptions {Object} - The css minifier options object
Defaults (same asclean-css
defaults)minifySkip {Boolean} - True to skip all minifications, defaults to false
Result {Object}
The output of the build process. Allows access to the output paths and full output content. Format:
cssPath {String}, The full path to the output css
htmlPath {String}, The full path to the output html
jsPath {String}, The full path to the output javascript
getCss {asyncFunction}, gets the output css
getHtml {asyncFunction}, gets the output html
getJs {asyncFunction}, gets the output javascript