From ccf70086543a034495834b4135e15e91a3ffceb8 Mon Sep 17 00:00:00 2001 From: Evan Wallace Date: Mon, 1 Jul 2024 23:37:15 -0400 Subject: [PATCH] Revert "update docs for new `--packages` default values" This reverts commit f953a083462861d27f2d712044233a8a8d38c0dc. --- src/content/api.yml | 54 ++++++++++++--------------------- src/content/getting-started.yml | 43 ++++++++++++++------------ 2 files changed, 43 insertions(+), 54 deletions(-) diff --git a/src/content/api.yml b/src/content/api.yml index 931b6e8..31c2230 100644 --- a/src/content/api.yml +++ b/src/content/api.yml @@ -1033,12 +1033,6 @@ body: immediately-invoked function expression to prevent variables from leaking into the global scope.

- - > -

- 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. -

- >

If a package specifies a map for the @@ -1103,14 +1097,6 @@ body: ES6-style exports using `export` statements will be converted into getters on the CommonJS `exports` object.

- - > -

- 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. -

- >

All [built-in node modules](https://nodejs.org/docs/latest/api/) such @@ -1174,11 +1160,6 @@ body: 2015 (i.e. ES6). You can change the output format if this default is not appropriate.

- - > -

- The [packages](#packages) setting is set to `bundle` by default, which - means all packages are allowed to be bundled. -

- >

The [main fields](#main-fields) setting is empty by default. If you want @@ -3970,30 +3951,34 @@ 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. Marking something - as external looks like this: + 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: - example: cli: - $: | - echo 'require("foo")' > app.js + echo 'require("fsevents")' > app.js - $: | - esbuild app.js --bundle --external:foo + esbuild app.js --bundle --external:fsevents --platform=node - expect: | // app.js - require("foo"); + require("fsevents"); mjs: | import * as esbuild from 'esbuild' import fs from 'node:fs' - fs.writeFileSync('app.js', 'require("foo")') + fs.writeFileSync('app.js', 'require("fsevents")') await esbuild.build({ entryPoints: ['app.js'], outfile: 'out.js', bundle: true, - external: ['foo'], + platform: 'node', + external: ['fsevents'], }) go: | @@ -4004,14 +3989,15 @@ body: import "os" func main() { - ioutil.WriteFile("app.js", []byte("require(\"foo\")"), 0644) + ioutil.WriteFile("app.js", []byte("require(\"fsevents\")"), 0644) result := api.Build(api.BuildOptions{ EntryPoints: []string{"app.js"}, Outfile: "out.js", Bundle: true, Write: true, - External: []string{"foo"}, + Platform: api.PlatformNode, + External: []string{"fsevents"}, }) if len(result.Errors) > 0 { @@ -4303,18 +4289,16 @@ body: - > `bundle`

- 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). + This is the default value. 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).

- > `external`

- This is the default value when the [platform](#platform) is set to `node`. - It means that all package imports considered external to the bundle, + This 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 diff --git a/src/content/getting-started.yml b/src/content/getting-started.yml index 5c93fd9..2fd052d 100644 --- a/src/content/getting-started.yml +++ b/src/content/getting-started.yml @@ -215,12 +215,14 @@ body: If you are bundling code that will be run in node, you should configure the [platform](/api/#platform) setting by passing --platform=node to esbuild. This simultaneously changes a few different settings to - 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) + 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) version of node: - example: @@ -264,27 +266,26 @@ body: } - p: > - _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): + 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: - example: in: - app.js: '1 + 2' + app.jsx: '

' cli: | - esbuild app.js --bundle --platform=node --packages=bundle + esbuild app.jsx --bundle --platform=node --packages=external js: | require('esbuild').buildSync({ - entryPoints: ['app.js'], + entryPoints: ['app.jsx'], bundle: true, platform: 'node', - packages: 'bundle', + packages: 'external', outfile: 'out.js', }) @@ -296,10 +297,10 @@ body: func main() { result := api.Build(api.BuildOptions{ - EntryPoints: []string{"app.js"}, + EntryPoints: []string{"app.jsx"}, Bundle: true, Platform: api.PlatformNode, - Packages: api.PackagesBundle, + Packages: api.PackagesExternal, Write: true, }) @@ -308,6 +309,10 @@ 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: >