Bunflare

0.2.25 verified Sat May 09 auth: no javascript

Bunflare v0.2.25 is a Bun bundler plugin that transforms Bun-native APIs (e.g., Bun.serve, bun:sqlite, Bun.password.hash) into Cloudflare Workers equivalents at build time. It targets developers who want Bun's DX but need to deploy to Cloudflare Workers. Key differentiators: zero runtime overhead (transform happens at build time), no code changes required for the developer, supports auto-discovery from wrangler.jsonc, and covers a wide range of Bun APIs including D1, KV, R2, Hyperdrive, WebCrypto, Workers Assets, and fullstack builds. Released as a dev dependency, it requires Bun >=1.0.0 and optionally integrates with Hono and Drizzle ORM. The package ships with TypeScript types. The project is actively maintained with recent commits.

Common errors

error ReferenceError: Bun is not defined ↓

cause Trying to run Bun-specific code in a Cloudflare Workers environment without building with Bunflare.

fix

Ensure your build step uses 'bun bunflare' or the Bunflare plugin, and deploy the output bundle (not the source).

error Cannot find module 'bunflare' or its corresponding type declarations. ↓

cause Bunflare not installed or missing in tsconfig's 'types' or 'includes'.

fix

Run 'bun add -d bunflare' and ensure your tsconfig includes node_modules/@types or the package types.

error SyntaxError: Unexpected token 'export' ↓

cause Attempting to require() an ESM-only package with CommonJS require() in Node.js.

fix

Switch to ESM (use import statements) or use a dynamic import: const bunflare = await import('bunflare')

error Binding 'DB' not found in environment ↓

cause Cloudflare Worker doesn't have a D1 binding named 'DB', or the binding name in bunflare.config.ts doesn't match the deployed binding.

fix

Verify the binding name in wrangler.jsonc and your config match. Also check that the D1 database is created and bound in Cloudflare dashboard.

error Type 'BunflareConfig' is not assignable to type 'BunflareConfig' (different namespaces) ↓

cause Type conflict when importing BunflareConfig from both bunflare and another module that re-exports it.

fix

Use import type { BunflareConfig } from 'bunflare' consistently and avoid re-exporting from other files.

Warnings

breaking Bunflare v0.2.x requires Bun >=1.0.0. Older Bun versions may produce errors or fail to load the plugin. ↓

fix Upgrade Bun to >=1.0.0 and bunflare to latest.

breaking Bunflare transforms Bun.serve into Cloudflare Workers fetch handler. If your Bun.serve uses advanced features (e.g., TLS options, unix sockets), those will not work on Workers and build may fail. ↓

fix Avoid TLS/unix socket options in Bun.serve. Use regular HTTP/HTTPS or omit options.

deprecated The `bunflare` CLI command is being phased out in favor of `bun bunflare`. Running `npx bunflare` may produce deprecation warnings. ↓

fix Use `bun bunflare` (if using Bun) or add a script in package.json: "build": "bun bunflare".

gotcha Bunflare automatically discovers bindings from wrangler.jsonc. If the file is missing or misconfigured, bindings (D1, KV, R2) will not work at runtime on Workers. ↓

fix Ensure wrangler.jsonc exists with correct binding names. Use explicit config in bunflare.config.ts if needed.

gotcha TypeScript type augmentation for Bun.env requires a manual global.d.ts and running 'wrangler types'. Without it, TypeScript errors appear on Bun.env.KEY usage. ↓

fix Create global.d.ts with the snippet from the readme and run 'wrangler types' to generate worker-configuration.d.ts.

gotcha Using bun:sqlite with Drizzle ORM requires drizzle-orm as peer dependency. Not installing it will cause runtime errors when SQL queries are executed via Drizzle on D1. ↓

fix Install drizzle-orm: bun add drizzle-orm

Install

npm install bunflare

yarn add bunflare

pnpm add bunflare

Imports

default (BunflareConfig type)

wrong

import { BunflareConfig } from 'bunflare' // BunflareConfig is a type, not a value

correct

import type { BunflareConfig } from 'bunflare'

BunflareConfig is a TypeScript type, imported with 'import type' to avoid runtime errors.

default (plugin)

wrong

const bunflare = require('bunflare') // Bunflare is ESM-only, require() fails

correct

import bunflare from 'bunflare'

The package is ESM-only. Use import statement.

CloudflareBindings (interface)

wrong

import { CloudflareBindings } from 'bunflare' // CloudflareBindings is not exported from bunflare

correct

interface CloudflareBindings { } // augmented by 'wrangler types' into worker-configuration.d.ts

CloudflareBindings is a global interface you declare yourself, often populated by 'wrangler types' generation.

Quickstart

Shows minimal setup: install as devDep, create config with entrypoint, write standard Bun code, build with `bun bunflare`.

// Install: bun add -d bunflare

// bunflare.config.ts
import type { BunflareConfig } from 'bunflare';

export default {
  entrypoint: './index.ts',
  // Optional: bindings are auto-discovered from wrangler.jsonc
  // sqlite: { binding: 'DB' },
} satisfies BunflareConfig;

// index.ts (source code, unchanged)
Bun.serve({
  port: 3000,
  fetch(request) {
    return new Response('Hello from Bun!');
  },
});

// Build command:
// bun bunflare
// Outputs Cloudflare Worker-compatible bundle to dist/worker.js