Bundle a TypeScript Project with Bun’s Built‑in Bundler

Desired outcome

Create a single JavaScript file (e.g., dist/main.js) that contains all of your TypeScript source code and its dependencies, ready to run with bun or Node.js while preserving ES module semantics and type‑checked correctness.

Prerequisites

1. Bun version 0.7 or newer installed globally or via your project’s bun wrapper.
2. A tsconfig.json in the project root with "module": "ESNext" (or "NodeNext") to emit ES modules.
3. All npm‑style dependencies installed via bun install (so node_modules exists).
4. An entry point file, conventionally src/index.ts, that exports or invokes the code you want to bundle.

Procedure

1. Verify TypeScript configuration

Open tsconfig.json and ensure the compilerOptions block contains:

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2020",
    "outDir": "dist",
    "sourceMap": true
  }
}

If you prefer not to generate source maps during the tsc step, you can omit "sourceMap": true; the Bun bundler will add its own if requested.

2. Run the Bun bundler

From the project root, execute:

bun bun --entry src/index.ts --outfile dist/main.js --minify

Explanation of flags:

• --entry – path to the TypeScript entry file.
• --outfile – destination for the bundled JavaScript.
• --minify – optional; removes whitespace and shortens identifiers for a smaller bundle.

To keep source maps for debugging, add --sourcemap:

bun bun --entry src/index.ts --outfile dist/main.js --minify --sourcemap

3. Inspect the generated bundle

After the command finishes, check that dist/main.js exists and is non‑empty. You can quickly view the first few lines:

head -n 5 dist/main.js

If you added --sourcemap, a companion file dist/main.js.map should also be present.

Expected checks

Runtime validation

Run the bundle with Bun to ensure it executes without errors:

bun dist/main.js

You should see the expected output of your program (e.g., console logs, HTTP server start, etc.). No stack trace or module‑not‑found errors should appear.

Bundle size and duplication

Inspect the size and verify that large dependencies are not duplicated unintentionally:

ls -lh dist/main.js
# optional: search for repeated patterns
grep -o 'from "[^"]*"' dist/main.js | sort | uniq -c | sort -nr

If a dependency appears many times, consider marking it as external (see recovery section).

Source map verification (if generated)

Open dist/main.js in a browser’s developer tools or use a source‑map viewer:

1. Load the bundle in a page or Node.js debugger that supports source maps.
2. Set a breakpoint on a line originating from your TypeScript source.
3. Confirm the debugger shows the original .ts file and line number.

Recovery options

Unsupported syntax or dynamic imports

If the bundler fails with an error about unsupported syntax (e.g., dynamic import() in a context Bun cannot resolve), you have two approaches:

1. Adjust tsconfig.json to target a newer ECMAScript version that Bun’s bundler understands, e.g., "target": "ES2022".
2. Exclude the problematic module from bundling using --external:

bun bun --entry src/index.ts --outfile dist/main.js --external problematic-pkg

Then ensure the external is available at runtime (it will be loaded from node_modules).

Large bundle size

If the bundle is unexpectedly large, check for inadvertent inclusion of entire node_modules trees:

• Add --no-node-modules to prevent Bun from walking the dependency tree.
• Alternatively, explicitly list large packages to externalize:

bun bun --entry src/index.ts --outfile dist/main.js --external lodash --external react

Minification breaking source maps

If you notice that source maps no longer line up after using --minify, repeat the bundling step without --minify to confirm the maps are correct. Then decide whether minification is required for your deployment.

Rollback

The bundling operation only creates files under dist/. To revert, simply delete the generated output:

rm -rf dist/main.js dist/*.map

No changes are made to node_modules or source files, so this is a safe rollback.

Summary

By following the steps above you can reliably bundle a TypeScript project with Bun’s built‑in bundler, validate the result, and address common pitfalls. Keep your tsconfig.json aligned with ES module output, use --external or --no-node-modules to control bundle size, and always verify the bundle runs before promoting it to production.