diff --git a/guides/esbuild.md b/guides/esbuild.md new file mode 100644 index 0000000..8526bc7 --- /dev/null +++ b/guides/esbuild.md @@ -0,0 +1,91 @@ +--- +title: esbuild +stack: Bundler +description: Update from CommonJS to ES Module output in esbuild +--- + +esbuild is a JavaScript bundler built in Go. It handles ESM natively and bundles for the browser out of the box. Most of the work here is removing the CommonJS output you no longer need. + +## 1. Mark the package as ESM + +Add `type: "module"` to your `package.json`. Every `.js` file in the package is +now treated as an ES module. + +```json +{ + "name": "my-package", + "type": "module" +} +``` + +Any file that genuinely still has to be CommonJS (e.g. a config file for an older +tool) can keep the `.cjs` extension. + +## 2. Emit a single ESM bundle + +Since the default for esbuild is ESM, you can omit the `format` parameter if you've previously defined `cjs` as its value. + +```js +import * as esbuild from 'esbuild'; + +await esbuild.build({ + entryPoints: ['src/index.js'], + bundle: true, + outfile: 'dist/index.js' +}); +``` + +Alternatively, if you are using the CLI: + +```bash +esbuild "src/index.js" --bundle --outfile="dist/index.js" +``` + +If you were previously building both CJS and ESM formats, remove the separate +build step or output for CommonJS. + +### "platform" flag + +If you are using the `platform` parameter with the value of `node` and `bundle` is set to `true`, this will default to the `cjs` format. In this case, you need to explicitly define the `format` to `esm`: + +```js +import * as esbuild from 'esbuild'; + +await esbuild.build({ + entryPoints: ['src/index.js'], + platform: 'node', + bundle: true, + format: 'esm', + outfile: 'dist/index.js' +}); +``` + +and in the CLI: + +```bash +esbuild "src/index.js" --platform=node --bundle --format=esm --outfile="dist/index.js" +``` + +## 3. Point `exports` at the bundle + +Replace `main` with an `exports` field. This is what lets Node.js and bundlers +resolve your package, and it stops deep imports into your `dist` folder from +becoming part of your public API by accident. + +```json +{ + "exports": { + ".": "./dist/index.js" + }, + "files": ["dist"] +} +``` + +## 4. Check the result + +Run [publint](https://publint.dev) to catch problems with leftover CommonJS +references, publishing config, etc. + +```sh +npx publint +``` diff --git a/guides/rolldown.md b/guides/rolldown.md new file mode 100644 index 0000000..801e696 --- /dev/null +++ b/guides/rolldown.md @@ -0,0 +1,65 @@ +--- +title: Rolldown +stack: Bundler +description: Switch a Rolldown build to ESM output and drop the CommonJS bundle. +--- + +Rolldown is built on ESM-first principles from the ground up, making it an ideal +choice for ESM-only packages. Most of the work here is removing the CommonJS +output you no longer need. + +## 1. Mark the package as ESM + +Add `type: "module"` to your `package.json`. Every `.js` file in the package is +now treated as an ES module. + +```json +{ + "name": "my-package", + "type": "module" +} +``` + +Any file that genuinely still has to be CommonJS (e.g. a config file for an older +tool) can keep the `.cjs` extension. + +## 2. Emit a single ESM bundle + +Drop the `cjs` entry from your Rolldown config: + +```ts +export default { + input: 'src/index.js', + output: { + file: 'dist/index.js', + format: 'es' + } +}; +``` + +If you were using `output` as an array to emit both formats, it can go back to +being a single object. + +## 3. Point `exports` at the bundle + +Replace `main` with an `exports` field. This is what lets Node.js and bundlers +resolve your package, and it stops deep imports into your `dist` folder from +becoming part of your public API by accident. + +```json +{ + "exports": { + ".": "./dist/index.js" + }, + "files": ["dist"] +} +``` + +## 4. Check the result + +Run [publint](https://publint.dev) to catch problems with leftover CommonJS +references, publishing config, etc. + +```sh +npx publint +``` diff --git a/guides/rollup.md b/guides/rollup.md index 09891ee..6f86bd3 100644 --- a/guides/rollup.md +++ b/guides/rollup.md @@ -10,7 +10,7 @@ removing the CommonJS output you no longer need. ## 1. Mark the package as ESM Add `type: "module"` to your `package.json`. Every `.js` file in the package is -now an ES module. +now treated as an ES module. ```json { diff --git a/src/routes/+page.svelte b/src/routes/+page.svelte index 68e925a..5f25744 100644 --- a/src/routes/+page.svelte +++ b/src/routes/+page.svelte @@ -25,7 +25,19 @@

esmodule.com

What are ES modules?

-

TODO: explain briefly what ES modules are

+

+ Introduced in the ES6 specification, the ECMAScript modules (ES modules or ESM) format is + the standardized format for packaging and organizing JavaScript code. It provides a native + way to import and export code across files and packages. +

+ +

+ ES modules enable better code organization, dependency management, and enable tools to + perform static analysis for optimizations like tree-shaking. Since its official addition to + the JavaScript specification, ES modules are now widely adaopted in modern browsers and + other runtime environments, making it the universal standard for modularizing JavScript + code. +

See an example