Bun Bytecode Caching

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bytecode Caching

> Speed up JavaScript execution with bytecode caching in Bun's bundler

Bytecode caching is a build-time optimization that dramatically improves application startup time by pre-compiling your JavaScript to bytecode. For example, when compiling TypeScript's `tsc` with bytecode enabled, startup time improves by **2x**.

## Usage

### Basic usage (CommonJS)

Enable bytecode caching with the `--bytecode` flag. Without `--format`, this defaults to CommonJS:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build ./index.ts --target=bun --bytecode --outdir=./dist
```

This generates two files:

* `dist/index.js` - Your bundled JavaScript (CommonJS)
* `dist/index.jsc` - The bytecode cache file

At runtime, Bun automatically detects and uses the `.jsc` file:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun ./dist/index.js  # Automatically uses index.jsc
```

### With standalone executables

When creating executables with `--compile`, bytecode is embedded into the binary. Both ESM and CommonJS formats are supported:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# ESM (requires --compile)
bun build ./cli.ts --compile --bytecode --format=esm --outfile=mycli

# CommonJS (works with or without --compile)
bun build ./cli.ts --compile --bytecode --outfile=mycli
```

The resulting executable contains both the code and bytecode, giving you maximum performance in a single file.

### ESM bytecode

ESM bytecode requires `--compile` because Bun embeds module metadata (import/export information) in the compiled binary. This metadata allows the JavaScript engine to skip parsing entirely at runtime.

Without `--compile`, ESM bytecode would still require parsing the source to analyze module dependencies—defeating the purpose of bytecode caching.

### Combining with other optimizations

Bytecode works great with minification and source maps:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build --compile --bytecode --minify --sourcemap ./cli.ts --outfile=mycli
```

* `--minify` reduces code size before generating bytecode (less code -> less bytecode)
* `--sourcemap` preserves error reporting (errors still point to original source)
* `--bytecode` eliminates parsing overhead

## Performance impact

The performance improvement scales with your codebase size:

| Application size          | Typical startup improvement |
| ------------------------- | --------------------------- |
| Small CLI (\< 100 KB)     | 1.5-2x faster               |
| Medium-large app (> 5 MB) | 2.5x-4x faster              |

Larger applications benefit more because they have more code to parse.

## When to use bytecode

### Great for:

#### CLI tools

* Invoked frequently (linters, formatters, git hooks)
* Startup time is the entire user experience
* Users notice the difference between 90ms and 45ms startup
* Example: TypeScript compiler, Prettier, ESLint

#### Build tools and task runners

* Run hundreds or thousands of times during development
* Milliseconds saved per run compound quickly
* Developer experience improvement
* Example: Build scripts, test runners, code generators

#### Standalone executables

* Distributed to users who care about snappy performance
* Single-file distribution is convenient
* File size less important than startup time
* Example: CLIs distributed via npm or as binaries

### Skip it for:

* ❌ **Small scripts**
* ❌ **Code that runs once**
* ❌ **Development builds**
* ❌ **Size-constrained environments**

## Limitations

### Version compatibility

Bytecode is **not portable across Bun versions**. The bytecode format is tied to JavaScriptCore's internal representation, which changes between versions.

When you update Bun, you must regenerate bytecode:

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# After updating Bun
bun build --bytecode ./index.ts --outdir=./dist
```

If bytecode doesn't match the current Bun version, it's automatically ignored and your code falls back to parsing the JavaScript source. Your app still runs - you just lose the performance optimization.

**Best practice**: Generate bytecode as part of your CI/CD build process. Don't commit `.jsc` files to git. Regenerate them whenever you update Bun.

From jarle/bun-skills, MIT.

More from jarle/bun-skills