@localnerve/web-component-build 0.3.1 → 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 +66 -26
  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 processing 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,58 +57,66 @@ 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
- build (outputDir, options)
77
+ build (outputDir, options): Result
62
78
  ```
63
- `outputDir` {String} - Full path to the output directory where css, html, and javascript output are written.
64
79
 
65
- ### Options
66
- 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.
80
+ ### outputDir {String}, required
81
+ Full path to the output directory where css, html, and javascript output are written.
82
+
83
+ ### Options {Object}, optional*
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.
67
85
 
68
- * `cssPath` {String} - Full path to the input css file
86
+ * **cssPath** {String} - Full path to the input css file
69
87
  If supplied:
70
88
  + css will be minified using `cleancssOptions`
71
89
  + css will be wrapped in a `style` tag
72
90
  + css will be inserted into the javascript file if `jsReplacement` and `jsPath` are supplied and no `htmlPath` supplied
73
91
  + css will be prepended to the html file if `htmlPath` is supplied
74
- * `cssLinkHref` {String} - link href to a stylesheet resource to be referenced by the web component
92
+
93
+ * **cssLinkHref** {String} - link href to a stylesheet resource to be referenced by the web component
75
94
  If supplied:
76
95
  + href will be wrapped in a `link` tag
77
96
  + resulting `link` will be prepended to the html file if `htmlPath` supplied
78
97
  + resulting `link` will be inserted into the javascript file if no `htmlPath` supplied and `jsReplacement` and `jsPath` supplied
79
- * `htmlPath` {String} - Full path to the input html file
98
+
99
+ * **htmlPath** {String} - Full path to the input html file
80
100
  If supplied:
81
101
  + css will be prepended in a `style` tag
82
102
  + cssLinkHref will be prepended in a `link` tag
83
103
  + html will be inserted into the javascript file if `jsReplacement` and `jsPath` is supplied
84
- * `jsPath` {String} - Full path to the input javascript file
85
- * `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
104
+
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
86
107
  If supplied:
87
- + A replacement will be attempted in the javascript file
88
- + If **not supplied** or falsy, No replacement will be attempted and all assets are just copied to `outputDir`
89
- * `terserOptions` {Object} - The [javascript minifier options](https://github.com/terser/terser/blob/master/README.md#minify-options) object
108
+ + A replacement will be attempted in the javascript file, `jsPath` must also be supplied
109
+ + If **not supplied** or falsy, No replacement will be attempted and all assets are just copied to `outputDir`
110
+
111
+ * **terserOptions** {Object} - The [javascript minifier options](https://github.com/terser/terser/blob/master/README.md#minify-options) object
90
112
  Defaults:
91
113
  ```
92
114
  {
93
115
  ecma: 2022
94
116
  }
95
- ```
96
- * `htmlminOptions` {Object} - The [html minifier options](https://github.com/kangax/html-minifier/blob/gh-pages/README.md#options-quick-reference) object
117
+ ```
118
+
119
+ * **htmlminOptions** {Object} - The [html minifier options](https://github.com/kangax/html-minifier/blob/gh-pages/README.md#options-quick-reference) object
97
120
  Defaults:
98
121
  ```
99
122
  {
@@ -103,10 +126,27 @@ One or more of `cssPath`, `jsPath`, and/or `htmlPath` **must** be supplied. They
103
126
  removeAttributeQuotes: true,
104
127
  removeComments: true
105
128
  }
106
- ```
107
- * `cleancssOptions` {Object} - The [css minifier options](https://github.com/clean-css/clean-css/blob/master/README.md#constructor-options) object
129
+ ```
130
+
131
+ * **cleancssOptions** {Object} - The [css minifier options](https://github.com/clean-css/clean-css/blob/master/README.md#constructor-options) object
108
132
  Defaults (same as `clean-css` defaults)
109
- * `minifySkip` {Boolean} - True to skip all minifications, defaults to false
133
+
134
+ * **minifySkip** {Boolean} - True to skip all minifications, defaults to false
110
135
 
136
+ ### Result {Object}
137
+ The output of the build process. Allows access to the output paths and full output content. Format:
138
+
139
+ + **cssPath** {String}, The full path to the output css
140
+
141
+ + **htmlPath** {String}, The full path to the output html
142
+
143
+ + **jsPath** {String}, The full path to the output javascript
144
+
145
+ + **getCss** {asyncFunction}, gets the output css
146
+
147
+ + **getHtml** {asyncFunction}, gets the output html
148
+
149
+ + **getJs** {asyncFunction}, gets the output javascript
150
+
111
151
  ## License
112
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.1",
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
  },