Bun's bundler supports a range of file types out of the box, with particular loaders designed to handle these files appropriately during the bundling process. Here is a detailed explanation of the file types supported by Bun's bundler:
JavaScript and TypeScript Files:
The bundler supports multiple JavaScript and TypeScript file extensions including .js, .jsx, .cjs, .mjs, .mts, .cts, .ts, and .tsx. Bun uses its built-in transpiler to parse these files and transpile TypeScript and JSX syntax to plain JavaScript. This enables the bundler to handle modern JavaScript features and TypeScript seamlessly. It also applies default transforms such as dead code elimination and tree shaking. However, Bun does not currently down-convert JavaScript syntax, so if modern ECMAScript features are used, they will remain in the output bundle.
JSON and TOML Files:
JSON and TOML files are parsed and inlined into the bundle as JavaScript objects. This means the contents of these files become part of the JavaScript output, accessible as objects in the code.
Text Files:
Text files are read and inlined into the bundle as strings. This is useful when importing plain text content into JavaScript modules.
Node and WebAssembly Files:
Files with .node and .wasm extensions are supported by the Bun runtime but during the bundling process, they are treated as assets. This means they are not transpiled or parsed but rather copied into the output directory and referenced as external assets.
Other Asset Files:
For files with unrecognized extensions, Bun treats these as external files by default. This includes assets such as images or other media files. The bundler copies these files as-is into the output directory and resolves the import as a path string to the copied file. For example, importing a .svg file results in the SVG being copied with a hashed filename, and the import in the JavaScript code resolves to a string path pointing to that file. The naming and public path behavior of these assets can be customized.
Advanced Loader Customization:
Bun allows overriding and extending the default file loader behavior through plugins, offering flexibility in how files are handled beyond the standard set of loaders.
Summary of Built-in Loaders:
- .js, .jsx, .cjs, .mjs, .mts, .cts, .ts, .tsx: Transpiled with built-in transpiler (TypeScript/JSX support).
- .json, .toml: Parsed and inlined as JavaScript objects.
- .txt: Inlined as strings.
- .node, .wasm: Treated as assets and copied to output.
- Files with other/unrecognized extensions: Treated as external assets, copied as-is, and referenced by path.
Additional Notes:
- Bun also supports importing YAML files directly, parsed into JavaScript objects.
- Bun's experimental support for WASI WebAssembly binaries allows running certain .wasm files.
- Bun has special handling for SQLite database files, which can be imported to return a Database object.
- The bundler supports module formats like ES modules (default), CommonJS (experimental), and immediately invoked function expressions (IIFE) experimentally.
This support enables Bun's bundler to cover a wide array of common file types encountered in web and backend JavaScript/TypeScript projects, without additional configuration, aiming for zero-config experience with fast builds and native support for modern JavaScript features.
The capabilities span source code files, configuration data files, static assets, and binary modules, with customization options available to tailor the bundling behavior as needed.
References for this information include the official Bun documentation at bun.com, which details the bundler's loaders, module formats, asset handling, and runtime file support. This resource outlines the practical implications of Bun's handling of these file types and the extensibility available via plugins for advanced use cases.