How does Bun's bundler integrate with TypeScript and JSX

TypeScript Support in Bun

Bun supports executing TypeScript code directly, making it unnecessary to manually transpile TypeScript to JavaScript before running the code. When a TypeScript file is executed using Bun, it automatically performs the transpilation under the hood and runs the resulting JavaScript code. However, although Bun transpiles TypeScript at runtime, it does not perform type checking. The TypeScript compiler (`tsc`) still needs to be run separately if type checking is required. This separation allows developers to enjoy fast execution with Bun while still leveraging TypeScript's static type checking during development or CI processes.

TypeScript files (.ts) are compiled with respect to the project's `tsconfig.json` or `jsconfig.json` configuration, ensuring that the compilation respects the project's defined settings such as module resolution, target version, and other compiler options. This makes integrating TypeScript projects into Bun smooth and consistent with existing workflows.

JSX and TSX Support

Bun also supports JSX, including TSX (TypeScript + JSX) files, natively. The bundler includes an internal transpiler that converts JSX syntax into vanilla JavaScript before execution. This means React components or similar JSX constructs can be used freely without additional setup. Bun respects relevant configuration options from `tsconfig.json` or `jsconfig.json`, such as the `jsx` setting that dictates how JSX is transformed.

Key options that Bun honors during JSX transpilation include:

- `jsx`: Determines how JSX is transformed to JavaScript, such as `react`, `react-jsx`, or `react-jsxdev`.
- `jsxFactory`: Specifies the function used to create JSX elements, defaulting to `createElement`. This is useful for supporting libraries like Preact, which use different factory functions (e.g., `h`).
- `jsxFragmentFactory`: Defines the function representing JSX fragments (`...`), defaulting to `Fragment`.
- `jsxImportSource`: Used when the `jsx` setting is `react-jsx` or `react-jsxdev` to specify the source module for the JSX factory functions, defaulting to `react`.
- `jsxSideEffects`: Controls whether JSX expressions are marked as pure for tree shaking. By default, Bun marks JSX as pure to enable dead code elimination, but this can be disabled.

These options can also be set via the `bunfig.toml` configuration file or passed as CLI flags, offering flexible control over JSX transformation in Bun.

Bundling TypeScript and JSX with Bun

Bun's bundler allows the building of bundles starting from entry points that can be TypeScript or TSX files. When bundling, Bun uses its built-in transpiler to parse the input files and convert TypeScript and JSX syntax to vanilla JavaScript. The bundler also handles dependencies, recursively bundling all imported modules into the final output.

For example, given an entry point `index.tsx` that uses React and JSX syntax, a simple Bun build command will produce a JavaScript bundle:

ts
await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
});

The output will be a JavaScript file in the specified output directory, with all TypeScript and JSX transformed for browser compatibility. Bun automatically includes necessary React runtime functions for JSX handling (`jsxDEV` and `$createRoot` in the example from the docs) so the resulting bundle is ready to execute in the browser or server environment.

This bundling process respects the standard JavaScript module ecosystem and can include Node.js-compatible packages, enabling full-stack development workflows.

Configuration and Workflow

- Bun reads the standard `tsconfig.json` or `jsconfig.json` to get TypeScript and JSX-related compilers options.
- Developers do not need to install or configure separate transpilers like Babel or esbuild for TypeScript or JSX.
- Bundling can be done for single file projects or complex monorepos with many TypeScript files.
- Source maps can be generated inline, aiding in debugging.
- HTML plugins can be used alongside Bun's bundler to process HTML files when integrating TypeScript in web projects.

Limitations and Considerations

- Bun does not perform type checking during transpilation or bundling. Running the TypeScript compiler is still required for type validation.
- For interactive TypeScript REPL features, Bun currently does not support this; it only supports JavaScript REPL. For interactive TypeScript, developers use other tools like TSX.
- While Bun supports direct execution of TypeScript files and can compile and bundle them, some developers note that for large-scale enterprise setups, additional tooling might still be needed to handle complex build steps or integrations.

Additional Capabilities

- Bun can compile TypeScript and JavaScript projects into single executable binaries, packaging all dependencies, which is useful for distributing applications without requiring the runtime or dependencies on the target machine.
- The bundler is integrated with Bun's package manager and test runner, enabling a unified toolchain experience.
- Bun supports JSX transformation for alternative libraries by letting developers specify custom factory functions for JSX elements and fragments.