@localnerve/web-component-build 0.2.2

package/LICENSE.md

@@ -0,0 +1,11 @@
+Copyright 2023 Alex Grant, LocalNerve, LLC
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,106 @@
+# Web Component Build
+
+> Assembles a web component from css, html, and js parts
+
+This library assembles a web component from its parts, allowing developers to author the component's parts in separate files. The parts are processed and written to an output directory. After processing, this library exposes the parts to a calling build process.  
+
+The following is a table of _some_ of the possible input, processing, and output combos. See [options](#options) for detailed explanation of the processing input.
+
+| input | processing | output |
+| ----- | ---------- | ------ |
+| javascript | minify or optional pass-thru | javascript |
+| 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
+
+```javascript
+  // Sample usage with most optional 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 */ }
+  });
+  // html, js, and css file output 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.
+```
+build (outputDir, options)
+```
+`outputDir` {String} - Full path to the output directory where css, html, and javascript output are written.
+
+### Options
+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` and `jsPath` are supplied and no `htmlPath` supplied
+    + css will be prepended to the html file if `htmlPath` is supplied
+* `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 if `htmlPath` supplied
+    + resulting `link` will be inserted into the javascript file if no `htmlPath` supplied and `jsReplacement` and `jsPath` supplied  
+* `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` and `jsPath` is supplied  
+* `jsPath` {String} - Full path to the input javascript file
+* `jsReplacement` {String} - The token to replace with the css or html in the javascript file  
+  If supplied:
+    + A replacement will be attempted in the javascript file
+    + If **not supplied** or falsy, No replacement will be attempted and all assets are just copied to `outputDir`       
+* `terserOptions` {Object} - The [javascript minifier options](https://github.com/terser/terser/blob/master/README.md#minify-options) object  
+  Defaults:
+  ```
+  {
+    ecma: 2022
+  }
+  ```
+* `htmlminOptions` {Object} - The [html minifier options](https://github.com/kangax/html-minifier/blob/gh-pages/README.md#options-quick-reference) object  
+  Defaults:  
+  ```
+  {
+    minifyJS: true,
+    minifyCSS: true,
+    collapseWhitespace: true,
+    removeAttributeQuotes: true,
+    removeComments: true
+  }
+  ```
+* `cleancssOptions` {Object} - The [css minifier options](https://github.com/clean-css/clean-css/blob/master/README.md#constructor-options) object  
+  Defaults (same as `clean-css` defaults)  
+* `minifySkip` {Boolean} - True to skip all minifications, defaults to false
+
+## License
+  * [BSD-3 Clasuse, Alex Grant, LocalNerve](LICENSE.md)

package/index.js

@@ -0,0 +1,9 @@
+/**
+ * Web Component Build
+ * Assemble and minify a web component from its parts.
+ * Expose parts back to the calling build process.
+ * 
+ * Copyright (c) 2023 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+export {build, build as default} from './lib/index.js';

package/lib/build.js

@@ -0,0 +1,175 @@
+/**
+ * Web Component Build
+ * Builds the component parts
+ * 
+ * Copyright (c) 2023 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import CleanCss from 'clean-css';
+import {minify as _minifyHtml} from 'html-minifier';
+import {minify as _minifyJs} from 'terser';
+
+class WebComponentBuild {
+
+  /**
+   * Construct WebComponentBuild instance.
+   *
+   * @param {String} outputDir - The full path to output directory.
+   * @param {String} [jsPath] - The full path to the input js file.
+   * @param {String} [cssPath] - The full path to the input css file.
+   * @param {String} [htmlPath] - The full path to the input html file.
+   * @param {Boolean} [minifySkip] - flag to skip minification (debug), default false.
+   */
+  constructor (outputDir, jsPath, cssPath, htmlPath, minifySkip = false) {
+    const minimumInput = jsPath || cssPath || htmlPath;
+
+    if (!minimumInput) {
+      throw new Error(
+        'One of jsPath, cssPath, or htmlPath MUST be supplied to do\
+ something meaningful. Did you forget something?'
+      );
+    }
+
+    this.inputCssFile = cssPath;
+    this.inputHtmlFile = htmlPath;
+    this.inputJsFile = jsPath;
+    this.outputDir = outputDir;
+    this.minifySkip = minifySkip;
+    
+    if (jsPath) {
+      this.outputJsFile = path.join(this.outputDir, path.basename(jsPath));
+    }
+    if (htmlPath) {
+      this.outputHtmlFile = path.join(this.outputDir, path.basename(htmlPath));
+    }
+    if (cssPath) {
+      this.outputCssFile = path.join(this.outputDir, path.basename(cssPath));
+    }
+  }
+
+  /**
+   * Minify the input css file and write it to the outputDir.
+   *
+   * @param {Object} options - clean-css options
+   * @returns {String} minified css.
+   */
+  async minifyCss (options = {}) {
+    const cssText = await fs.readFile(this.inputCssFile, {
+      encoding: 'utf8'
+    });
+    
+    const cleanCss =
+      this.minifySkip ? cssText : new CleanCss(options).minify(cssText).styles;
+  
+    await fs.writeFile(this.outputCssFile, cleanCss, {
+      encoding: 'utf8'
+    });
+
+    return cleanCss;
+  }
+
+  /**
+   * Minify the given html and write it to the outputDir.
+   * 
+   * @param {String} htmlText - The full new html text.
+   * @param {Object} options - The html-minifier options.
+   * @returns {String} minified html.
+   */
+  async minifyHtml (htmlText, options = {
+    minifyJS: true,
+    minifyCSS: true,
+    collapseWhitespace: true,
+    removeAttributeQuotes: true,
+    removeComments: true
+  }) {
+    const minifiedHtml =
+      this.minifySkip ? htmlText : _minifyHtml(htmlText, options);
+
+    await fs.writeFile(this.outputHtmlFile, minifiedHtml, {
+      encoding: 'utf8'
+    });
+
+    return minifiedHtml;
+  }
+
+  /**
+   * Minify the given js and write it to the outputDir.
+   * 
+   * @param {String} jsText - The full new js text to process.
+   * @param {Object} options - terser minification options.
+   * @returns {String} minified js.
+   */
+  async minifyJs (jsText, options = {
+    ecma: 2022
+  }) {
+    const minifiedJs =
+      this.minifySkip ? jsText : (await _minifyJs(jsText, options)).code;
+        
+    await fs.writeFile(this.outputJsFile, minifiedJs, {
+      encoding: 'utf8'
+    });
+    
+    return minifiedJs;
+  }
+
+  /**
+   * Get the output interface.
+   * @returns {Object} An interface to access build output content.
+   */
+  get output () {
+    const _cssPath = this.outputCssFile;
+    const _htmlPath = this.outputHtmlFile;
+    const _jsPath = this.outputJsFile;
+
+    return {
+      get cssPath () {
+        return _cssPath;
+      },
+      async getCss () {
+        let cssText;
+        if (_cssPath) {
+          cssText = await fs.readFile(_cssPath, { encoding: 'utf8' });
+        }
+        return cssText;
+      },
+      get htmlPath () {
+        return _htmlPath;
+      },
+      async getHtml () {
+        let htmlText;
+        if (_htmlPath) {
+          htmlText = await fs.readFile(_htmlPath, { encoding: 'utf8' });
+        }
+        return htmlText;
+      },
+      get jsPath () {
+        return _jsPath;
+      },
+      async getJs () {
+        let jsText;
+        if (_jsPath) {
+          jsText = await fs.readFile(_jsPath, { encoding: 'utf8' });
+        }
+        return jsText;
+      }
+    };
+  }
+}
+
+/**
+ * Create WebComponentBuild instance.
+ *
+ * @param {String} cssPath - The full path to the input css file.
+ * @param {String} htmlPath - The full path to the input html file.
+ * @param {String} jsPath - The full path to the input js file.
+ * @param {String} outputDir - The full path to output directory.
+ * @param {Boolean} [minifySkip] - True to skip minifications (debug), default false.
+ * @returns {WebComponentBuild} an instance of WebComponentBuild
+ */
+export function createBuild (
+  cssPath, htmlPath, jsPath, outputDir, minifySkip = false
+) {
+  return new WebComponentBuild(cssPath, htmlPath, jsPath, outputDir, minifySkip);
+}

package/lib/index.js

@@ -0,0 +1,91 @@
+/**
+ * Web Component Build
+ * Assemble and minify a web component from its parts.
+ * Expose parts back to the calling build process.
+ * 
+ * Copyright (c) 2023 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+import * as fs from 'node:fs/promises';
+import * as cheerio from 'cheerio';
+import {createBuild} from './build.js';
+
+/**
+ * Build entry point.
+ * Possible build outcomes:
+ *   1. jsFile only - all contained. Don't expose any css/html to build. Minify js only.
+ *   2. css in js - replace the inline css in js. expose the css to build.
+ *   3. css in html - add the inline css to html, replace the html in the js, expose css/html to build.
+ *   4. csslink in html - add the css link to html, replace the html in the js, expose css/html to build.
+ *   5. csslink in js - add the css link to js, replace the html in js.
+ *   6. html in js - replace the html in the js, expose html to build.
+ *
+ * @param {String} outputDir - full path to the output directory
+ * @param {Object} [options] - optional options
+ * @param {String} [options.jsPath] - full path to the javascript file
+ * @param {String} [options.cssPath] - full path to the input css file
+ * @param {String} [options.cssLinkHref] - http href to css resource
+ * @param {String} [options.htmlPath] - full path to the input html file
+ * @param {String} [options.jsReplacement] - Replacement token in the js file
+ * @param {Object} [options.terserOptions] - Js minifier options (terser)
+ * @param {Object} [options.htmlminOptions] - html-minifier options
+ * @param {Object} [options.cleancssOptions] - clean-css options
+ * @param {Boolean} [options.minifySkip] - default false, flag to skip all minification (debug)
+ * @returns {Object} Interface to getCss, getHtml, getJs for further processing
+ */
+export async function build (outputDir, {
+  jsPath,
+  cssPath,
+  cssLinkHref,
+  htmlPath,
+  jsReplacement,
+  terserOptions,
+  htmlminOptions,
+  cleancssOptions,
+  minifySkip = false
+} = {}) {
+  const build = createBuild(outputDir, jsPath, cssPath, htmlPath, minifySkip);
+  let jsText, cssText, htmlText;
+
+  if (jsPath) {
+    jsText = await fs.readFile(jsPath, { encoding: 'utf8' });
+  }
+
+  if (cssPath) {
+    cssText = await build.minifyCss(cleancssOptions);
+  }
+
+  if (htmlPath) {
+    htmlText = await fs.readFile(htmlPath, { encoding: 'utf8' });
+    const $ = cheerio.load(htmlText);
+    if (cssText) {
+      $('body').prepend(`<style>${cssText}</style>`);
+    }
+    if (cssLinkHref) {
+      $('body').prepend(`<link href="${cssLinkHref}" rel="stylesheet" />`);
+    }
+    htmlText = await build.minifyHtml($('body').html(), htmlminOptions);
+  }
+
+  if (jsReplacement) {
+    if (htmlText) {
+      htmlText = htmlText.replace(/$/mg, '\\');
+      if (htmlText.endsWith('\\')) {
+        htmlText = htmlText.slice(0, -1);
+      }
+      jsText = jsText.replace(jsReplacement, htmlText);
+    } else if (cssText) {
+      jsText = jsText.replace(jsReplacement, `<style>${cssText}</style>`);
+    } else if (cssLinkHref) {
+      jsText = jsText.replace(
+        jsReplacement, `<link href="${cssLinkHref}" rel="stylesheet" />`
+      );
+    }
+  }
+
+  if (jsText) {
+    await build.minifyJs(jsText, terserOptions);
+  }
+
+  return build.output;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@localnerve/web-component-build",
+  "version": "0.2.2",
+  "description": "A library to help build web components",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    "import": "./index.js",
+    "default": "./index.js"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:debug": "node --experimental-vm-modules --inspect-brk node_modules/jest/bin/jest.js"
+  },
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/localnerve/web-component-build.git"
+  },
+  "keywords": [
+    "minifier",
+    "web components",
+    "web",
+    "component",
+    "build",
+    "build tool"
+  ],
+  "author": {
+    "name": "Alex Grant",
+    "email": "alex@localnerve.com",
+    "url": "https://www.localnerve.com"
+  },
+  "maintainers": [
+    {
+      "name": "Alex Grant",
+      "email": "alex@localnerve.com",
+      "url": "https://www.localnerve.com"
+    }
+  ],
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/localnerve/web-component-build/issues"
+  },
+  "homepage": "https://github.com/localnerve/web-component-build#readme",
+  "dependencies": {
+    "cheerio": "^1.0.0-rc.12",
+    "clean-css": "^5.3.3",
+    "html-minifier": "^4.0.0",
+    "terser": "^5.26.0"
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.23.5",
+    "eslint": "^8.55.0",
+    "jest": "^29.7.0",
+    "tempy": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}