Running the Repo with Bun

I know the feeling of staring at a terminal while waiting for a runtime to catch up with my changes. It gets even more complicated when you want to try a new tool but don’t want to mess up the team’s shared lockfile or established pnpm workflow. If you want to try a faster local workflow without ditching pnpm, you can use Bun as an optional runtime.

I recommend using Bun for local development when you want to run TypeScript files directly. However, keep it local for now. It is not recommended for production Gateway runtimes because of bugs with WhatsApp and Telegram. Stick to Node for those production environments.

What You’ll Need

• Bun installed on your local machine.
• Node 22 or higher (required for some dependency checks).

Quick Start

You can get started with Bun in about five minutes. It runs alongside pnpm without causing repo churn because the Bun lockfile is ignored by git.

First, install your dependencies:

bun install

If you want to ensure that no lockfile is written at all, use this flag:

bun install --no-save

Once your packages are ready, you can build the project or run tests:

bun run build
bun run vitest run

Troubleshooting

Lifecycle scripts are blocked

Bun might block dependency lifecycle scripts by default. In this repo, common scripts like the @whiskeysockets/baileys preinstall check or protobufjs postinstall are usually not required. If you encounter a runtime issue that needs these scripts, you can trust them manually:

bun pm trust @whiskeysockets/baileys protobufjs

Scripts that require pnpm

You might find that some scripts still have pnpm hardcoded into them. This includes commands like docs:build, ui:*, or protocol:check. If a script fails under Bun because it expects pnpm, just run that specific command using pnpm for now.

Production issues

If you see unexpected behavior in WhatsApp or Telegram integrations, switch back to Node. Bun is currently an experimental option and is not recommended for the Gateway runtime.

If you run into other specific setup issues, check the AI Setup Assistant for help.

What’s Next

• Production Deployment Guide
• Local Development Workflow