Merge branch 'main' of https://github.com/esbuild/esbuild.github.io i…

…nto sync-07b1501e

package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "esbuild": "0.21.4",
+    "esbuild": "0.22.0",
     "fast-watch": "1.0.0",
     "highlight.js": "10.4.1",
     "js-yaml": "3.14.0",

src/content/api.yml

@@ -1033,6 +1033,12 @@ body:
       immediately-invoked function expression to prevent variables from leaking
       into the global scope.
       </p>
+    - >
+      <p>
+      The [packages](#packages) setting is set to `bundle` by default, which
+      means all packages are allowed to be bundled. This is important because
+      the browser won't otherwise be able to load them.
+      </p>
     - >
       <p>
       If a package specifies a map for the
@@ -1097,6 +1103,14 @@ body:
       ES6-style exports using `export` statements will be converted into getters
       on the CommonJS `exports` object.
       </p>
+    - >
+      <p>
+      The [packages](#packages) setting is set to `external` by default, which
+      means all packages are excluded from the bundle. This avoids compatibility
+      problems from packages using node-specific features that don't work with
+      esbuild. If you don't want this behavior, you'll have to explicitly set
+      the [packages](#packages) setting to `bundle` instead.
+      </p>
     - >
       <p>
       All [built-in node modules](https://nodejs.org/docs/latest/api/) such
@@ -1160,6 +1174,11 @@ body:
       2015 (i.e. ES6). You can change the output format if this default is not
       appropriate.
       </p>
+    - >
+      <p>
+      The [packages](#packages) setting is set to `bundle` by default, which
+      means all packages are allowed to be bundled.
+      </p>
     - >
       <p>
       The [main fields](#main-fields) setting is empty by default. If you want
@@ -3530,6 +3549,7 @@ body:
             EntryPoints: []string{"app.js"},
             Bundle:      true,
             Outdir:      "out",
+            Write:       true,
           })
 
           if len(result.Errors) > 0 {
@@ -3590,7 +3610,8 @@ body:
           result := api.Build(api.BuildOptions{
             EntryPoints: []string{"app.js"},
             Bundle:      true,
-            Outdir:      "out.js",
+            Outfile:     "out.js",
+            Write:       true,
           })
 
           if len(result.Errors) > 0 {
@@ -3949,34 +3970,31 @@ body:
       This has several uses. First of all, it can be used to trim unnecessary
       code from your bundle for a code path that you know will never be
       executed. For example, a package may contain code that only runs in node
-      but you will only be using that package in the browser. It can also be
-      used to import code in node at run time from a package that cannot be
-      bundled. For example, the `fsevents` package contains a native extension,
-      which esbuild doesn't support. Marking something as external looks like
-      this:
+      but you will only be using that package in the browser. Marking something
+      as external looks like this:
 
   - example:
       cli:
         - $: |
-            echo 'require("fsevents")' > app.js
+            echo 'import "foo"' > app.js
         - $: |
-            esbuild app.js --bundle --external:fsevents --platform=node
+            esbuild app.js --bundle --external:foo --format=esm
         - expect: |
             // app.js
-            require("fsevents");
+            import "foo";
 
       mjs: |
         import * as esbuild from 'esbuild'
         import fs from 'node:fs'
 
-        fs.writeFileSync('app.js', 'require("fsevents")')
+        fs.writeFileSync('app.js', 'import "foo"')
 
         await esbuild.build({
           entryPoints: ['app.js'],
           outfile: 'out.js',
           bundle: true,
-          platform: 'node',
-          external: ['fsevents'],
+          external: ['foo'],
+          format: 'esm',
         })
 
       go: |
@@ -3987,15 +4005,15 @@ body:
         import "os"
 
         func main() {
-          ioutil.WriteFile("app.js", []byte("require(\"fsevents\")"), 0644)
+          ioutil.WriteFile("app.js", []byte("import \"foo\""), 0644)
 
           result := api.Build(api.BuildOptions{
             EntryPoints: []string{"app.js"},
             Outfile:     "out.js",
             Bundle:      true,
             Write:       true,
-            Platform:    api.PlatformNode,
-            External:    []string{"fsevents"},
+            External:    []string{"foo"},
+            Format:      api.FormatESModule,
           })
 
           if len(result.Errors) > 0 {
@@ -4276,11 +4294,50 @@ body:
   - h3: Packages
 
   - p: >
-      Use this setting to exclude all of your package's dependencies from the bundle.
-      This is useful when [bundling for node](/getting-started/#bundling-for-node)
+      Use this setting to control whether all of your package's dependencies
+      are excluded from the bundle or not. This is useful when
+      [bundling for node](/getting-started/#bundling-for-node)
       because many npm packages use node-specific features that esbuild doesn't
       support while bundling (such as `__dirname`, `import.meta.url`, `fs.readFileSync`,
-      and `*.node` native binary modules). Using it looks like this:
+      and `*.node` native binary modules). There are two possible values:
+
+  - ul:
+    - >
+      `bundle`
+      <p>
+      This is the default value when the [platform](#platform) is set to
+      `browser`. It means that package imports are allowed to be bundled.
+      Note that this value doesn't mean all packages will be bundled, just that
+      they are allowed to be. You can still exclude individual packages from
+      the bundle using [external](#external).
+      </p>
+
+    - >
+      `external`
+      <p>
+      This is the default value when the [platform](#platform) is set to `node`.
+      It means that all package imports considered external to the bundle,
+      and are not bundled. _Note that your dependencies must still be present
+      on the file system when your bundle is run._ It has the same effect as
+      manually passing each dependency to [external](#external) but is more
+      concise. If you want to customize which of your dependencies are external
+      and which ones aren't, then you should set this to `bundle` instead and
+      then use [external](#external) for individual dependencies.
+      </p>
+      <p>
+      This setting considers all import paths that "look like" package imports
+      in the original source code to be package imports. Specifically import paths
+      that don't start with a path segment of `/` or `.` or `..` are considered
+      to be package imports. The only two exceptions to this rule are
+      [subpath imports](https://nodejs.org/api/packages.html#subpath-imports)
+      (which start with a `#` character) and TypeScript path remappings via
+      [`paths`](https://www.typescriptlang.org/tsconfig/#paths) and/or
+      [`baseUrl`](https://www.typescriptlang.org/tsconfig/#baseUrl) in
+      `tsconfig.json` (which are applied first).
+      </p>
+
+  - p: >
+      Using it looks like this:
 
   - example:
       in:
@@ -4316,15 +4373,6 @@ body:
           }
         }
 
-  - p: >
-      Enabling this automatically marks all import paths that look like npm
-      packages (i.e. that don't start with a `.` or `..` path component and
-      that aren't absolute paths) as external. It has the same effect as
-      manually passing each dependency to [external](#external) but is more
-      concise. If you want to customize which of your dependencies are
-      external and which ones aren't, then you should be using
-      [external](#external) instead of this setting.
-
   - p: >
       Note that this setting only has an effect when [bundling](#bundle) is
       enabled. Also note that marking an import path as external happens after

src/content/content-types.yml

@@ -92,8 +92,8 @@ body:
       | [Top-level await](https://github.com/tc39/proposal-top-level-await)                                                    | `es2022`                             | `await import(x)`           |
       | [Arbitrary module namespace identifiers](https://github.com/bmeck/proposal-arbitrary-module-namespace-identifiers)     | `es2022`                             | `export {foo as 'f o o'}`   |
       | [RegExp match indices](https://github.com/tc39/proposal-regexp-match-indices)                                          | `es2022`                             | `/x(.+)y/d`<sup>1</sup>     |
+      | [RegExp set notation](https://github.com/tc39/proposal-regexp-v-flag)                                                  | `es2024`                             | `/[\w--\d]/v`<sup>1</sup>   |
       | [Hashbang grammar](https://github.com/tc39/proposal-hashbang)                                                          | `esnext`                             | `#!/usr/bin/env node`       |
-      | [RegExp set notation](https://github.com/tc39/proposal-regexp-v-flag)                                                  | `esnext`                             | `/[\w--\d]/`<sup>1</sup>    |
 
   - p: >
       <footer>

src/content/getting-started.yml

@@ -215,14 +215,12 @@ body:
       If you are bundling code that will be run in node, you should configure
       the [platform](/api/#platform) setting by passing <code>--platform=<wbr>node</code>
       to esbuild. This simultaneously changes a few different settings to
-      node-friendly default values. For example, all packages that are
-      built-in to node such as `fs` are automatically marked as external so
-      esbuild doesn't try to bundle them. This setting also disables the
-      interpretation of the browser field in `package.json`.
-
-  - p: >
-      If your code uses newer JavaScript syntax that doesn't work in your
-      version of node, you will want to configure the [target](/api/#target)
+      node-friendly default values. For example, all of your dependencies are
+      automatically excluded from the bundle to avoid compatibility problems from
+      packages using node-specific features that don't work with esbuild. You
+      can read more in the documentation for the [platform](/api/#platform)
+      setting. If your code uses newer JavaScript syntax that doesn't work in your
+      version of node, you will want to also configure the [target](/api/#target)
       version of node:
 
   - example:
@@ -266,26 +264,27 @@ body:
         }
 
   - p: >
-      You also may not want to bundle your dependencies with esbuild. There
-      are many node-specific features that esbuild doesn't support while
-      bundling such as `__dirname`, `import.meta.url`, `fs.readFileSync`,
-      and `*.node` native binary modules. You can exclude all of your
-      dependencies from the bundle by setting [packages](/api/#packages)
-      to external:
+      _Note that by default, your dependencies must still be present on the
+      file system when your bundle is run._ If you want to include your
+      dependencies in the bundle, you can change the [packages](/api/#packages)
+      setting to `--packages=bundle`. However, this may not work with packages
+      that use node-specific features that esbuild doesn't support while
+      bundling (such as `__dirname`, `import.meta.url`, `fs.readFileSync`, and
+      `*.node` native binary modules):
 
   - example:
       in:
-        app.jsx: '<div/>'
+        app.js: '1 + 2'
 
       cli: |
-        esbuild app.jsx --bundle --platform=node --packages=external
+        esbuild app.js --bundle --platform=node --packages=bundle
 
       js: |
         require('esbuild').buildSync({
-          entryPoints: ['app.jsx'],
+          entryPoints: ['app.js'],
           bundle: true,
           platform: 'node',
-          packages: 'external',
+          packages: 'bundle',
           outfile: 'out.js',
         })
 
@@ -297,10 +296,10 @@ body:
 
         func main() {
           result := api.Build(api.BuildOptions{
-            EntryPoints: []string{"app.jsx"},
+            EntryPoints: []string{"app.js"},
             Bundle:      true,
             Platform:    api.PlatformNode,
-            Packages:    api.PackagesExternal,
+            Packages:    api.PackagesBundle,
             Write:       true,
           })
 
@@ -309,10 +308,6 @@ body:
           }
         }
 
-  - p: >
-      If you do this, your dependencies must still be present on the file
-      system at run-time since they are no longer included in the bundle.
-
   - h2: Simultaneous platforms
 
   - p: >
@@ -465,6 +460,7 @@ body:
       | [`@esbuild/linux-s390x`](https://www.npmjs.org/package/@esbuild/linux-s390x)       | `linux`              | `s390x`                | <a class="dl" href="https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-CURRENT_ESBUILD_VERSION.tgz"></a>       |
       | [`@esbuild/linux-x64`](https://www.npmjs.org/package/@esbuild/linux-x64)           | `linux`              | `x64`                  | <a class="dl" href="https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-CURRENT_ESBUILD_VERSION.tgz"></a>           |
       | [`@esbuild/netbsd-x64`](https://www.npmjs.org/package/@esbuild/netbsd-x64)         | `netbsd`<sup>1</sup> | `x64`                  | <a class="dl" href="https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-CURRENT_ESBUILD_VERSION.tgz"></a>         |
+      | [`@esbuild/openbsd-arm64`](https://www.npmjs.org/package/@esbuild/openbsd-arm64)   | `openbsd`            | `arm64`                | <a class="dl" href="https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-CURRENT_ESBUILD_VERSION.tgz"></a>   |
       | [`@esbuild/openbsd-x64`](https://www.npmjs.org/package/@esbuild/openbsd-x64)       | `openbsd`            | `x64`                  | <a class="dl" href="https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-CURRENT_ESBUILD_VERSION.tgz"></a>       |
       | [`@esbuild/sunos-x64`](https://www.npmjs.org/package/@esbuild/sunos-x64)           | `sunos`              | `x64`                  | <a class="dl" href="https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-CURRENT_ESBUILD_VERSION.tgz"></a>           |
       | [`@esbuild/win32-arm64`](https://www.npmjs.org/package/@esbuild/win32-arm64)       | `win32`              | `arm64`                | <a class="dl" href="https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-CURRENT_ESBUILD_VERSION.tgz"></a>       |

src/try/build.ts

@@ -283,8 +283,8 @@ function addBlock(isEntryPoint = false, path = '', content = ''): Block {
   }
   let sourceMapLinkEl: HTMLAnchorElement | undefined
 
-  disableAnnoyingBehaviors(pathEl)
-  disableAnnoyingBehaviors(contentEl)
+  disableAnnoyingBehaviors(pathEl, false)
+  disableAnnoyingBehaviors(contentEl, false)
   pathEl.placeholder = '<stdin>'
   pathEl.value = path
   entryEl.className = 'entryToggle'

src/try/index.css

@@ -391,6 +391,11 @@ a.underLink:hover,
   color: var(--fg-on);
 }
 
+.outputPath span {
+  font-weight: normal;
+  font-style: italic;
+}
+
 #slowWarning {
   display: none;
   color: #CC9C00;

src/try/output.ts

@@ -16,9 +16,28 @@ const mangleCacheEl = document.createElement('textarea')
 const metafileEl = document.createElement('textarea')
 const sourceMapEl = document.createElement('textarea')
 const buildOutputEls: HTMLTextAreaElement[] = []
+const encoder = new TextEncoder
 let sourceMapLinkEl: HTMLAnchorElement | undefined
+let numberFormat: Intl.NumberFormat | undefined
 let loadingFailure = false
 
+let formatInteger = (value: number): string => {
+  return numberFormat ? numberFormat.format(value) : value + ''
+}
+
+let formatNumberWithDecimal = (value: number): string => {
+  let parts = value.toFixed(1).split('.', 2)
+  return formatInteger(+parts[0]) + '.' + parts[1]
+}
+
+let bytesToText = (bytes: number): string => {
+  if (bytes === 1) return '1 byte'
+  if (bytes < 1024) return formatInteger(bytes) + ' bytes'
+  if (bytes < 1024 * 1024) return formatNumberWithDecimal(bytes / 1024) + ' kb'
+  if (bytes < 1024 * 1024 * 1024) return formatNumberWithDecimal(bytes / (1024 * 1024)) + ' mb'
+  return formatNumberWithDecimal(bytes / (1024 * 1024 * 1024)) + ' gb'
+}
+
 disableAnnoyingBehaviors(transformOutputEl, true)
 disableAnnoyingBehaviors(legalCommentsEl, true)
 disableAnnoyingBehaviors(mangleCacheEl, true)
@@ -33,7 +52,7 @@ export function resetHeight(el: HTMLTextAreaElement): void {
   document.body.style.paddingBottom = '0'
 }
 
-export function disableAnnoyingBehaviors(el: HTMLTextAreaElement | HTMLInputElement, readOnly = false): void {
+export function disableAnnoyingBehaviors(el: HTMLTextAreaElement | HTMLInputElement, readOnly: boolean): void {
   el.readOnly = readOnly
   el.spellcheck = false
   el.autocapitalize = 'off'
@@ -167,12 +186,15 @@ export function updateBuildOutput({ outputFiles_, metafile_, mangleCache_, stder
     for (const file of outputFiles_) {
       const div = document.createElement('div')
       const outputPath = document.createElement('div')
+      const outputSize = document.createElement('span')
       const textarea = document.createElement('textarea')
       outputPath.className = 'outputPath'
       outputPath.textContent = file.path.replace(/^\//, '')
+      outputSize.textContent = ' (' + bytesToText(encoder.encode(file.text).length) + ')'
+      outputPath.append(outputSize)
       textarea.readOnly = true
       textarea.value = file.text.replace(/\n$/, '')
-      disableAnnoyingBehaviors(textarea)
+      disableAnnoyingBehaviors(textarea, true)
       div.className = 'buildOutput hasLabel'
       div.append(textarea)
 
@@ -285,3 +307,9 @@ addEventListener('resize', () => {
   }
   resetHeight(mangleCacheEl)
 })
+
+// Handle the case where this API doesn't exist
+try {
+  numberFormat = new Intl.NumberFormat()
+} catch {
+}