@localnerve/web-component-build 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +41 -25
  2. package/lib/index.js +2 -0
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,14 +1,29 @@
1
1
  # Web Component Build
2
2
 
3
- > Assembles a web component from css, html, and js parts
3
+ > Assembles a web component from css, html, and js parts, assists user build flexibility
4
4
 
5
5
  [![npm version](https://badge.fury.io/js/@localnerve%2Fweb-component-build.svg)](https://badge.fury.io/js/@localnerve%2Fweb-component-build)
6
6
  ![Verify](https://github.com/localnerve/web-component-build/workflows/Verify/badge.svg)
7
7
  [![Coverage Status](https://coveralls.io/repos/github/localnerve/web-component-build/badge.svg?branch=main)](https://coveralls.io/github/localnerve/web-component-build?branch=main)
8
8
 
9
- 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.
9
+ Assembles a web component from its parts, allows developers to author the component's parts in separate files.
10
+ The parts are processed and written to an output directory, then exposed to a calling build process.
10
11
 
11
- The following is a table of _some_ of the possible input, processing, and output combos. See [options](#options) for detailed explanation of the input.
12
+ * [Why This Exists](#why-this-exists)
13
+ * [Processing Possibilities](#processing-map)
14
+ * [Usage](#usage)
15
+ * [API](#api)
16
+ * [Options](#options-object-optional)
17
+ * [Result](#result-object)
18
+
19
+ ## Why This Exists
20
+ 1. Author web components in separate JS, CSS, and HTML files
21
+ 2. Expose CSS for the web component to builds for computing [CSP hashes](https://github.com/localnerve/csp-hashes#readme)
22
+ 3. Expose HTML for the web component to builds for companion templates and/or DSD for SSR builds
23
+ 4. Enable/ease paying these conveniences forward in web component distribution packages
24
+
25
+ ## Processing Map
26
+ The following is a table of _some_ of the possible input, processing, and output combos. See [options](#options-object-optional) for detailed explanations.
12
27
 
13
28
  | input | processing | output |
14
29
  | ----- | ---------- | ------ |
@@ -30,7 +45,7 @@ The following is a table of _some_ of the possible input, processing, and output
30
45
  ## Usage
31
46
 
32
47
  ```javascript
33
- // Sample usage with most optional options specified
48
+ // Sample usage, all options specified
34
49
  import {build} from '@localnerve/web-component-build';
35
50
  const outputDir = 'some/path/output';
36
51
 
@@ -42,21 +57,22 @@ The following is a table of _some_ of the possible input, processing, and output
42
57
  jsReplacement: '__REPLACEMENT_IN_JS__',
43
58
  terserOptions: { /* terser options */ },
44
59
  htmlminOptions: { /* html-minifier options */ },
45
- cleancssOptions: { /* clean-css options */ }
60
+ cleancssOptions: { /* clean-css options */ },
61
+ minifySkip: false
46
62
  });
47
- // html, js, and css file output written to `outputDir`
63
+ // html, js, and css written to `outputDir`
48
64
 
49
- // retrieve processed content
65
+ // Retrieve processed content
50
66
  const [js, css, html] = await Promise.all([
51
67
  result.getJs(), result.getCss(), result.getHtml()
52
68
  ]);
53
69
 
54
- // retrieve output paths
70
+ // Retrieve output paths
55
71
  const [jsPath, cssPath, htmlPath] = [result.jsPath, result.cssPath, result.htmlPath];
56
72
  ```
57
73
 
58
74
  ## API
59
- This library exports a single function that takes an output directory and processing options.
75
+ This library exports a single function that takes an output directory and processing options, returns a [result](#result-object) object.
60
76
  ```
61
77
  build (outputDir, options): Result
62
78
  ```
@@ -67,32 +83,32 @@ Full path to the output directory where css, html, and javascript output are wri
67
83
  ### Options {Object}, optional*
68
84
  \* 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.
69
85
 
70
- * `cssPath` {String} - Full path to the input css file
86
+ * **cssPath** {String} - Full path to the input css file
71
87
  If supplied:
72
88
  + css will be minified using `cleancssOptions`
73
89
  + css will be wrapped in a `style` tag
74
90
  + css will be inserted into the javascript file if `jsReplacement` and `jsPath` are supplied and no `htmlPath` supplied
75
91
  + css will be prepended to the html file if `htmlPath` is supplied
76
92
 
77
- * `cssLinkHref` {String} - link href to a stylesheet resource to be referenced by the web component
93
+ * **cssLinkHref** {String} - link href to a stylesheet resource to be referenced by the web component
78
94
  If supplied:
79
95
  + href will be wrapped in a `link` tag
80
96
  + resulting `link` will be prepended to the html file if `htmlPath` supplied
81
97
  + resulting `link` will be inserted into the javascript file if no `htmlPath` supplied and `jsReplacement` and `jsPath` supplied
82
98
 
83
- * `htmlPath` {String} - Full path to the input html file
99
+ * **htmlPath** {String} - Full path to the input html file
84
100
  If supplied:
85
101
  + css will be prepended in a `style` tag
86
102
  + cssLinkHref will be prepended in a `link` tag
87
103
  + html will be inserted into the javascript file if `jsReplacement` and `jsPath` is supplied
88
104
 
89
- * `jsPath` {String} - Full path to the input javascript file
90
- * `jsReplacement` {String|RegExp} - The replacement pattern for the css or html in the javascript file. See [pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#pattern) for full documentation
105
+ * **jsPath** {String} - Full path to the input javascript file
106
+ * **jsReplacement** {String|RegExp} - The replacement pattern for the css or html in the javascript file. See [pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#pattern) for full documentation
91
107
  If supplied:
92
- + A replacement will be attempted in the javascript file
108
+ + A replacement will be attempted in the javascript file, `jsPath` must also be supplied
93
109
  + If **not supplied** or falsy, No replacement will be attempted and all assets are just copied to `outputDir`
94
110
 
95
- * `terserOptions` {Object} - The [javascript minifier options](https://github.com/terser/terser/blob/master/README.md#minify-options) object
111
+ * **terserOptions** {Object} - The [javascript minifier options](https://github.com/terser/terser/blob/master/README.md#minify-options) object
96
112
  Defaults:
97
113
  ```
98
114
  {
@@ -100,7 +116,7 @@ Full path to the output directory where css, html, and javascript output are wri
100
116
  }
101
117
  ```
102
118
 
103
- * `htmlminOptions` {Object} - The [html minifier options](https://github.com/kangax/html-minifier/blob/gh-pages/README.md#options-quick-reference) object
119
+ * **htmlminOptions** {Object} - The [html minifier options](https://github.com/kangax/html-minifier/blob/gh-pages/README.md#options-quick-reference) object
104
120
  Defaults:
105
121
  ```
106
122
  {
@@ -112,25 +128,25 @@ Full path to the output directory where css, html, and javascript output are wri
112
128
  }
113
129
  ```
114
130
 
115
- * `cleancssOptions` {Object} - The [css minifier options](https://github.com/clean-css/clean-css/blob/master/README.md#constructor-options) object
131
+ * **cleancssOptions** {Object} - The [css minifier options](https://github.com/clean-css/clean-css/blob/master/README.md#constructor-options) object
116
132
  Defaults (same as `clean-css` defaults)
117
133
 
118
- * `minifySkip` {Boolean} - True to skip all minifications, defaults to false
134
+ * **minifySkip** {Boolean} - True to skip all minifications, defaults to false
119
135
 
120
136
  ### Result {Object}
121
137
  The output of the build process. Allows access to the output paths and full output content. Format:
122
138
 
123
- + cssPath {String}, The full path to the output css
139
+ + **cssPath** {String}, The full path to the output css
124
140
 
125
- + htmlPath {String}, The full path to the output html
141
+ + **htmlPath** {String}, The full path to the output html
126
142
 
127
- + jsPath {String}, The full path to the output javascript
143
+ + **jsPath** {String}, The full path to the output javascript
128
144
 
129
- + getCss {asyncFunction}, gets the output css
145
+ + **getCss** {asyncFunction}, gets the output css
130
146
 
131
- + getHtml {asyncFunction}, gets the output html
147
+ + **getHtml** {asyncFunction}, gets the output html
132
148
 
133
- + getJs {asyncFunction}, gets the output javascript
149
+ + **getJs** {asyncFunction}, gets the output javascript
134
150
 
135
151
  ## License
136
152
  * [BSD-3 Clasuse, Alex Grant, LocalNerve](LICENSE.md)
package/lib/index.js CHANGED
@@ -42,6 +42,8 @@ export async function build (outputDir, {
42
42
 
43
43
  if (jsPath) {
44
44
  jsText = await fs.readFile(jsPath, { encoding: 'utf8' });
45
+ } else if (jsReplacement) {
46
+ throw new Error('Invalid input, jsReplacement supplied without jsPath. Did you forget \'jsPath\'?');
45
47
  }
46
48
 
47
49
  if (cssPath) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@localnerve/web-component-build",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
4
4
  "description": "A library to help build web components",
5
5
  "main": "index.js",
6
6
  "type": "module",
@@ -52,8 +52,8 @@
52
52
  "terser": "^5.26.0"
53
53
  },
54
54
  "devDependencies": {
55
- "@babel/preset-env": "^7.23.5",
56
- "eslint": "^8.55.0",
55
+ "@babel/preset-env": "^7.23.6",
56
+ "eslint": "^8.56.0",
57
57
  "jest": "^29.7.0",
58
58
  "tempy": "^3.1.0"
59
59
  },