From ccf70086543a034495834b4135e15e91a3ffceb8 Mon Sep 17 00:00:00 2001
From: Evan Wallace
- 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=
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: '