TailwindCSS plugin installation
To use TailwindCSS with Bun's dev server, install the bun-plugin-tailwind plugin with `bun install --dev bun-plugin-tailwind`, then add it to bunfig.toml under [serve.static] plugins.
bundler & build options
23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Plugin API for HTML preprocessing with HTMLRewriter
Configure the bundler through Bun.build()'s JavaScript API with a plugins array. Use Bun's built-in HTMLRewriter to preprocess HTML. Example: A plugin can use `new HTMLRewriter().on("*", { element(element) { element.tagName = element.tagName.toLowerCase(); }, text(element) { element.replace(element.text.toLowerCase()); } })` to transform HTML. The onLoad callback should return an object with contents (the transformed HTML) and loader: "html" so Bun's bundler will scan the HTML for scripts, stylesheets, and other assets to bundle automatically.
Plugin limitation in CLI vs API
Plugins are only supported through Bun.build()'s API or through bunfig.toml with the frontend dev server, not through bun build's CLI.
--define advantages over variable assignment
Using --define for constants enables dead code elimination, whereas setting a variable in code does not. Property accesses in JavaScript can have side effects through getters, setters, and dynamic definitions via prototype chains and Proxy objects, so static analysis tools cannot assume a variable's value remains constant across lines. Only --define provides statically-analyzable constants.
--define runtime usage
To use --define at runtime, pass the flag to bun with the syntax: bun --define IDENTIFIER=VALUE src/file.ts. For example: bun --define process.env.NODE_ENV="'production'" src/index.ts
--define in bun build
To use --define with bun build, pass the flag as: bun build --define IDENTIFIER=VALUE src/file.ts. For example: bun build --define process.env.NODE_ENV="'production'" src/index.ts
--define enables dead code elimination
Bun uses statically-known values from --define definitions for dead code elimination and other optimizations. Code branches that are unreachable based on the defined constants are removed during transpilation.
--define with string values
String values in --define must be quoted in the command line. For example: bun --define process.env.NODE_ENV="'production'" uses the outer double quotes for shell escaping and inner quotes to define a string literal.
--define with identifiers
The --define flag can replace identifiers with other identifiers without quotes. For example: bun --define global=globalThis replaces all usages of global with globalThis. Another example: bun --define window=undefined replaces window with undefined.
--define with JSON values
The --define flag can replace values with JSON objects and arrays. For example: bun --define AWS='{"ACCESS_KEY":"abc","SECRET_KEY":"def"}' src/index.ts replaces AWS with the JSON object. Bun transforms these into equivalent JavaScript code.
--define with property paths
The --define flag can replace properties with other properties. For example: bun --define console.write=console.log replaces all usages of console.write with console.log.
--minify-syntax enables constant folding
The --minify-syntax flag (also enabled by --minify) performs constant folding to collapse constant expressions and remove the surrounding scaffolding. For example, bun build --define process.env.NODE_ENV="'production'" --minify-syntax src/index.ts will reduce if (true) { ... } to just the executed statement.
--define operates on AST, not text
The --define flag operates on the Abstract Syntax Tree (AST), not on text. The replacement happens during transpilation and participates in optimizations like dead code elimination. This is different from find-and-replace or string replacement tools, which operate on text and can have escaping issues.
--define flag for constants and globals
The --define flag declares statically-analyzable constants and globals. It replaces all usages of an identifier or property in a JavaScript or TypeScript file with a constant value, and works both at runtime and in bun build. It is similar to #define in C/C++, but for JavaScript.
Build-time constants with bun build command example
bun build --define BUILD_VERSION='"1.0.0"' --define NODE_ENV='"production"' src/index.ts --outdir ./dist
Build-time constants with bun build --compile example
bun build --compile --define BUILD_VERSION='"1.0.0"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
Build-time constants value format rules
Bun parses each --define value as a JavaScript expression. Strings must be JSON-quoted: --define VERSION='"1.0.0"'. Numbers are JSON literals: --define PORT=3000. Booleans are JSON literals: --define DEBUG=true. Objects and arrays use single quotes: --define 'CONFIG={"host":"localhost","port":3000}' and --define 'FEATURES=["auth","billing","analytics"]'. Property access patterns are supported: --define 'process.env.NODE_ENV="production"' and --define 'window.myApp.version="1.0.0"'.
TypeScript declarations for build-time constants
For TypeScript projects, declare your build-time constants to avoid type errors. Example: declare const BUILD_VERSION: string; declare const BUILD_TIME: string; declare const NODE_ENV: "development" | "staging" | "production"; declare const DEBUG: boolean;
Cross-platform builds with --define and --target
When building for multiple platforms, use --target with --define. Examples: bun build --compile --target=bun-linux-x64 --define PLATFORM='"linux"' src/app.ts --outfile app-linux, bun build --compile --target=bun-darwin-x64 --define PLATFORM='"darwin"' src/app.ts --outfile app-macos, bun build --compile --target=bun-windows-x64 --define PLATFORM='"windows"' src/app.ts --outfile app-windows.exe.
Dynamic build-time constants from shell commands
Generate build-time constants from shell commands using bash command substitution. Example: bun build --compile --define BUILD_VERSION="\"$(git describe --tags --always)\"" --define BUILD_TIME="\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" --define GIT_COMMIT="\"$(git rev-parse HEAD)\"" src/cli.ts --outfile mycli
Build automation script using Bun shell
Create a build script that injects build metadata using Bun's $ shell command. Example: import { $ } from "bun"; const version = await $`git describe --tags --always`.text(); const buildTime = new Date().toISOString(); const gitCommit = await $`git rev-parse HEAD`.text(); await Bun.build({ entrypoints: ["./src/cli.ts"], outdir: "./dist", define: { BUILD_VERSION: JSON.stringify(version.trim()), BUILD_TIME: JSON.stringify(buildTime), GIT_COMMIT: JSON.stringify(gitCommit.trim()) } });
Dead code elimination with build-time constants
Build-time constants enable dead code elimination. When a conditional check uses a build-time constant that evaluates to false, the entire block is removed during compilation. Example: if (ENABLE_ANALYTICS) { /* this entire block is removed if ENABLE_ANALYTICS is false */ } becomes optimized away entirely.
--define flag for build-time constants with bun build
Use --define to inject build-time constants into your application with bun build or bun build --compile. Values are embedded directly into the compiled code at build time, providing zero runtime overhead, immutability, dead code elimination optimization, and security benefits.