loaders & file handling

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

--loader syntax and unsupported loaders

Bun uses --loader .ext:loader syntax (not --loader:.ext=loader). Bun supports a different set of built-in loaders than esbuild. The esbuild loaders dataurl, binary, base64, copy, and empty are not implemented in Bun.

loader parameter in Bun.build() JS API

In Bun.build() JavaScript API, loader maps the same as esbuild but Bun supports a different set of built-in loaders. Bun does not implement the esbuild loaders dataurl, binary, base64, copy, and empty.

loader option maps file extensions to built-in loaders

The loader option is a map of file extensions to built-in loader names. Use this to customize how certain files are loaded. Example: loader: { '.png': 'dataurl', '.txt': 'file' }

Loader types supported by Bun bundler

Supported loader types: js, jsx, ts, tsx, css, json, jsonc, toml, yaml, text, file, napi, wasm, html

Text file import as string

Text files (.txt) have their contents read and inlined into the bundle as a string. For example: import contents from './file.txt' provides the file contents.

Asset imports with unrecognized extensions

If the bundler encounters an import with an unrecognized extension, it treats the imported file as an external file. The bundler copies the referenced file as-is into outdir and resolves the import as a path to the file. Exact behavior depends on naming and publicPath options.

HTML bundling with asset references

HTML files are processed and any referenced assets (scripts, stylesheets, images) are bundled.

JSON and JSONC files inlined as objects

JSON and JSONC files are parsed and inlined into the bundle as JavaScript objects. For example: import pkg from './package.json' makes pkg.name available.

TOML files inlined as objects

TOML files are parsed and inlined into the bundle as JavaScript objects. For example: import config from './bunfig.toml' makes config.logLevel available.

YAML files inlined as objects

YAML files are parsed and inlined into the bundle as JavaScript objects. For example: import config from './config.yaml' makes config.name available.

Supported loaders for bundler content types

The bundler supports: .js/.jsx/.cjs/.mjs/.mts/.cts/.ts/.tsx (transpiled), .json/.jsonc (parsed and inlined), .toml/.yaml/.yml (parsed and inlined), .txt (inlined as string), .html (processed with assets bundled), .css (bundled to single file), .node/.wasm (treated as assets)

JavaScript transpilation and default transforms

For .js/.jsx/.ts/.tsx files, Bun uses its built-in transpiler to parse and transpile TypeScript/JSX to vanilla JavaScript. The bundler executes a set of default transforms including dead code elimination and tree shaking. Bun does not down-convert syntax; recent ECMAScript syntax appears as-is in the bundled code.

Loader types available

The Loader type can be one of: 'js', 'jsx', 'ts', 'tsx', 'json', 'jsonc', 'toml', 'yaml', 'file', 'napi', 'wasm', 'text', 'css', or 'html'.

napi loader for .node files

Native addon loader is the default for .node files in the runtime. Native addons can be directly imported in the runtime. In the bundler, Bun handles .node files with the file loader.

sqlite loader requirements and usage

SQLite loader requires the 'type: sqlite' import attribute. In the runtime and bundler, SQLite databases can be directly imported with: import db from "./my.db" with { type: "sqlite" }; The sqlite loader is only supported when the target is bun. By default, Bun does not bundle the database file into the final output. You can change this with the 'embed: true' attribute: import db from "./my.db" with { type: "sqlite", embed: "true" }; With a standalone executable, Bun embeds the database into the single-file executable. Otherwise, the database is copied into outdir with a hashed filename.

html loader behavior and asset bundling

HTML loader is the default for .html files. The html loader processes HTML files and bundles any referenced assets. It bundles and hashes referenced JavaScript files (<script src>), bundles and hashes referenced CSS files (<link rel="stylesheet" href>), hashes referenced images (<img src>), and preserves external URLs (by default, anything starting with http:// or https://). The loader uses lol-html to extract script and link tags as entrypoints, and other assets as external.

html loader supported selectors

The html loader supports these selectors: audio[src], img[src], img[srcset], link[as='font'][href], link[type^='font/'][href], link[as='image'][href], link[as='style'][href], link[as='video'][href], link[as='audio'][href], link[as='worker'][href], link[rel='icon'][href], link[rel='apple-touch-icon'][href], link[rel='manifest'][href], link[rel='stylesheet'][href], script[src], source[src], source[srcset], video[poster], video[src].

html loader behavior in different contexts

The html loader behaves differently depending on context. Static Build: when you run 'bun build ./index.html', Bun produces a static site with all assets bundled and hashed. Runtime: when you run 'bun run server.ts' (where server.ts imports an HTML file), Bun bundles assets on the fly during development, enabling features like hot module replacement. Full-stack Build: when you run 'bun build --target=bun server.ts' (where server.ts imports an HTML file), the import resolves to a manifest object that Bun.serve uses to serve pre-bundled assets in production.

css loader behavior

CSS loader is the default for .css files. CSS files can be directly imported. The bundler parses and bundles them, handling @import statements and url() references. During bundling, Bun combines all imported CSS files into a single .css file in the output directory.

sh loader for shell scripts

Bun Shell loader is the default for .sh files. This loader parses Bun Shell scripts. It's only supported when starting Bun itself, so it's not available in the bundler or in the runtime.

file loader for unrecognized file types

File loader is the default for all unrecognized file types. It resolves the import as a path/URL to the imported file. In the runtime, Bun checks that the file exists and resolves the import to its absolute path on disk. In the bundler, Bun copies the file into outdir as-is, and the import resolves to a relative path pointing to the copied file.

file loader publicPath configuration

The file loader uses the publicPath setting to construct paths. If publicPath is set, the import uses its value as a prefix. With publicPath = '' (default), resolved import is './logo.svg'. With publicPath = '/assets/', resolved import is '/assets/logo.svg'. With publicPath = 'https://cdn.example.com/', resolved import is 'https://cdn.example.com/logo.svg'. The value of naming.asset determines the location and file name of the copied file.

Built-in loaders supported by Bun bundler

Bun supports the following file types by default: .js, .cjs, .mjs, .mts, .cts, .ts, .tsx, .jsx, .css, .json, .jsonc, .json5, .toml, .yaml, .yml, .xml, .txt, .text, .md, .markdown, .wasm, .node, .html, .sh. The bundler and runtime support the same set of file types.

How to specify a loader explicitly with import attributes

Use the 'type' import attribute to specify a loader explicitly. Example: import my_toml from "./my_file" with { type: "toml" }; or with dynamic imports: const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

js loader behavior

JavaScript loader is the default for .cjs and .mjs files. It parses the code and applies default transforms like dead-code elimination and tree shaking. Bun does not down-convert syntax.

jsx loader behavior

JavaScript + JSX loader is the default for .js and .jsx files. Same as the js loader, but JSX syntax is supported. By default, Bun down-converts JSX to plain JavaScript. The exact output depends on the jsx* compiler options in tsconfig.json.

ts loader behavior

TypeScript loader is the default for .ts, .mts, and .cts files. Strips out all TypeScript syntax, then behaves identically to the js loader. Bun does not perform typechecking.

tsx loader behavior

TypeScript + JSX loader is the default for .tsx files. Transpiles both TypeScript and JSX to vanilla JavaScript.

json loader behavior and bundling

JSON loader is the default for .json files. JSON files can be directly imported. During bundling, Bun inlines the parsed JSON into the bundle as a JavaScript object. If you pass a .json file as an entrypoint to the bundler, Bun converts it to a .js module that export defaults the parsed object.

jsonc loader behavior

JSON with Comments loader is the default for .jsonc files. JSONC files can be directly imported. Bun parses them, stripping out comments and trailing commas. During bundling, Bun inlines the parsed JSONC into the bundle as a JavaScript object. Bun automatically uses the jsonc loader for tsconfig.json, jsconfig.json, package.json, and bun.lock files.

toml loader behavior and bundling

TOML loader is the default for .toml files. TOML files can be directly imported. Bun parses them with its native TOML parser. During bundling, Bun inlines the parsed TOML into the bundle as a JavaScript object. If you pass a .toml file as an entrypoint, Bun converts it to a .js module that export defaults the parsed object.

yaml loader behavior and bundling

YAML loader is the default for .yaml and .yml files. YAML files can be directly imported. Bun parses them with its native YAML parser. During bundling, Bun inlines the parsed YAML into the bundle as a JavaScript object. If you pass a .yaml or .yml file as an entrypoint, Bun converts it to a .js module that export defaults the parsed object.

xml loader behavior and bundling

XML loader is the default for .xml files. XML files can be directly imported. Bun parses them with its native XML 1.0 parser into the compact object shape of Bun.XML.parse. The structure includes: one key for the root element, '@name' keys for attributes, arrays for repeated child elements, '#text' for text next to attributes or children, and every value is a string. During bundling, Bun inlines the parsed XML into the bundle as a JavaScript object.

text loader behavior

Text loader is the default for .txt and .text files. Text files can be directly imported. Bun reads the file and returns it as a string. During bundling, Bun inlines the contents into the bundle as a string. If you pass a .txt file as an entrypoint, Bun converts it to a .js module that export defaults the file contents.

Give your agent this brain