deno-to-bun

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 = new URL(req.url);

  if (url.pathname === "/") {
    return new Response("Hello");
  }

  return new Response("Not found", { status: 404 });
});

Bun:

Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);

    if (url.pathname === "/") {
      return new Response("Hello");
    }

    return new Response("Not found", { status: 404 });
  },
});

File Operations

Deno:

const file = await Deno.open("file.txt");
const decoder = new TextDecoder();
const content = decoder.decode(await Deno.readAll(file));
file.close();

Bun:

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

Environment Variables

Deno:

const apiKey = Deno.env.get("API_KEY");
Deno.env.set("NEW_VAR", "value");

Bun:

const apiKey = process.env.API_KEY;
process.env.NEW_VAR = "value";  // Note: Setting at runtime doesn't persist

Command Execution

Deno:

const command = new Deno.Command("ls", {
  args: ["-la"],
});
const { stdout } = await command.output();

Bun:

import { $ } from "bun";

const output = await $`ls -la`.text();

Verification Steps

Run these commands to verify migration:

# 1. Install dependencies
bun install

# 2. Type check
bun run --bun tsc --noEmit

# 3. Run tests
bun test

# 4. Try development server
bun run dev

# 5. Test production build (if applicable)
bun run build

Migration Checklist

Present this checklist to the user:

Bun installed and verified
Deno APIs mapped to Bun equivalents
deno.json converted to package.json
Import maps converted to npm dependencies
URL imports replaced with npm packages
File extensions added to imports
Permission flags removed (security reviewed)
Test framework migrated to bun:test
TypeScript configuration created
Dependencies installed with bun install
Tests passing with bun test
Application runs successfully
Documentation updated

Known Differences

Deno Features Not in Bun

Permission System: Bun has full system access
URL Imports: Must use npm packages or local files
Deno Deploy: Use Docker or other deployment (see bun-deploy skill)
Deno Namespace: No Deno.* APIs (use Bun/Node equivalents)
Built-in Formatter/Linter: Use separate tools (Biome, ESLint, Prettier)

Bun Advantages Over Deno

npm Ecosystem: Full access to npm packages
Performance: Faster startup and execution
Package Manager: Built-in package manager (3x faster than npm)
Native Bundler: Built-in bundler and transpiler
Jest Compatibility: Familiar testing API

Completion

Once migration is complete, provide summary:

✅ Migration status (success/partial/issues)
✅ List of changes made
✅ API conversions performed
✅ Any remaining manual steps
✅ Links to Bun documentation for ongoing development

Next Steps

Suggest to the user:

Review security implications (no permission system)
Update CI/CD pipelines for Bun
Consider containerization (bun-deploy skill)
Optimize with Bun-specific features
Update team documentation

About this skill

Quick Reference

Migration Workflow

1. Pre-Migration Analysis

2. API Compatibility Analysis

File System

HTTP Server

Environment Variables

Reading JSON

3. Configuration Migration

4. Import Map Conversion

5. Permission Model Changes

6. Update File Extensions and Imports

7. Testing Migration

8. Update package.json

9. Install Dependencies

10. Update TypeScript Configuration

Common Migration Patterns

HTTP Server

File Operations

Environment Variables

Command Execution

Verification Steps

Migration Checklist

Known Differences

Deno Features Not in Bun

Bun Advantages Over Deno

Completion

Next Steps