Bun Check Explained: Type-Check TypeScript Before You Run, Test or Build

Nothing stops it. Bun removes the type annotations and runs the JavaScript that is left, so a type mistake turns into a wrong answer at runtime instead of an error. That gap is what bun check closes.

Picture a common setup. A small food-delivery backend stores each order amount in paise, where 100 paise make one rupee. One order arrives from a form as the text "19900" instead of the number 19900. The setup is made up, but the bug is real and we ran it.

The total function adds 49900 and "19900". In JavaScript, adding a number to a string joins them as text. So the code divides "4990019900" by 100 and prints 49900199 rupees, instead of 698. Here is src/order.ts, followed by src/index.ts, where line 5 holds the mistake.

export interface Order {
  id: string;
  amountPaise: number;
}

export function totalRupees(orders: Order[]): number {
  return orders.reduce((sum, o) => sum + o.amountPaise, 0) / 100;
}

import { totalRupees, type Order } from "./order.js";

const orders: Order[] = [
  { id: "A1", amountPaise: 49900 },
  { id: "A2", amountPaise: "19900" },
];

const label: string = totalRupees(orders);
console.log(label);

TypeScript knows amountPaise must be a number, so it can catch this before anyone sees the bill. There is a second, smaller mistake too: label is declared as a string, but totalRupees returns a number.

Yet running bun src/index.ts on Bun 1.4.4 printed 49900199 and exited with code 0, which means success. Before Bun 1.4.3, teams ran tsc as a separate step to catch this. Now one command, bun check, finds both mistakes and stops with exit code 1. You will see its exact output in the section on running it.

You need seven terms: type checker, tsc, tsconfig.json, emit, error code, exit code and pipe. Each gets a plain meaning below, tied to the order example.

• Type checker: a program that reads code and checks that values match their declared types. It flags "19900" because amountPaise is declared as a number.
• tsc: the TypeScript compiler from the typescript npm package. Running tsc --noEmit only checks types, which is the job bun check copies.
• tsconfig.json: the settings file for a TypeScript project. It says which files to check and how strict to be.
• Emit: writing output files, such as compiled JavaScript or .d.ts type declaration files. Bun check never emits anything.
• Error code: a stable number for each kind of TypeScript error. TS2322 means a value's type is not assignable to the expected type.
• Exit code: the number a command returns when it ends. Zero means success, and anything else means failure. CI, short for continuous integration, is the server that tests every code change and reads this number to pass or fail it.
• Pipe: sending one command's output into another program or a file instead of the screen. Standard output and standard error are a command's two output channels, one for results and one for messages.

Bun check is a TypeScript type checker inside the Bun binary. The Bun 1.4.3 release post calls it a port of typescript-go, the native TypeScript 7 compiler. It says bun check passes all 51,210 of TypeScript 7.0.2's conformance tests, the compiler's own tests of how it must behave.

It finds the nearest tsconfig.json, loads every file that config includes, and checks them on all CPU cores. You do not need the typescript package installed. In our test project, node_modules had no typescript folder and bun check still worked.

Think of it like a ticket checker at a railway gate. Every passenger, which is every file, shows a ticket, which is its types, before boarding the train, which is running the code. Where the picture breaks: a real checker looks at one ticket at a time, while bun check compares files against each other through their imports.

We confirmed both early exits on 1.4.4. A tsconfig.json with baseUrl failed with TS5102 and the note "Stopped before type checking 1 file". A file with a broken expression failed with TS1109, and no type errors were reported until it was fixed.

Install Bun's type declarations, list them in tsconfig.json, then run bun check in the project folder. The steps below are what we ran on Bun 1.4.4.

1. 1

   Pin your Bun version

   Run npm i -D --save-exact [email protected], then run it as npx bun check or from a package.json script. Plain bun uses whichever Bun is first on your PATH.

2. 2

   Add Bun's types

   Run bun add -d @types/bun, or npm i -D @types/bun if you use npm. Without it, names like Bun and bun:test are unknown. In our test without the package, bun check also printed a note telling us to install it.

3. 3

   List the types in tsconfig.json

   Set compilerOptions.types to ["bun"]. TypeScript 7 loads no global type packages unless they are listed there.

4. 4

   Run the checker

   Run bun check in the folder with tsconfig.json. Use bun check -p packages/api to check another project folder.

5. 5

   Read the exit code

   Run echo $? straight after, or echo $LASTEXITCODE in PowerShell. You should see 0 for a clean project and 1 when any error was found.

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "types": ["bun"]
  },
  "include": ["src"]
}

On the order example, bun check printed exactly the same two error lines as tsc 7.0.2 in pipe mode, which --no-pretty forces. Only the last line is extra, and the timing in brackets will differ on your machine.

$ bun check --no-pretty
src/index.ts(5,15): error TS2322: Type 'string' is not assignable to type 'number'.
src/index.ts(8,7): error TS2322: Type 'number' is not assignable to type 'string'.
Found 2 errors in 1 file, checked 2 files [89.68ms]
$ echo $?
1

Each line reads as file, then line and column in brackets, then the error code and message. Line 5, column 15 is the amountPaise property that received the "19900" string, and line 8 is label. We changed "19900" to 19900 and wrote totalRupees(orders).toFixed(2), which returns a string. Bun check then printed "No type errors in 2 files" and exited 0.

Bun check picks its output style from where it is running. In a terminal it shows source code around each error. In a pipe it prints one line per error, like tsc --pretty false.

The streams matter in scripts. Bun check sends error lines to standard output and the summary line to standard error. We checked this by hiding each stream in turn. A grep on the error output will not see the summary. When only standard output is piped, the summary can appear on screen before the errors.

In terminal mode, more than 50 identical errors are grouped. Our file with 60 copies of the same mistake showed one excerpt and the line "60 times in this file". Add --all to see every one, and add --timing to print load and check times.

For checking, bun check aims to be a drop-in for tsc --noEmit with the same TypeScript 7 rules, with two documented exceptions listed under limits below. The differences are in what else each tool does, and we ran every row below on Bun 1.4.4 and tsc 7.0.2.

Keep tsc when you publish a library and need .d.ts files. Bun's docs also tell you to install the TypeScript version Bun reports. On both 1.4.3 and 1.4.4, bun -e "console.log(process.versions.typescript)" printed 7.0.2.

TypeScript 7 defaults catch people coming from TypeScript 5

Bun check follows TypeScript 7, so its defaults apply. A tsconfig.json without a strict setting still reported TS7006, an implicit any parameter, in both tools. Strict mode is on unless you turn it off.

Old options now fail outright. On our sample, baseUrl gave TS5102 and moduleResolution node gave TS5108, in both bun check and tsc. Bun's docs list target es5 and some module values as removed too.

It type checks first and only continues when there are no errors. On an error it prints the errors, exits with 1 and runs nothing, so the wrong bill from the order example never prints.

We ran all four forms on Bun 1.4.4 and got the same stop-on-error result each time:

• bun --check src/index.ts and bun run --check src/index.ts: errors printed, exit 1, nothing ran.
• bun build --check src/index.ts --outdir out: errors printed, exit 1, and no out folder was created.
• Bun.build with check: true in a build script: by default it threw an error listing both TS2322 errors and wrote nothing. With throw: false it returned success: false, with the errors in its logs.
• bun --watch --check src/index.ts: after we broke the file during the watch, it re-checked and printed the error instead of restarting the program.

Trap one: bun test --check only checks what the tests import

Our order.test.ts imported order.ts but not index.ts, which still held both errors. Running bun test --check passed and ran the test, while bun check on the whole project failed. The docs describe this scope, but it is easy to miss.

Trap two: computed imports are not followed

A file that loaded a module with import(name), where name was built from strings, passed bun --check and ran. The loaded module held a type error that only the full bun check caught. Workers and require calls are also outside the check, per Bun's docs.

Because Bun treats bun check like a script name when package.json has a script called check. That script runs instead of the type checker, on both Bun 1.4.3 and 1.4.4.

We added a check script that only printed a message. Both versions printed the message and exited 0, without checking any types. That is a silent pass in CI, because the job looks green while the order bug is still there.

Bun 1.4.4 added --no-script, which forces the type checker. On 1.4.4, bun check --no-script reported the two errors and exited 1. On 1.4.3 the flag does not exist, and it was passed to the script as a plain argument.

It follows project references, which are links in tsconfig.json from one project to the projects it depends on. It reads referenced projects straight from source, so nothing needs building first.

We built a two-package monorepo where api imports a function from shared. Running bun check -b found the error in api and wrote no files. Running tsc -b found the same error but wrote dist output and two .tsbuildinfo files, which are tsc's build cache.

• Root config with only references: plain bun check followed them anyway and said so in a note.
• No tsconfig.json at or above the folder: it listed the nested configs, suggested bun check -p or bun check ., and exited 1.
• No tsconfig.json anywhere: it used built-in defaults with strict on, and still reported an implicit any.
• An empty folder: it printed "Nothing to check" and exited 1, so a wrong working directory fails loudly.

Checking one file is narrower than it looks. Running bun check src/order.ts passed, because order.ts imports nothing broken. The errors lived in index.ts, which was outside that run.

Bun reports it as several times faster than tsc 7.0.2, and 1.4.4 as faster again on large projects. These are Bun's own benchmarks, so treat them as claims to test on your code.

We also timed our own small run, labelled as ours. The machine was a Linux x86_64 container with 2 virtual CPUs at 2.8 GHz and 7 GB of memory. The project was 2,000 generated files with simple types.

Over five rounds, Bun 1.4.4 took 0.27 to 0.44 seconds, Bun 1.4.3 took 0.32 to 0.41 seconds, and tsc 7.0.2 took 0.97 to 1.50 seconds. That is roughly three times faster on this synthetic project, with only two cores to share.

The 1.4.4 post also lists costs. Bun's own src/js folder got slower, from 0.11 to 0.20 seconds. Monorepos of large projects can use more memory, because -b now checks up to 16 small projects at once instead of 4.

It only checks types, and it can still disagree with tsc in rare cases. These limits come from Bun's docs and release posts, and we ran the ones we could.

• No emit: no JavaScript, .d.ts files, source maps or .tsbuildinfo, so there is no incremental cache between runs either.
• No language server: editors still need the typescript package for red squiggles and hover types.
• Known mismatches: the 1.4.3 post reports 1,102 of 1,103 configs matching tsc across 72 deliberately misconfigured repositories. Under 11 other option sets, 751 of 752 runs matched, and the one that differed had strict turned off.
• Extra errors: Bun's docs say tsc can drop an error that a later file raises in an earlier one, while bun check reports it.
• Ignored setups: Bun's docs say it ignores tsconfig plugins and does not support Yarn Plug'n'Play, so Yarn projects need nodeLinker node-modules.
• Behaviour changes: 1.4.4 stopped reporting TS2321, a deep-comparison error, following TypeScript 7.1, so the same code can pass on 1.4.4 and fail on 1.4.3 or on tsc 7.0.2.

Bun's checker is young and changes fast between releases. Pin the Bun version in package.json and CI, and treat a Bun upgrade like a TypeScript upgrade. Bun asks for mismatches with tsc to be reported on its GitHub issues.

Frame it as a build-pipeline question: where does type safety get enforced, and what does it cost in time? Use the order-total bug as your one example.

1. 1

   State the gap

   Bun and similar runtimes strip types and run the code, so a type mistake becomes a wrong result, like a 49900199 rupee bill.

2. 2

   Name the gate

   A type checker such as bun check or tsc --noEmit checks types before code runs, and its exit code fails the pipeline.

3. 3

   Place it in the pipeline

   Run a full project check in CI, and a fast --check guard before local runs, tests and builds.

4. 4

   Call out the scope traps

   Test-only checks and computed imports skip files, so the full check is the source of truth.

5. 5

   Talk about trust

   Speed numbers are vendor claims, so measure on your own repository. Pin versions, because checker rules change between releases.

6. 6

   Say what you keep

   Keep the typescript package for .d.ts output and the editor, and use bun check for fast checking.