> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bun guide

> This guide will show you how to setup Trigger.dev in your existing Bun project, test an example task, and view the run.

> [!WARNING]
>
> The trigger.dev CLI does not yet support Bun. So you will need to run the CLI using Node.js. Bun
> will still be used to execute your tasks, even in the `dev` environment.

> [!WARNING]
>
> **`runtime: "bun"` is deprecated.** It deploys on Bun 1.3.3 with a Node.js 20 binary alongside it
> (`bun-legacy` is the same runtime). Deploys that use it will be rejected from **January 5, 2027**.
> Switch to `runtime: "bun-1.4"` (Bun 1.4.4) and redeploy; already-deployed versions keep their
> original image until you do. For local development, match the Bun minor you deploy on.

## Choosing a Bun runtime

| `runtime` | Bun | Node.js binary in the image | Notes |
| - | - | - | - |
| `bun-1.4` | 1.4.4 | No | Recommended. Bun-only image. See the Bun 1.4 note below. |
| `bun` | 1.3.3 | Yes (Node.js 20) | Deprecated, also spelled `bun-legacy`. Rejected from January 5, 2027. |

The `bun-1.4` image contains **no Node.js binary**. Anything in your task that spawns
`node` (a CLI tool, a `postinstall` script, a library that shells out) will fail on it. Install
Node.js yourself with a build extension before moving those projects off `bun`.

> [!NOTE]
>
> **Bun 1.4:** Bun 1.4.x has an open regression in its `node:http2` client
> ([oven-sh/bun#39796](https://github.com/oven-sh/bun/issues/39796)). If your tasks use HTTP/2
> clients, for example some gRPC or Google Cloud SDKs, you can stay on `bun` until it is fixed,
> but no later than January 5, 2027.

## Prerequisites

* Setup a project in Bun
* Ensure TypeScript is installed
* [Create a Trigger.dev account](https://cloud.trigger.dev)
* Create a new Trigger.dev project

## Known issues

* Certain OpenTelemetry instrumentation will not work with Bun, because Bun does not support Node's `register` hook. This means that some libraries that rely on this hook will not work with Bun.
* If Bun is installed via Homebrew (e.g. `/opt/homebrew/bin/bun`), you may see an `ENOENT: spawn /Users/<you>/.bun/bin/bun` error because the CLI expects Bun at the default install path. **Workaround:** create a symlink:
  ```bash theme={"theme":"css-variables"}
  mkdir -p ~/.bun/bin && ln -s $(which bun) ~/.bun/bin/bun
  ```
* Bun's WebSocket client does not handle the `101 Switching Protocols` upgrade response correctly, so connecting to a remote browser via `puppeteer.connect()` / `playwright.connectOverCDP()` (e.g. BrowserBase, Browserless) fails silently — typically with an empty `{}` `ErrorEvent`. The remote session opens and immediately drops. **Workaround:** set `runtime: "node"` in `trigger.config.ts` for tasks that connect to a remote browser.

## Initial setup

**1. Run the CLI `init` command**

The easiest way to get started is to use the CLI. It will add Trigger.dev to your existing project, create a `/trigger` folder and give you an example task.

Run this command in the root of your project to get started:

```bash npm theme={"theme":"css-variables"}
npx trigger.dev@latest init --runtime bun-1.4
```

```bash pnpm theme={"theme":"css-variables"}
pnpm dlx trigger.dev@latest init --runtime bun-1.4
```

```bash yarn theme={"theme":"css-variables"}
yarn dlx trigger.dev@latest init --runtime bun-1.4
```

It will do a few things:

1. Log you into the CLI if you're not already logged in.
2. Create a `trigger.config.ts` file in the root of your project.
3. Ask where you'd like to create the `/trigger` directory.
4. Create the `/src/trigger` directory with an example task, `/src/trigger/example.[ts/js]`.

Install the "Hello World" example task when prompted. We'll use this task to test the setup.

**2. Update example.ts to use Bun**

Open the `/src/trigger/example.ts` file and replace the contents with the following:

```ts example.ts theme={"theme":"css-variables"}
import { Database } from "bun:sqlite";
import { task } from "@trigger.dev/sdk";

export const bunTask = task({
  id: "bun-task",
  run: async (payload: { query: string }) => {
    const db = new Database(":memory:");
    const query = db.query("select 'Hello world' as message;");
    console.log(query.get()); // => { message: "Hello world" }

    return {
      message: "Query executed",
    };
  },
});

```

**3. Run the CLI `dev` command**

The CLI `dev` command runs a server for your tasks. It watches for changes in your `/trigger` directory and communicates with the Trigger.dev platform to register your tasks, perform runs, and send data back and forth.

It can also update your `@trigger.dev/*` packages to prevent version mismatches and failed deploys. You will always be prompted first.

```bash npm theme={"theme":"css-variables"}
npx trigger.dev@latest dev
```

```bash pnpm theme={"theme":"css-variables"}
pnpm dlx trigger.dev@latest dev
```

```bash yarn theme={"theme":"css-variables"}
yarn dlx trigger.dev@latest dev
```

**4. Perform a test run using the dashboard**

The CLI `dev` command spits out various useful URLs, including a link to the dashboard. Open it, find your Example task on the Tasks page, and press the "Test" button to open its test page.

Most tasks have a "payload" which you enter in the JSON editor, but our example task doesn't need any input. You can also configure run options, pre-populate the form from recent runs, and save run templates.

Press the "Run test" button.

![Test page](https://mintcdn.com/trigger/2gGDaV8FR4pPhx_f/images/test-dashboard.png?fit=max\&auto=format\&n=2gGDaV8FR4pPhx_f\&q=85\&s=9a7c31f3499500be59e62586763e03d1)

**5. View your run**

Congratulations, you should see the run page which will live reload showing you the current state of the run.

![Run page](https://mintcdn.com/trigger/5SxX7bFjJKRsidSL/images/run-page.png?fit=max\&auto=format\&n=5SxX7bFjJKRsidSL\&q=85\&s=4b0bb5f9b181499cf324cdb8d5d673a8)

If you go back to your terminal you'll see that the dev command also shows the task status and links to the run log.

![Terminal showing completed run](https://mintcdn.com/trigger/0bD0UfsjaINxS6Tw/images/terminal-completed-run.png?fit=max\&auto=format\&n=0bD0UfsjaINxS6Tw\&q=85\&s=a9284c5228343b72d798c6e36f5acb24)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.