@visulima/packem 1.0.0-alpha.113 → 1.0.0-alpha.115

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## @visulima/packem [1.0.0-alpha.115](https://github.com/visulima/packem/compare/@visulima/packem@1.0.0-alpha.114...@visulima/packem@1.0.0-alpha.115) (2024-09-16)
+
+### Bug Fixes
+
+* improved external handling of package imports ([39defc9](https://github.com/visulima/packem/commit/39defc9ae6f783bd3a32c2c57143537e05c4af06))
+
+### Miscellaneous Chores
+
+* renamed test ([35c7269](https://github.com/visulima/packem/commit/35c726930d6a8af046f5f53bd9deb523d31d7370))
+* renamed test ([4ac1ce0](https://github.com/visulima/packem/commit/4ac1ce0f1567c4b46e3628bfbd441b9f1db06b25))
+
+## @visulima/packem [1.0.0-alpha.114](https://github.com/visulima/packem/compare/@visulima/packem@1.0.0-alpha.113...@visulima/packem@1.0.0-alpha.114) (2024-09-16)
+
+### Bug Fixes
+
+* added Security Policy, added test run on release, updated readme ([c07ea0f](https://github.com/visulima/packem/commit/c07ea0fa7140b83fe8ef13c49afe8ef838034686))
+* fixed tests ([fb69a7b](https://github.com/visulima/packem/commit/fb69a7b98d4498c0844da18e179965f0ee7ca310))
+* fixed tests ([b0558c3](https://github.com/visulima/packem/commit/b0558c3449df4e2322b4b44faf27719b21c2e2ee))
+* renamed variables ([273079e](https://github.com/visulima/packem/commit/273079e1ff802231916ecdd9a047b67e754a2b84))
+
 ## @visulima/packem [1.0.0-alpha.113](https://github.com/visulima/packem/compare/@visulima/packem@1.0.0-alpha.112...@visulima/packem@1.0.0-alpha.113) (2024-09-15)
 
 ### Bug Fixes

package/README.md

@@ -34,20 +34,24 @@ It uses the `exports` configuration in `package.json` and recognizes entry file
 
 ## Features
 
-- ✅ package.json#exports, package.json#main, package.json#module to define entry-points
-- ✅ package.json#bin to define executables
-- ✅ package.json#types to define types
-- ✅ Generates package.json#typeVersions to support node 10
-- ✅ Dependency externalization
-- ✅ Minification
-- ✅ TypeScript support + .d.ts bundling
-- ✅ Watch mode
-- ✅ CLI outputs (auto hashbang insertion)
-- ✅ Validates package.json and checks if all fields that are needed to publish your package are configured correctly
-- ✅ Supports multiple runtimes (default, react-server, edge-light)
-- ✅ Supports react server and client components
-- ✅ Supports shared modules
-- ✅ Supports dynamic import
+-   ✅ package.json#exports, package.json#main, package.json#module to define entry-points
+-   ✅ package.json#bin to define executables
+-   ✅ package.json#types to define types
+-   ✅ Generates package.json#typeVersions to support node 10
+-   ✅ Dependency externalization
+-   ✅ Minification
+-   ✅ TypeScript support + .d.ts bundling
+-   ✅ Watch mode
+-   ✅ CLI outputs (auto hashbang insertion)
+-   ✅ Validates package.json and checks if all fields that are needed to publish your package are configured correctly
+-   ✅ Supports multiple runtimes (default, react-server, edge-light)
+-   ✅ Supports react server and client components
+-   ✅ Supports shared modules
+-   ✅ Supports dynamic import
+-   ✅ Supports `tsconfig.json` paths and `package.json` imports resolution
+-   ✅ ESM ⇄ CJS interoperability
+-   ✅ Supports isolated declaration types (experimental)
+-   ✅ Supports wasm [WebAssembly modules](http://webassembly.org)
 
 And more...
 
@@ -237,9 +241,8 @@ For instance:
 
 If you need to separate the `production` and `development` exports condition, `packem` provides `process.env.NODE_ENV` injected by default if present that you don't need to manually inject yourself.
 
-
-- When the `production` exports condition is defined and the file ends with `*.production.*` in the package.json, the bundle will be minified.
-- When the `development` exports condition is defined and the file ends with `*.development.*` in the package.json, the bundle will not be minified.
+-   When the `production` exports condition is defined and the file ends with `*.production.*` in the package.json, the bundle will be minified.
+-   When the `development` exports condition is defined and the file ends with `*.development.*` in the package.json, the bundle will not be minified.
 
 ```json
 {
@@ -254,8 +257,7 @@ If you need to separate the `production` and `development` exports condition, `p
 
 To build executable files with the `bin` field in package.json. The source file matching will be same as the entry files convention.
 
-> [!NOTE]
-> `packem` automatically preserves and prepends the shebang to the executable file, and fix correct permissions for the executable file.
+> [!NOTE] > `packem` automatically preserves and prepends the shebang to the executable file, and fix correct permissions for the executable file.
 
 For example:
 
@@ -380,20 +382,68 @@ console.log(text); // "Hello World"
 
 #### Visualize Bundle Makeup
 
-Use the `--visualize` flag to generate a `stats.html` file at build time, showing the makeup of your bundle.
+Use the `--visualize` flag to generate a `packem-bundle-analyze.html` file at build time, showing the makeup of your bundle.
 
 #### Building Module Workers (Experimental) (WIP)
 
 `packem` supports building module workers with the `--workers` flag, which are a special type of bundle that can be used to run code in a web worker.
 
 ```js
-worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
+worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
 // or simply:
-worker = new Worker('./worker.js', { type: 'module' });
+worker = new Worker("./worker.js", { type: "module" });
 ```
 
 #### CSS and CSS Modules (Coming Soon)
 
+### Aliases
+
+Aliases can be configured in the [import map](https://nodejs.org/api/packages.html#imports), defined in `package.json#imports`.
+
+For native Node.js import mapping, all entries must be prefixed with `#` to indicate an internal [subpath import](https://nodejs.org/api/packages.html#subpath-imports). `Packem` takes advantage of this behavior to define entries that are _not prefixed_ with `#` as an alias.
+
+Native Node.js import mapping supports conditional imports (eg. resolving different paths for Node.js and browser), but `packem` does not.
+
+> ⚠️ Aliases are not supported in type declaration generation. If you need type support, do not use aliases.
+
+```json5
+{
+    // ...
+
+    imports: {
+        // Mapping '~utils' to './src/utils.js'
+        "~utils": "./src/utils.js",
+
+        // Native Node.js import mapping (can't reference ./src)
+        "#internal-package": "./vendors/package/index.js",
+    },
+}
+```
+
+### ESM ⇄ CJS interoperability
+
+Node.js ESM offers [interoperability with CommonJS](https://nodejs.org/api/esm.html#interoperability-with-commonjs) via [static analysis](https://github.com/nodejs/cjs-module-lexer). However, not all bundlers compile ESM to CJS syntax in a way that is statically analyzable.
+
+Because `packem` uses Rollup, it's able to produce CJS modules that are minimal and interoperable with Node.js ESM.
+
+This means you can technically output in CommonJS to get ESM and CommonJS support.
+
+#### `require()` in ESM
+
+Sometimes it's useful to use `require()` or `require.resolve()` in ESM. ESM code that uses `require()` can be seamlessly compiled to CommonJS, but when compiling to ESM, Node.js will error because `require` doesn't exist in the module scope.
+
+When compiling to ESM, `packem` detects `require()` usages and shims it with [`createRequire(import.meta.url)`](https://nodejs.org/api/module.html#modulecreaterequirefilename).
+
+### Environment variables
+
+Pass in compile-time environment variables with the `--env` flag.
+
+This will replace all instances of `process.env.NODE_ENV` with `'production'` and remove unused code:
+
+```sh
+packem build --env.NODE_ENV=production
+```
+
 ## Validating
 
 `Packem` validates your `package.json` file and checks if all fields are configured correctly, that are needed to publish your package.