Deno to Bun Migration

You are assisting with migrating an existing Deno project to Bun. This involves converting Deno APIs, updating configurations, and adapting to Bun's runtime model.

Quick Reference

For detailed patterns, see:

• API Mapping: api-mapping.md - Deno.* to Bun equivalents
• Permissions: permissions.md - Permission model differences

Migration Workflow

1. Pre-Migration Analysis

Check if Bun is installed:

bun --version

Analyze current Deno project:

# Check Deno version
deno --version

# Check for deno.json/deno.jsonc
ls -la | grep -E "deno.json|deno.jsonc"

# List permissions used
grep -r "deno run" .

Read deno.json or deno.jsonc to understand the project configuration.

2. API Compatibility Analysis

Common Deno APIs and their Bun equivalents:

File System

// Deno
const text = await Deno.readTextFile("file.txt");
await Deno.writeTextFile("file.txt", "content");

// Bun
const text = await Bun.file("file.txt").text();
await Bun.write("file.txt", "content");

HTTP Server

// Deno
Deno.serve({ port: 3000 }, (req) => {
  return new Response("Hello");
});

// Bun
Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello");
  },
});

Environment Variables

// Deno
const value = Deno.env.get("KEY");

// Bun (same as Node.js)
const value = process.env.KEY;

Reading JSON

// Deno
const data = await Deno.readTextFile("data.json");
const json = JSON.parse(data);

// Bun
const json = await Bun.file("data.json").json();

For complete API mapping, see api-mapping.md.

3. Configuration Migration

Convert deno.json to package.json and bunfig.toml:

deno.json:

{
  "tasks": {
    "dev": "deno run --allow-net --allow-read main.ts",
    "test": "deno test"
  },
  "imports": {
    "oak": "https://deno.land/x/oak@v12.6.1/mod.ts"
  },
  "compilerOptions": {
    "lib": ["deno.window"]
  }
}

package.json (Bun):

{
  "name": "my-bun-project",
  "type": "module",
  "scripts": {
    "dev": "bun run --hot main.ts",
    "test": "bun test"
  },
  "dependencies": {
    "hono": "^3.0.0"
  }
}

bunfig.toml:

[test]
preload = ["./tests/setup.ts"]

4. Import Map Conversion

Deno imports:

// Deno - URL imports
import { serve } from "https://deno.land/std@0.200.0/http/server.ts";
import { oak } from "https://deno.land/x/oak@v12.6.1/mod.ts";

Bun imports:

// Bun - npm packages
import { Hono } from "hono";
// Or for std library equivalents, use npm packages

Common replacements:

• deno.land/std/http → hono or native Bun.serve
• deno.land/x/oak → hono or express
• deno.land/std/testing → bun:test
• deno.land/std/path → Node.js path module

5. Permission Model Changes

Deno permissions:

deno run --allow-read --allow-write --allow-net main.ts

Bun (no permission system):

bun run main.ts  # Full system access by default

Security implications:

• Bun has no permission system like Deno
• Review code for security concerns
• Use environment variables for sensitive operations
• Consider running in containers for isolation

For detailed permission migration, see permissions.md.

6. Update File Extensions and Imports

Deno allows extension-less imports:

// Deno
import { helper } from "./utils";  // Resolves to utils.ts

Bun requires extensions:

// Bun
import { helper } from "./utils.ts";  // Explicit extension

7. Testing Migration

Deno test:

import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

Deno.test("example", () => {
  assertEquals(1 + 1, 2);
});

Bun test:

import { test, expect } from "bun:test";

test("example", () => {
  expect(1 + 1).toBe(2);
});

8. Update package.json

Create or update package.json:

{
  "name": "migrated-from-deno",
  "type": "module",
  "scripts": {
    "dev": "bun run --hot main.ts",
    "start": "bun run main.ts",
    "test": "bun test"
  },
  "dependencies": {
    "hono": "^3.0.0"
  }
}

9. Install Dependencies

# Remove deno.lock if present
rm deno.lock

# Install Bun dependencies
bun install

10. Update TypeScript Configuration

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"],
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}

Common Migration Patterns

HTTP Server

Deno:

Deno.serve({ port: 3000 }, (req) => {
  const url

...