cli/bundle

27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

deno bundle command overview

The `deno bundle` command outputs a single JavaScript file with all dependencies. It is powered by ESBuild under the hood and is useful for deploying or distributing a project as a single optimized JS file. This is an experimental feature requiring Deno 2.4.0 or newer.

deno bundle supported features

deno bundle supports: resolving and inlining all dependencies, JSX/TSX, TypeScript, and modern JavaScript including import attributes and CSS, HTML entrypoint support (Deno 2.5+), optional minification (--minify) and source maps (--sourcemap), code splitting, platform targeting (--platform, supports Deno and browser), and JSX support when configured.

deno bundle basic usage

Basic usage: `deno bundle main.ts > bundle.js` or `deno bundle -o bundle.js main.ts`. You can use JSR, npm, http(s) and local imports in the file being bundled.

deno bundle CLI flags

Flags for deno bundle: `-o`, `--output <file>` (write bundled output to a file), `--outdir <dir>` (write bundled output to a directory), `--minify` (minify the output for production), `--format <format>` (output format, esm by default), `--code-splitting` (enable code splitting), `--platform <platform>` (bundle for browser or deno, default: deno), `--sourcemap` (include source maps: linked, inline, or external), `--watch` (automatically rebuild on file changes), `--inline-imports` (inline imported modules: true or false), `--packages <how>` (how to handle packages: bundle (default) or external), `--external <pkg>` (exclude a module or package from the bundle), `--keep-names` (keep original function and class names).

deno bundle HTML entrypoint support

Starting with Deno 2.5, `deno bundle` supports HTML files as entrypoints. When using an HTML file as an entrypoint, deno bundle will: find all script references in the HTML file, bundle those scripts and their dependencies, update the paths in the HTML file to point to the bundled scripts, and bundle and inject any imported CSS files into the HTML output. The bundled output includes content-based hashes for cache-busting and fingerprinting.

deno bundle HTML entrypoint example

When bundling HTML entrypoints with `deno bundle --outdir dist index.html`, if index.html references `./index.tsx` with `<script src="./index.tsx" type="module"></script>`, the output becomes: ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Example</title> <script src="./index-2TFDJWLF.js" type="module" crossorigin></script> <link rel="stylesheet" crossorigin href="./index-EWSJYQGA.css"> </head> </html> ``` The bundled scripts and stylesheets include content-based hashes.

deno bundle vs deno compile

To produce a standalone binary rather than a JavaScript file, use `deno compile`, which can also bundle and minify its input with the `--bundle` and `--minify` flags.

Bundle React page for web example

Example of bundling a React app for the web. With `app.jsx` and `index.html`, run `deno bundle --platform=browser app.jsx -o bundle.js` to produce a browser-optimized bundle. The output can then be served using `deno run -ENR jsr:@std/http/file-server` to test the app.

deno bundle basic usage

The basic command to bundle a module is 'deno bundle -o output.js main.ts'. Without the -o/--output flag, the bundle is written to standard output. The output file can then be run with Deno or in other JavaScript runtimes using 'deno run output.js'.

deno bundle --platform flag

The --platform flag targets a platform for bundling. Valid values are 'deno' (default) or 'browser'.

deno bundle --minify flag

The --minify flag shrinks the bundle output by minifying the code.

deno bundle --sourcemap flag

The --sourcemap flag emits source maps alongside the bundled output.

deno bundle --code-splitting flag

The --code-splitting flag splits shared code into separate chunks. It must be used with an output directory specified via --outdir.

deno bundle --outdir flag

The --outdir flag specifies an output directory for the bundle. This is used with --code-splitting to write multiple chunks or with --declaration to write TypeScript declaration files.

deno bundle --external flag

The --external flag keeps a dependency out of the bundle. Example usage: 'deno bundle --external npm:sharp -o output.js main.ts' excludes npm:sharp from the final bundle.

deno bundle --declaration flag

The --declaration flag generates TypeScript declarations alongside the JavaScript output. Deno rolls up the types for each entry point into a single self-contained .d.ts file. Example: 'deno bundle main.ts --outdir dist --declaration' produces dist/main.js and dist/main.d.ts.

deno bundle --check flag

The --check flag enables type-checking during bundling. Use '--check' to type-check local modules only, or '--check=all' to also type-check remote modules. By default, deno bundle does not type-check.

deno bundle --no-check flag

The --no-check flag explicitly skips type-checking. Use '--no-check=remote' to ignore diagnostics from remote modules only.

deno bundle browser platform and browser field

When bundling with --platform=browser, Deno honors the npm 'browser' field in a dependency's package.json, including its object form. The object maps modules to browser-specific replacements: a relative-path key remaps a resolved file to a browser-specific one, a bare-specifier key remaps an import, and a value of false excludes the module by substituting an empty stub.

deno bundle overview

deno bundle combines a module and all of its dependencies into a single JavaScript file using esbuild under the hood. It is useful for deploying or distributing a project as a single optimized file, but is not currently intended as a replacement for complex or interactive build tools such as Vite or webpack. The command is currently experimental and subject to changes.

deno compile --bundle flag

The --bundle flag runs your entrypoint through the bundler before embedding, so only the code your program actually reaches ends up in the binary. This is experimental and subject to change. For projects with many npm dependencies, this reduces binary size and startup time. Example: deno compile --bundle main.ts

deno compile --bundle tree-shaking

For a pure-ESM dependency tree, tree-shaking removes everything unused and the npm payload is dropped entirely, producing a much smaller binary. When a CommonJS package or native addon (.node) is reached, the relevant packages are embedded so they keep working at runtime, but unreached packages are still left out.

deno compile --bundle automatic pattern handling

--bundle understands several real-world patterns automatically: CommonJS and native addons—CJS dependencies and .node native addons are detected and the packages that provide them are embedded. Workers—new Worker(new URL('./worker.ts', import.meta.url), ...) calls are discovered, each worker is bundled separately and embedded. package.json reads—packages that read their own package.json at runtime have it included automatically.

deno compile --bundle with --minify

Combine --bundle with --minify to minify the bundled output. This reduces both the embedded bundle size and runtime memory use, at the cost of less readable stack traces. Example: deno compile --bundle --minify main.ts. --minify is only meaningful together with --bundle.

deno compile --bundle limitations

Because bundling relies on statically analyzing your code, patterns that cannot be traced are dropped from the binary: Dynamic require() / import() of specifiers that aren't string literals, and Workers spawned with computed URLs or spawned from transitive dependencies rather than your own source. If your program relies on these, keep them statically analyzable, add files with --include, or compile without --bundle.

--unstable-bundle flag

The --unstable-bundle flag enables the unstable Deno.bundle runtime API for bundling JavaScript and TypeScript programmatically.

esbuild example for bundling replacement

Example bundling with esbuild and esbuild-deno-loader: import * as esbuild from "npm:esbuild"; import { denoPlugins } from "jsr:@luca/esbuild-deno-loader"; const result = await esbuild.build({ plugins: [...denoPlugins()], entryPoints: ["./main.ts"], outfile: "./dist/bytes.esm.js", bundle: true, format: "esm", }); esbuild.stop();

Give your agent this brain