Bun 1.4.3 Adds bun check: How to Try Its TypeScript Checker

TypeScript catches many coding mistakes before an application runs, but checking a large project can take time. Bun 1.4.3 introduces bun check, a TypeScript type checker built into Bun that can check a project without installing the TypeScript package separately.

The command reads your tsconfig.json, checks TypeScript types, and reports errors in your source files. It does not generate JavaScript or declaration files. This makes it useful when you want to check code during development or add a type-checking step to your CI pipeline.

Bun's implementation is based on typescript-go and aims to match the diagnostics produced by TypeScript 7. Developers should still test it against their own projects before replacing an existing type-checking process.

What Is New in Bun 1.4.3?

Before this release, a common way to check a TypeScript project was to install TypeScript and run tsc --noEmit. The --noEmit option prevents the compiler from generating output files.

Bun 1.4.3 adds a built-in alternative for type checking.

There is an important distinction between checking code and compiling it. A project can pass bun check and still fail at runtime because of incorrect business logic, invalid API responses, or other problems that static type checking cannot detect.

1. Install or Upgrade Bun

First, check the version installed on your machine.

bun --version

If you already use Bun, upgrade it:

bun upgrade

Then verify the installed version again.

bun --version

Confirm that the output reports version 1.4.3 or a later version that includes the feature.

If Bun is not installed, use the installation method appropriate for your operating system. On Windows, for example, the PowerShell installer can be used:

powershell -c "irm bun.sh/install.ps1|iex"

After installation, open a new terminal if the bun command is not recognized.

For an existing application, create a separate Git branch before changing the development toolchain. This makes it easier to compare results and undo configuration changes if the new checker reports unexpected errors.

2. Create a Small TypeScript Example

You can try the checker in a new project or an existing TypeScript application.

Create a file named index.ts with the following code:

interface User {
    id: number;
    name: string;
}

function greet(user: User): string {
    return `Hello, ${user.name}`;
}

const user: User = {
    id: 101,
    name: "Anita"
};

console.log(greet(user));

The User interface defines the expected structure of a user object. Its id property must be a number, and its name property must be a string.

The greet function accepts a User and returns a string. This gives the type checker enough information to catch several common mistakes before the code runs.

For example, change the id value to a string:

const user: User = {
    id: "101",
    name: "Anita"
};

The assignment is invalid because the interface requires a number. A type checker should report the mismatch at this point.

3. Run the Type Checker

Run the following command from the project directory:

bun check

If the project has no type errors, Bun reports a successful check. If it finds an error, it prints the file location and diagnostic details.

A typical error looks like this:

error TS2322: Type 'string' is not assignable to type 'number'.

The exact output depends on the file and the error.

One detail matters when you try this in an existing project. If package.json already defines a script named check, the bun check command can run that script instead of the built-in type checker.

For example, this configuration uses check for a different tool:

{
  "scripts": {
    "check": "biome check"
  }
}

In that case, run the built-in checker explicitly:

bun --check

This avoids confusion between a project script and Bun's type-checking option. For a team project, naming the package script typecheck is also a practical way to make its purpose clear.

4. Configure TypeScript Types Correctly

Bun's checker reads the project's TypeScript configuration. If your application depends on Node.js types, Bun types, or React types, make sure the required declarations are installed and configured.

For a Bun application, install Bun's type declarations:

bun add -d @types/bun

Then configure tsconfig.json:

{
  "compilerOptions": {
    "types": ["bun"],
    "strict": true,
    "noEmit": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

The types option tells TypeScript which ambient type packages to include. The strict option enables stricter checks, while noEmit documents that the project does not expect compiler output from a normal type-checking step.

If your application also uses Node.js or React declarations, list those packages when required. Do not copy this configuration blindly into a project that already has carefully chosen compiler options.

Bun's checker follows TypeScript 7 behavior, including changes to compiler defaults. A project moving from an older TypeScript version may therefore see additional errors. Review the diagnostics and migration requirements before treating every new error as a regression.

5. Add Type Checking to Your Build Process

A type check is most useful when developers run it regularly instead of waiting for a release build to discover problems.

You can add a dedicated script to package.json:

{
  "scripts": {
    "typecheck": "bun --check"
  }
}

Run it with:

bun run typecheck

This creates a clear command for developers and CI systems. It also avoids a naming conflict with an existing check script.

For a GitHub Actions workflow, you can run the checker after installing the project's locked dependencies:

name: TypeScript Check

on:
  push:
  pull_request:

jobs:
  typecheck:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Check TypeScript
        run: bun --check

This example assumes the project uses Bun and has a valid Bun lock file. The frozen installation helps CI use the dependency versions recorded by the project instead of silently changing them.

A failed type check returns a nonzero exit code, allowing CI to reject a change that contains type errors. Keep your existing tests and build steps as well, because type checking does not replace them.

6. Understand the Limitations Before Replacing tsc

Bun's checker is designed to report the same errors as TypeScript 7. However, matching behavior is a compatibility goal, and complex projects should still be tested before switching tools.

There are several reasons to keep the existing compiler available during evaluation.

First, bun check does not generate JavaScript, declaration files, or TypeScript build information. If your publishing process generates .d.ts files for a library, you still need an appropriate compiler step.

Second, the checker uses a particular TypeScript version. Your editor may use a different version, which can cause it to show errors that the terminal does not report, or the other way around.

Third, projects that use project references or multiple packages need to be checked with the correct project configuration.

For a monorepo, use:

bun check -b

This follows project references and checks the referenced projects. To check one package, you can specify its path:

bun check -p packages/api

If your editor and terminal disagree, check the TypeScript version used by Bun:

bun -p process.versions.typescript

Then configure your editor to use a compatible workspace TypeScript version where appropriate.

Common Mistakes and Troubleshooting

The command runs the wrong tool

Check whether package.json defines a check script. Use bun --check to invoke the built-in checker explicitly.

The editor shows different errors

The editor may use a different TypeScript version. Align the editor with the version Bun uses, then run the checker again.

Type checking passes but the application fails

Static type checking cannot catch every runtime problem. Run unit tests, integration tests, and the normal build process before deploying the application.

The CI job fails after upgrading Bun

Check the dependency installation output, the selected Bun version, and the TypeScript diagnostics. Compare the results with the previous toolchain before changing compiler options to suppress errors.

Best Practices

• Test Bun's checker on a small branch before replacing the current type-checking command.

• Keep the lock file committed and use frozen dependency installation in CI.

• Use a dedicated typecheck script if the project already has a check script.

• Keep unit tests, integration tests, and build validation separate from type checking.

• Review new diagnostics when moving from an older TypeScript version.

• Verify declaration generation and project-reference behavior before removing tsc from a library build.

• Compare checker results on representative project files before making it a required CI gate.

Advantages and Disadvantages

Summary

Bun 1.4.3 adds bun check, a built-in TypeScript checker that reads project configuration and reports type errors without generating output files. It can simplify the type-checking step in local development and CI, especially for projects already using Bun.

Start by checking a small TypeScript file, then test the command against your existing project and dependency lock file. Pay attention to TypeScript version differences, project references, and any existing check script.

For many applications, Bun's checker can be a useful alternative to tsc --noEmit. Projects that generate declaration files or depend on other compiler features should retain the necessary TypeScript build steps until those requirements are covered.