@ms-cloudpack/esm-stub-utilities 0.15.31 → 0.15.33
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.
- package/README.md +23 -0
- package/package.json +13 -13
package/README.md
CHANGED
|
@@ -18,6 +18,29 @@ const esmStub = await writeESMStubsInWorker({
|
|
|
18
18
|
});
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
+
## What is an ESM stub?
|
|
22
|
+
|
|
23
|
+
"ESM stubs" are a workaround for issues presented by CommonJS modules for Cloudpack's ESM library mode approach. The biggest problem is that CJS has many possible ways to declare exports, some of which are nontrivial or even impossible to find through static analysis. This isn't a problem in a monolithic bundle, but for an ESM bundle in library mode, all the export names must be declared in the bundle output so they can be imported by name in consuming packages. Some bundlers may attempt to convert common patterns to named exports, but others will just provide a default export.
|
|
24
|
+
|
|
25
|
+
The utilities in this package are used to run the package code, detect the actual exported names, and create an ES module format stub file with the proper exports (which can then be used as the bundler entry point). For example:
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
// Original file: index.js
|
|
29
|
+
module.exports.default = { value: 'I am the default export' };
|
|
30
|
+
// Example of a pattern that can't be statically analyzed (suppose it returns "a")
|
|
31
|
+
module.exports[computePropertyName()] = 'why';
|
|
32
|
+
module.exports.b = 'b';
|
|
33
|
+
|
|
34
|
+
// Generated stub file: index-stub.mjs
|
|
35
|
+
import moduleExport from './index.js';
|
|
36
|
+
const { a, b } = moduleExport;
|
|
37
|
+
const defaultExport = moduleExport?.default?.default ?? moduleExport?.default;
|
|
38
|
+
export default defaultExport;
|
|
39
|
+
export { a, b };
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Currently, our primary approach for detecting export names is to run the code in a worker thread, with a browser-like environment provided for packages that need it. This has multiple significant downsides and we're actively considering other options ([tracking issue](https://github.com/microsoft/cloudpack/issues/2548)), but running the code is the only way to approach 100% accuracy.
|
|
43
|
+
|
|
21
44
|
## Special considerations
|
|
22
45
|
|
|
23
46
|
When evaluating named entries in the `exports` of the cjs file, the library is loaded in the Node process. A few libraries are used to simulate the browser environment in order for the script to load. (e.g. some libraries will reference `window` on load, and therefore must be run in an environment that accommodates this.)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ms-cloudpack/esm-stub-utilities",
|
|
3
|
-
"version": "0.15.
|
|
3
|
+
"version": "0.15.33",
|
|
4
4
|
"description": "Generates ESM stubs for CommonJS entry files.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -13,12 +13,22 @@
|
|
|
13
13
|
"import": "./lib/index.js"
|
|
14
14
|
}
|
|
15
15
|
},
|
|
16
|
+
"scripts": {
|
|
17
|
+
"api": "cloudpack-scripts api",
|
|
18
|
+
"build:watch": "cloudpack-scripts build-watch",
|
|
19
|
+
"build": "cloudpack-scripts build",
|
|
20
|
+
"lint:update": "cloudpack-scripts lint-update",
|
|
21
|
+
"lint": "cloudpack-scripts lint",
|
|
22
|
+
"test:update": "cloudpack-scripts test-update",
|
|
23
|
+
"test:watch": "cloudpack-scripts test-watch",
|
|
24
|
+
"test": "cloudpack-scripts test"
|
|
25
|
+
},
|
|
16
26
|
"dependencies": {
|
|
17
27
|
"@happy-dom/global-registrator": "^20.0.2",
|
|
18
|
-
"@ms-cloudpack/common-types": "^0.
|
|
28
|
+
"@ms-cloudpack/common-types": "^0.33.0",
|
|
19
29
|
"@ms-cloudpack/environment": "^0.1.1",
|
|
20
30
|
"@ms-cloudpack/json-utilities": "^0.1.11",
|
|
21
|
-
"@ms-cloudpack/package-utilities": "^13.2.
|
|
31
|
+
"@ms-cloudpack/package-utilities": "^13.2.3",
|
|
22
32
|
"@ms-cloudpack/path-string-parsing": "^1.2.7",
|
|
23
33
|
"@ms-cloudpack/worker-pool": "^0.4.1",
|
|
24
34
|
"oxc-parser": "^0.73.0",
|
|
@@ -30,16 +40,6 @@
|
|
|
30
40
|
"@ms-cloudpack/test-utilities": "^0.5.0",
|
|
31
41
|
"@types/regenerator-runtime": "^0.13.1"
|
|
32
42
|
},
|
|
33
|
-
"scripts": {
|
|
34
|
-
"api": "cloudpack-scripts api",
|
|
35
|
-
"build:watch": "cloudpack-scripts build-watch",
|
|
36
|
-
"build": "cloudpack-scripts build",
|
|
37
|
-
"lint:update": "cloudpack-scripts lint-update",
|
|
38
|
-
"lint": "cloudpack-scripts lint",
|
|
39
|
-
"test:update": "cloudpack-scripts test-update",
|
|
40
|
-
"test:watch": "cloudpack-scripts test-watch",
|
|
41
|
-
"test": "cloudpack-scripts test"
|
|
42
|
-
},
|
|
43
43
|
"files": [
|
|
44
44
|
"lib/**/!(*.test.*)"
|
|
45
45
|
]
|