|
3 | 3 | > **NOTE:** This tool should only be used on packages in this repository,
|
4 | 4 | > and is not intended for external usage.
|
5 | 5 |
|
6 |
| -Create bundled packages with minimal dependencies and appropriate license attributions. |
| 6 | +You can use this tool to help create bundled packages with minimal dependencies and appropriate license attributions. |
7 | 7 |
|
8 | 8 | ## Why
|
9 | 9 |
|
10 | 10 | When shipping nodejs applications, there is currently no easy way to ensure your users are
|
11 |
| -consuming the exact dependency clojure your package was tested against. |
| 11 | +consuming the exact dependency closure your package was tested against. |
12 | 12 |
|
13 |
| -This is because many libraries define their dependencies with a range, rather then a fixed version. |
| 13 | +This is because many libraries define their dependencies with a range, rather than a fixed version. |
14 | 14 | NPM has provided an install time lock file called [shrinkwrap](https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap)
|
15 |
| -to mitigate this, however, this file is only respected by NPM itself, and not by other package managers such as Yarn. |
| 15 | +to help mitigate this, however, this file is only respected by NPM itself, and not by other package managers such as Yarn. |
16 | 16 |
|
17 | 17 | ## What
|
18 | 18 |
|
19 |
| -This package wires up several popular tools to offer a simple entrypoint for |
| 19 | +This package wires up several popular tools to offer a simpler entrypoint for |
20 | 20 | creating self-contained nodejs packages.
|
21 | 21 |
|
22 |
| -The resulting packages are still npm installable packages, but the entrypoints you specify are |
23 |
| -replaced with a bundled version of them, embedding all their dependencies inline. |
| 22 | +The resulting packages are still npm installable packages, but you can use this tool to |
| 23 | +replace the entrypoints you specify with a bundled version of them, embedding their dependencies inline. |
24 | 24 | Note that embedding dependencies means you are effectively redistributing third-party software.
|
25 |
| -This could have legal/licensing implications, and typically requires proper |
26 |
| -attribution of the bundled dependencies, while validating their licenses allow |
27 |
| -such redistribution. |
| 25 | +This could have licensing implications, and it is your responsibility to provide proper |
| 26 | +and typically requires proper attribution of the bundled dependencies, |
| 27 | +while validating their licenses allow such redistribution. |
28 | 28 |
|
29 |
| -This tool does the following: |
| 29 | +You can use this tool to help achieve the following tasks: |
30 | 30 |
|
31 |
| -- Bundle dependencies inside the package. |
| 31 | +- Bundle the entrypoints inside the package. |
32 | 32 |
|
33 | 33 | > Currently done with [esbuild](https://esbuild.github.io), but is subject to change.
|
34 | 34 |
|
35 |
| -- Validate and create THIRD_PARTY_LICENCES files with complete third-party attributions. |
| 35 | +- Validate and create THIRD_PARTY_LICENCES file with third-party attributions for packages with declared licensing information. |
36 | 36 |
|
37 | 37 | > Currently done with [license-checker](https://www.npmjs.com/package/license-checker), but is subject to change.
|
38 | 38 |
|
39 |
| -- Enforce no circular imports are exhibited in your package, nor in your dependency closure. |
| 39 | +- Detect circular imports that are exhibited in your package, or in your dependency closure. |
40 | 40 |
|
41 | 41 | > Currently done with [madge](https://www.npmjs.com/package/madge), but is subject to change.
|
42 | 42 | > This is necessary because circular imports mess up the declaration order of types in the bundled file.
|
43 | 43 |
|
44 | 44 | ### Disclaimer
|
45 | 45 |
|
46 |
| -- Features of this package rely on the dependencies' declared licensing information, etc... and if that is incorrect, the tool may not notice/warn about that. |
| 46 | +Features of this package rely on the dependencies' declared licensing information, and the fulsomeness of |
| 47 | +the generated attribution is dependent on the dependencies’ declarations. |
| 48 | +This tool is not a substitute for your code attribution processes, but you can use it to help |
| 49 | +streamline attribution items for dependencies that have license declarations. |
| 50 | +The user of this package remains responsible for complying to their dependencies' licensing requirements, |
| 51 | +including any attribution obligations. |
47 | 52 |
|
48 |
| -- The user of this package remains responsible for complying to their dependencies' licensing requirements. |
49 |
| - |
50 |
| -- While this package makes reasonable efforts to ensure the produced THIRD_PARTY_LICENSES file is correct, |
51 |
| -the user is responsible for ensuring the output is correct (this is why it is recommended to check it into source control) |
52 |
| -If unsure, users should seek legal counsel before releasing bundled artifacts. |
| 53 | +We strongly recommend that you check all of your code into source control, and follow your ordinary code attribution processes. |
53 | 54 |
|
54 | 55 | ## Alternative Approaches
|
55 | 56 |
|
@@ -129,17 +130,17 @@ We recommend to integrate this tool in the following way:
|
129 | 130 | 1. Add a `node-bundle validate` command as a post compile step.
|
130 | 131 | 2. Set your packaging command to `node-bundle pack`.
|
131 | 132 |
|
132 |
| -This way, local dev builds will be validated not to break any functionality needed for bundling. |
| 133 | +This way, you can validate local dev builds not to break any functionality needed for bundling. |
133 | 134 | In addition, developers can run `node-bundle validate --fix` to automatically fix any (fixable) violations
|
134 |
| -and commit that to source code. |
| 135 | +and commit that to source control. |
135 | 136 |
|
136 | 137 | For example, if a dependency is added but the attribution file has not been re-generated,
|
137 |
| -`validate` will catch this, and `validate --fix` will regenerate it. |
| 138 | +you can use `node-bundle validate` to catch this, and regenerate it with `node-bundle validate --fix`. |
138 | 139 |
|
139 | 140 | ## Take into account
|
140 | 141 |
|
141 | 142 | By default, the tool will use the `main` directive of the `package.json` as
|
142 |
| -the entrypoint. This will ensure that all top level exports of the |
| 143 | +the entrypoint. This will help you ensure that all top level exports of the |
143 | 144 | package are preserved.
|
144 | 145 |
|
145 | 146 | Deep imports such as `const plugins = require('your-package/lib/plugins')` are considered
|
|
0 commit comments