prjct-cli 0.35.1 → 0.35.3

package/packages/shared/node_modules/@types/bun/node_modules/bun-types/docs/bundler/esbuild.mdx

@@ -1,298 +0,0 @@
----
-title: esbuild
-description: Migration guide from esbuild to Bun's bundler
----
-
-Bun's bundler API is inspired heavily by esbuild. Migrating to Bun's bundler from esbuild should be relatively painless. This guide will briefly explain why you might consider migrating to Bun's bundler and provide a side-by-side API comparison reference for those who are already familiar with esbuild's API.
-
-There are a few behavioral differences to note.
-
-<Note>
-  **Bundling by default.** Unlike esbuild, Bun always bundles by default. This is why the `--bundle` flag isn't
-  necessary in the Bun example. To transpile each file individually, use `Bun.Transpiler`.
-</Note>
-
-<Note>
-  **It's just a bundler.** Unlike esbuild, Bun's bundler does not include a built-in development server or file watcher.
-  It's just a bundler. The bundler is intended for use in conjunction with `Bun.serve` and other runtime APIs to achieve
-  the same effect. As such, all options relating to HTTP/file watching are not applicable.
-</Note>
-
-## Performance
-
-With a performance-minded API coupled with the extensively optimized Zig-based JS/TS parser, Bun's bundler is 1.75x faster than esbuild on esbuild's three.js benchmark.
-
-<Info>Bundling 10 copies of three.js from scratch, with sourcemaps and minification</Info>
-
-## CLI API
-
-Bun and esbuild both provide a command-line interface.
-
-```bash terminal icon="terminal"
-# esbuild
-esbuild <entrypoint> --outdir=out --bundle
-
-# bun
-bun build <entrypoint> --outdir=out
-```
-
-In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Other flags like `--outdir <path>` do accept an argument; these flags can be written as `--outdir out` or `--outdir=out`. Some flags like `--define` can be specified several times: `--define foo=bar --define bar=baz`.
-
-| esbuild                | bun build                  | Notes                                                                                                                                                                                                                                                                                                                                                               |
-| ---------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bundle`             | n/a                        | Bun always bundles, use `--no-bundle` to disable this behavior.                                                                                                                                                                                                                                                                                                     |
-| `--define:K=V`         | `--define K=V`             | Small syntax difference; no colon.<br/>`esbuild --define:foo=bar`<br/>`bun build --define foo=bar`                                                                                                                                                                                                                                                                  |
-| `--external:<pkg>`     | `--external <pkg>`         | Small syntax difference; no colon.<br/>`esbuild --external:react`<br/>`bun build --external react`                                                                                                                                                                                                                                                                  |
-| `--format`             | `--format`                 | Bun supports `"esm"` and `"cjs"` currently, but more module formats are planned. esbuild defaults to `"iife"`.                                                                                                                                                                                                                                                      |
-| `--loader:.ext=loader` | `--loader .ext:loader`     | Bun supports a different set of built-in loaders than esbuild; see Bundler > Loaders for a complete reference. The esbuild loaders `dataurl`, `binary`, `base64`, `copy`, and `empty` are not yet implemented.<br/><br/>The syntax for `--loader` is slightly different.<br/>`esbuild app.ts --bundle --loader:.svg=text`<br/>`bun build app.ts --loader .svg:text` |
-| `--minify`             | `--minify`                 | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--outdir`             | `--outdir`                 | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--outfile`            | `--outfile`                | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--packages`           | `--packages`               | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--platform`           | `--target`                 | Renamed to `--target` for consistency with tsconfig. Does not support `neutral`.                                                                                                                                                                                                                                                                                    |
-| `--serve`              | n/a                        | Not applicable                                                                                                                                                                                                                                                                                                                                                      |
-| `--sourcemap`          | `--sourcemap`              | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--splitting`          | `--splitting`              | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--target`             | n/a                        | Not supported. Bun's bundler performs no syntactic down-leveling at this time.                                                                                                                                                                                                                                                                                      |
-| `--watch`              | `--watch`                  | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--allow-overwrite`    | n/a                        | Overwriting is never allowed                                                                                                                                                                                                                                                                                                                                        |
-| `--analyze`            | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--asset-names`        | `--asset-naming`           | Renamed for consistency with naming in JS API                                                                                                                                                                                                                                                                                                                       |
-| `--banner`             | `--banner`                 | Only applies to js bundles                                                                                                                                                                                                                                                                                                                                          |
-| `--footer`             | `--footer`                 | Only applies to js bundles                                                                                                                                                                                                                                                                                                                                          |
-| `--certfile`           | n/a                        | Not applicable                                                                                                                                                                                                                                                                                                                                                      |
-| `--charset=utf8`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--chunk-names`        | `--chunk-naming`           | Renamed for consistency with naming in JS API                                                                                                                                                                                                                                                                                                                       |
-| `--color`              | n/a                        | Always enabled                                                                                                                                                                                                                                                                                                                                                      |
-| `--drop`               | `--drop`                   |                                                                                                                                                                                                                                                                                                                                                                     |
-| n/a                    | `--feature`                | Bun-specific. Enable feature flags for compile-time dead-code elimination via `import { feature } from "bun:bundle"`                                                                                                                                                                                                                                                |
-| `--entry-names`        | `--entry-naming`           | Renamed for consistency with naming in JS API                                                                                                                                                                                                                                                                                                                       |
-| `--global-name`        | n/a                        | Not applicable, Bun does not support `iife` output at this time                                                                                                                                                                                                                                                                                                     |
-| `--ignore-annotations` | `--ignore-dce-annotations` |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--inject`             | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--jsx`                | `--jsx-runtime <runtime>`  | Supports `"automatic"` (uses jsx transform) and `"classic"` (uses `React.createElement`)                                                                                                                                                                                                                                                                            |
-| `--jsx-dev`            | n/a                        | Bun reads `compilerOptions.jsx` from `tsconfig.json` to determine a default. If `compilerOptions.jsx` is `"react-jsx"`, or if `NODE_ENV=production`, Bun will use the jsx transform. Otherwise, it uses `jsxDEV`. The bundler does not support `preserve`.                                                                                                          |
-| `--jsx-factory`        | `--jsx-factory`            |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--jsx-fragment`       | `--jsx-fragment`           |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--jsx-import-source`  | `--jsx-import-source`      |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--jsx-side-effects`   | n/a                        | JSX is always assumed to be side-effect-free                                                                                                                                                                                                                                                                                                                        |
-| `--keep-names`         | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--keyfile`            | n/a                        | Not applicable                                                                                                                                                                                                                                                                                                                                                      |
-| `--legal-comments`     | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--log-level`          | n/a                        | Not supported. This can be set in `bunfig.toml` as `logLevel`.                                                                                                                                                                                                                                                                                                      |
-| `--log-limit`          | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--log-override:X=Y`   | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--main-fields`        | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--mangle-cache`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--mangle-props`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--mangle-quoted`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--metafile`           | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--minify-whitespace`  | `--minify-whitespace`      |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--minify-identifiers` | `--minify-identifiers`     |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--minify-syntax`      | `--minify-syntax`          |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--out-extension`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--outbase`            | `--root`                   |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--preserve-symlinks`  | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--public-path`        | `--public-path`            |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--pure`               | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--reserve-props`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--resolve-extensions` | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--servedir`           | n/a                        | Not applicable                                                                                                                                                                                                                                                                                                                                                      |
-| `--source-root`        | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--sourcefile`         | n/a                        | Not supported. Bun does not support stdin input yet.                                                                                                                                                                                                                                                                                                                |
-| `--sourcemap`          | `--sourcemap`              | No differences                                                                                                                                                                                                                                                                                                                                                      |
-| `--sources-content`    | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--supported`          | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                       |
-| `--tree-shaking`       | n/a                        | Always true                                                                                                                                                                                                                                                                                                                                                         |
-| `--tsconfig`           | `--tsconfig-override`      |                                                                                                                                                                                                                                                                                                                                                                     |
-| `--version`            | n/a                        | Run `bun --version` to see the version of Bun.                                                                                                                                                                                                                                                                                                                      |
-
-## JavaScript API
-
-| esbuild.build()     | Bun.build()                | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `absWorkingDir`     | n/a                        | Always set to `process.cwd()`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `alias`             | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `allowOverwrite`    | n/a                        | Always false                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `assetNames`        | `naming.asset`             | Uses same templating syntax as esbuild, but `[ext]` must be included explicitly.<br/><br/>`ts<br/>Bun.build({<br/>  entrypoints: ["./index.tsx"],<br/>  naming: {<br/>    asset: "[name].[ext]",<br/>  },<br/>});<br/>`                                                                                                                                                                                                                                                                |
-| `banner`            | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `bundle`            | n/a                        | Always true. Use `Bun.Transpiler` to transpile without bundling.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `charset`           | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `chunkNames`        | `naming.chunk`             | Uses same templating syntax as esbuild, but `[ext]` must be included explicitly.<br/><br/>`ts<br/>Bun.build({<br/>  entrypoints: ["./index.tsx"],<br/>  naming: {<br/>    chunk: "[name].[ext]",<br/>  },<br/>});<br/>`                                                                                                                                                                                                                                                                |
-| `color`             | n/a                        | Bun returns logs in the `logs` property of the build result.                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `conditions`        | n/a                        | Not supported. Export conditions priority is determined by `target`.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `define`            | `define`                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `drop`              | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `entryNames`        | `naming` or `naming.entry` | Bun supports a `naming` key that can either be a string or an object. Uses same templating syntax as esbuild, but `[ext]` must be included explicitly.<br/><br/>`ts<br/>Bun.build({<br/>  entrypoints: ["./index.tsx"],<br/>  // when string, this is equivalent to entryNames<br/>  naming: "[name].[ext]",<br/><br/>  // granular naming options<br/>  naming: {<br/>    entry: "[name].[ext]",<br/>    asset: "[name].[ext]",<br/>    chunk: "[name].[ext]",<br/>  },<br/>});<br/>` |
-| `entryPoints`       | `entrypoints`              | Capitalization difference                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `external`          | `external`                 | No differences                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `footer`            | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `format`            | `format`                   | Only supports `"esm"` currently. Support for `"cjs"` and `"iife"` is planned.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `globalName`        | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `ignoreAnnotations` | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `inject`            | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `jsx`               | `jsx`                      | Not supported in JS API, configure in `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `jsxDev`            | `jsxDev`                   | Not supported in JS API, configure in `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `jsxFactory`        | `jsxFactory`               | Not supported in JS API, configure in `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `jsxFragment`       | `jsxFragment`              | Not supported in JS API, configure in `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `jsxImportSource`   | `jsxImportSource`          | Not supported in JS API, configure in `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `jsxSideEffects`    | `jsxSideEffects`           | Not supported in JS API, configure in `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `keepNames`         | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `legalComments`     | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `loader`            | `loader`                   | Bun supports a different set of built-in loaders than esbuild; see Bundler > Loaders for a complete reference. The esbuild loaders `dataurl`, `binary`, `base64`, `copy`, and `empty` are not yet implemented.                                                                                                                                                                                                                                                                         |
-| `logLevel`          | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `logLimit`          | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `logOverride`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `mainFields`        | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `mangleCache`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `mangleProps`       | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `mangleQuoted`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `metafile`          | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `minify`            | `minify`                   | In Bun, `minify` can be a boolean or an object.<br/><br/>`ts<br/>await Bun.build({<br/>  entrypoints: ['./index.tsx'],<br/>  // enable all minification<br/>  minify: true<br/><br/>  // granular options<br/>  minify: {<br/>    identifiers: true,<br/>    syntax: true,<br/>    whitespace: true<br/>  }<br/>})<br/>`                                                                                                                                                               |
-| `minifyIdentifiers` | `minify.identifiers`       | See `minify`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `minifySyntax`      | `minify.syntax`            | See `minify`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `minifyWhitespace`  | `minify.whitespace`        | See `minify`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `nodePaths`         | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `outExtension`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `outbase`           | `root`                     | Different name                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `outdir`            | `outdir`                   | No differences                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `outfile`           | `outfile`                  | No differences                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `packages`          | n/a                        | Not supported, use `external`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `platform`          | `target`                   | Supports `"bun"`, `"node"` and `"browser"` (the default). Does not support `"neutral"`.                                                                                                                                                                                                                                                                                                                                                                                                |
-| `plugins`           | `plugins`                  | Bun's plugin API is a subset of esbuild's. Some esbuild plugins will work out of the box with Bun.                                                                                                                                                                                                                                                                                                                                                                                     |
-| `preserveSymlinks`  | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `publicPath`        | `publicPath`               | No differences                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `pure`              | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `reserveProps`      | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `resolveExtensions` | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `sourceRoot`        | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `sourcemap`         | `sourcemap`                | Supports `"inline"`, `"external"`, and `"none"`                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `sourcesContent`    | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `splitting`         | `splitting`                | No differences                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `stdin`             | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `supported`         | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `target`            | n/a                        | No support for syntax downleveling                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `treeShaking`       | n/a                        | Always true                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `tsconfig`          | n/a                        | Not supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `write`             | n/a                        | Set to true if `outdir`/`outfile` is set, otherwise false                                                                                                                                                                                                                                                                                                                                                                                                                              |
-
-## Plugin API
-
-Bun's plugin API is designed to be esbuild compatible. Bun doesn't support esbuild's entire plugin API surface, but the core functionality is implemented. Many third-party esbuild plugins will work out of the box with Bun.
-
-<Note>
-  Long term, we aim for feature parity with esbuild's API, so if something doesn't work please file an issue to help us
-  prioritize.
-</Note>
-
-Plugins in Bun and esbuild are defined with a builder object.
-
-```ts title="myPlugin.ts" icon="/icons/typescript.svg"
-import type { BunPlugin } from "bun";
-
-const myPlugin: BunPlugin = {
-  name: "my-plugin",
-  setup(builder) {
-    // define plugin
-  },
-};
-```
-
-The builder object provides some methods for hooking into parts of the bundling process. Bun implements `onResolve` and `onLoad`; it does not yet implement the esbuild hooks `onStart`, `onEnd`, and `onDispose`, and `resolve` utilities. `initialOptions` is partially implemented, being read-only and only having a subset of esbuild's options; use `config` (same thing but with Bun's `BuildConfig` format) instead.
-
-```ts title="myPlugin.ts" icon="/icons/typescript.svg"
-import type { BunPlugin } from "bun";
-const myPlugin: BunPlugin = {
-  name: "my-plugin",
-  setup(builder) {
-    builder.onResolve(
-      {
-        /* onResolve.options */
-      },
-      args => {
-        return {
-          /* onResolve.results */
-        };
-      },
-    );
-    builder.onLoad(
-      {
-        /* onLoad.options */
-      },
-      args => {
-        return {
-          /* onLoad.results */
-        };
-      },
-    );
-  },
-};
-```
-
-### onResolve
-
-<Tabs>
-  <Tab title="options">
-
-    - 🟢 `filter`
-    - 🟢 `namespace`
-
-  </Tab>
-  <Tab title="arguments">
-
-    - 🟢 `path`
-    - 🟢 `importer`
-    - 🔴 `namespace`
-    - 🔴 `resolveDir`
-    - 🔴 `kind`
-    - 🔴 `pluginData`
-
-  </Tab>
-  <Tab title="results">
-
-    - 🟢 `namespace`
-    - 🟢 `path`
-    - 🔴 `errors`
-    - 🔴 `external`
-    - 🔴 `pluginData`
-    - 🔴 `pluginName`
-    - 🔴 `sideEffects`
-    - 🔴 `suffix`
-    - 🔴 `warnings`
-    - 🔴 `watchDirs`
-    - 🔴 `watchFiles`
-
-  </Tab>
-</Tabs>
-
-### onLoad
-
-<Tabs>
-  <Tab title="options">
-
-    - 🟢 `filter`
-    - 🟢 `namespace`
-
-  </Tab>
-  <Tab title="arguments">
-  
-    - 🟢 `path`
-    - 🔴 `namespace`
-    - 🔴 `suffix`
-    - 🔴 `pluginData`
-
-  </Tab>
-  <Tab title="results">
-
-    - 🟢 `contents`
-    - 🟢 `loader`
-    - 🔴 `errors`
-    - 🔴 `pluginData`
-    - 🔴 `pluginName`
-    - 🔴 `resolveDir`
-    - 🔴 `warnings`
-    - 🔴 `watchDirs`
-    - 🔴 `watchFiles`
-
-  </Tab>
-</Tabs>