Bun في الإنتاج: ما يعمل، وما لا يعمل، وما فاجأني

# حذف node_modules وإعادة التثبيت من الصفر
 
# npm (v10):
time npm install
# real 34.2s
 
# pnpm (v9):
time pnpm install
# real 12.1s
 
# bun (v1.1):
time bun install
# real 4.3s

# التثبيت الدافئ (node_modules محذوفة، المخزن المؤقت يبقى)
 
# npm:
time npm install
# real 18.7s
 
# pnpm:
time pnpm install
# real 4.8s
 
# bun:
time bun install
# real 0.9s

# يمكنك تفريغ ملف القفل بصيغة قابلة للقراءة
bun bun.lockb > lockfile-dump.txt
 
# أو استخدام الإخراج النصي المدمج
bun install --yarn
# هذا يولّد yarn.lock بجانب bun.lockb

{
  "name": "my-monorepo",
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

# تثبيت التبعيات لجميع مساحات العمل
bun install
 
# تشغيل سكربت في مساحة عمل محددة
bun run --filter packages/shared build
 
# إضافة تبعية لمساحة عمل محددة
bun add react --filter apps/web

# الخطوة 1: حذف ملف القفل و node_modules الحالية
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
 
# الخطوة 2: التثبيت باستخدام Bun
bun install
 
# الخطوة 3: التحقق من أن تطبيقك لا يزال يعمل
bun run dev
# أو: node dist/server.js  (مدير حزم Bun، بيئة تشغيل Node)

// كل هذه تعمل كما هو متوقع في Bun
import fs from "node:fs";
import path from "node:path";
import crypto from "node:crypto";
import { Buffer } from "node:buffer";
import { EventEmitter } from "node:events";
import { Readable, Writable } from "node:stream";
import http from "node:http";
import https from "node:https";
import { URL, URLSearchParams } from "node:url";
import os from "node:os";
import child_process from "node:child_process";

# تحقق إذا كانت الحزمة تستخدم إضافات أصلية
ls node_modules/your-package/binding.gyp  # إذا كان هذا موجوداً، إنها أصلية

// هذا لن يعمل في Bun — خاص بـ V8
const v8 = require("v8");
v8.serialize({ data: "test" });
 
// هذا سيعمل — استخدم مكافئ Bun أو نهج عابر لبيئات التشغيل
const encoded = new TextEncoder().encode(JSON.stringify({ data: "test" }));

# شغّل فحص التوافق المدمج في Bun على مشروعك
bun --bun node_modules/.bin/your-tool
 
# علامة --bun تفرض بيئة تشغيل Bun حتى لسكربتات node_modules

# فحص توافق سريع — شغّل مجموعة الاختبارات الكاملة تحت Bun
bun test  # إذا كنت تستخدم مُشغّل اختبارات bun
# أو
bun run vitest  # إذا كنت تستخدم vitest

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
 
    if (url.pathname === "/") {
      return new Response("مرحباً من Bun!", {
        headers: { "Content-Type": "text/plain" },
      });
    }
 
    if (url.pathname === "/api/users") {
      const users = [
        { id: 1, name: "أليس" },
        { id: 2, name: "بوب" },
      ];
      return Response.json(users);
    }
 
    return new Response("غير موجود", { status: 404 });
  },
});
 
console.log(`الخادم يعمل على http://localhost:${server.port}`);

import { Database } from "bun:sqlite";
 
const db = new Database("app.db");
db.run(`
  CREATE TABLE IF NOT EXISTS todos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    completed INTEGER DEFAULT 0,
    created_at TEXT DEFAULT (datetime('now'))
  )
`);
 
const server = Bun.serve({
  port: process.env.PORT || 3000,
 
  async fetch(req) {
    const url = new URL(req.url);
    const method = req.method;
 
    try {
      // GET /api/todos
      if (url.pathname === "/api/todos" && method === "GET") {
        const todos = db.query("SELECT * FROM todos ORDER BY created_at DESC").all();
        return Response.json(todos);
      }
 
      // POST /api/todos
      if (url.pathname === "/api/todos" && method === "POST") {
        const body = await req.json();
 
        if (!body.title || typeof body.title !== "string") {
          return Response.json({ error: "العنوان مطلوب" }, { status: 400 });
        }
 
        const stmt = db.prepare("INSERT INTO todos (title) VALUES (?) RETURNING *");
        const todo = stmt.get(body.title);
        return Response.json(todo, { status: 201 });
      }
 
      // DELETE /api/todos/:id
      const deleteMatch = url.pathname.match(/^\/api\/todos\/(\d+)$/);
      if (deleteMatch && method === "DELETE") {
        const id = parseInt(deleteMatch[1], 10);
        db.run("DELETE FROM todos WHERE id = ?", [id]);
        return new Response(null, { status: 204 });
      }
 
      return Response.json({ error: "غير موجود" }, { status: 404 });
    } catch (error) {
      console.error("خطأ في الطلب:", error);
      return Response.json({ error: "خطأ داخلي في الخادم" }, { status: 500 });
    }
  },
});
 
console.log(`الخادم يعمل على المنفذ ${server.port}`);

// قراءة الملفات
const file = Bun.file("./config.json");
const text = await file.text();       // قراءة كنص
const json = await file.json();       // تحليل كـ JSON مباشرة
const bytes = await file.arrayBuffer(); // قراءة كـ ArrayBuffer
const stream = file.stream();          // قراءة كـ ReadableStream
 
// بيانات تعريف الملف
console.log(file.size);  // الحجم بالبايت
console.log(file.type);  // نوع MIME (مثلاً "application/json")
 
// كتابة الملفات
await Bun.write("./output.txt", "مرحباً بالعالم!");
await Bun.write("./data.json", JSON.stringify({ key: "value" }));
await Bun.write("./copy.png", Bun.file("./original.png"));
 
// كتابة جسم Response لملف
const response = await fetch("https://example.com/data.json");
await Bun.write("./downloaded.json", response);

const server = Bun.serve({
  port: 3000,
 
  fetch(req, server) {
    const url = new URL(req.url);
 
    if (url.pathname === "/ws") {
      const upgraded = server.upgrade(req, {
        data: {
          userId: url.searchParams.get("userId"),
          joinedAt: Date.now(),
        },
      });
 
      if (!upgraded) {
        return new Response("فشل ترقية WebSocket", { status: 400 });
      }
      return undefined;
    }
 
    return new Response("استخدم /ws لاتصالات WebSocket");
  },
 
  websocket: {
    open(ws) {
      console.log(`عميل متصل: ${ws.data.userId}`);
      ws.subscribe("chat");
    },
 
    message(ws, message) {
      // البث لجميع المشتركين
      server.publish("chat", `${ws.data.userId}: ${message}`);
    },
 
    close(ws) {
      console.log(`عميل انفصل: ${ws.data.userId}`);
      ws.unsubscribe("chat");
    },
  },
});

import { Database } from "bun:sqlite";
 
// فتح أو إنشاء قاعدة بيانات
const db = new Database("myapp.db");
 
// وضع WAL لأداء قراءة متزامن أفضل
db.exec("PRAGMA journal_mode = WAL");
 
// إنشاء جداول
db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT (datetime('now'))
  )
`);
 
// عبارات مُعدّة (قابلة لإعادة الاستخدام، أسرع للاستعلامات المتكررة)
const insertUser = db.prepare(
  "INSERT INTO users (email, name) VALUES ($email, $name) RETURNING *"
);
 
const findByEmail = db.prepare(
  "SELECT * FROM users WHERE email = $email"
);
 
// الاستخدام
const user = insertUser.get({
  $email: "alice@example.com",
  $name: "Alice",
});
console.log(user); // { id: 1, email: "alice@example.com", name: "Alice", ... }
 
// المعاملات
const insertMany = db.transaction((users: { email: string; name: string }[]) => {
  for (const user of users) {
    insertUser.run({ $email: user.email, $name: user.name });
  }
  return users.length;
});
 
const count = insertMany([
  { email: "bob@example.com", name: "Bob" },
  { email: "carol@example.com", name: "Carol" },
]);
console.log(`تم إدراج ${count} مستخدمين`);

// math.test.ts
import { describe, it, expect } from "bun:test";
 
describe("أدوات الرياضيات", () => {
  it("يجمع الأرقام بشكل صحيح", () => {
    expect(1 + 2).toBe(3);
  });
 
  it("يتعامل مع الأعداد العشرية", () => {
    expect(0.1 + 0.2).toBeCloseTo(0.3);
  });
});

# تشغيل جميع الاختبارات
bun test
 
# تشغيل ملف محدد
bun test math.test.ts
 
# تشغيل اختبارات تطابق نمطاً
bun test --test-name-pattern "يجمع الأرقام"
 
# وضع المراقبة
bun test --watch
 
# التغطية
bun test --coverage

import { describe, it, expect, mock, spyOn } from "bun:test";
import { fetchUsers } from "./api";
 
// محاكاة وحدة
mock.module("./database", () => ({
  query: mock(() => [{ id: 1, name: "Alice" }]),
}));
 
describe("fetchUsers", () => {
  it("يُرجع المستخدمين من قاعدة البيانات", async () => {
    const users = await fetchUsers();
    expect(users).toHaveLength(1);
    expect(users[0].name).toBe("Alice");
  });
});
 
// التجسس على طريقة كائن
describe("console", () => {
  it("يتتبع استدعاءات console.log", () => {
    const logSpy = spyOn(console, "log");
    console.log("رسالة اختبار");
    expect(logSpy).toHaveBeenCalledWith("رسالة اختبار");
    logSpy.mockRestore();
  });
});

# تحزيم نقطة دخول واحدة
bun build ./src/index.ts --outdir ./dist
 
# التحزيم لأهداف مختلفة
bun build ./src/index.ts --outdir ./dist --target browser
bun build ./src/index.ts --outdir ./dist --target bun
bun build ./src/index.ts --outdir ./dist --target node
 
# التصغير
bun build ./src/index.ts --outdir ./dist --minify
 
# توليد خرائط المصدر
bun build ./src/index.ts --outdir ./dist --sourcemap external

const result = await Bun.build({
  entrypoints: ["./src/index.ts", "./src/worker.ts"],
  outdir: "./dist",
  target: "browser",
  minify: {
    whitespace: true,
    identifiers: true,
    syntax: true,
  },
  splitting: true,    // تقسيم الكود
  sourcemap: "external",
  external: ["react", "react-dom"],  // لا تحزم هذه
  naming: "[dir]/[name]-[hash].[ext]",
  define: {
    "process.env.NODE_ENV": JSON.stringify("production"),
  },
});
 
if (!result.success) {
  console.error("فشل البناء:");
  for (const log of result.logs) {
    console.error(log);
  }
  process.exit(1);
}
 
for (const output of result.outputs) {
  console.log(`${output.path} — ${output.size} بايت`);
}

// utils.ts
export function used() {
  return "سأكون في الحزمة";
}
 
export function unused() {
  return "سأُزال بإزالة الكود الميت";
}
 
// index.ts
import { used } from "./utils";
console.log(used());

bun build ./src/index.ts --outdir ./dist --minify
# الدالة `unused` لن تظهر في الإخراج

// build-info.ts — هذا الملف يعمل في وقت البناء، ليس وقت التشغيل
export function getBuildInfo() {
  return {
    builtAt: new Date().toISOString(),
    gitSha: require("child_process")
      .execSync("git rev-parse --short HEAD")
      .toString()
      .trim(),
    nodeVersion: process.version,
  };
}

// app.ts
import { getBuildInfo } from "./build-info" with { type: "macro" };
 
// getBuildInfo() تُنفّذ في وقت التحزيم
// النتيجة تُضمّن كقيمة ثابتة
const info = getBuildInfo();
console.log(`بُني في ${info.builtAt}، commit ${info.gitSha}`);

# استخدم Bun لتثبيت التبعيات، ثم استخدم Node.js لتشغيل Next.js
bun install
bun run dev    # هذا فعلاً يشغّل سكربت "dev" عبر Node.js افتراضياً
bun run build
bun run start

# فرض تشغيل Next.js تحت بيئة تشغيل Bun
bun --bun run dev

# البناء ببيئة تشغيل Bun
bun --bun run build
 
# بدء خادم الإنتاج ببيئة تشغيل Bun
bun --bun run start

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start"
  }
}

# سير العمل اليومي
bun install      # تثبيت حزم سريع
bun run dev      # يشغّل "next dev" عبر Node.js
bun run build    # يشغّل "next build" عبر Node.js

FROM oven/bun:1 AS base
WORKDIR /app
 
# تثبيت التبعيات
FROM base AS deps
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production
 
# البناء (إذا لزم الأمر)
FROM base AS build
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build
 
# الإنتاج
FROM base AS production
WORKDIR /app
 
# لا تشغّل كـ root
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
USER appuser
 
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./
 
EXPOSE 3000
CMD ["bun", "run", "dist/server.js"]

# مرحلة البناء: صورة Bun كاملة مع جميع التبعيات
FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun build ./src/index.ts --target bun --outdir ./dist --minify
 
# مرحلة التشغيل: صورة أساسية أصغر
FROM oven/bun:1-slim AS runtime
WORKDIR /app
 
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
USER appuser
 
COPY --from=builder /app/dist ./dist
 
EXPOSE 3000
CMD ["bun", "run", "dist/index.js"]

# تجميع تطبيقك لملف تنفيذي واحد
bun build --compile ./src/server.ts --outfile server
 
# الإخراج ملف ثنائي مستقل — لا حاجة لـ Bun أو Node.js لتشغيله
./server

# صورة Docker فائقة الحد الأدنى باستخدام ملف ثنائي مُجمّع
FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun build --compile ./src/server.ts --outfile server
 
# الصورة النهائية — فقط الملف الثنائي
FROM debian:bookworm-slim
WORKDIR /app
 
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
USER appuser
 
COPY --from=builder /app/server ./server
 
EXPOSE 3000
CMD ["./server"]

# صورة Node.js
docker images | grep node
# node:20-slim    ~180MB
 
# صورة Bun
docker images | grep bun
# oven/bun:1-slim  ~130MB
 
# ملف ثنائي مُجمّع على debian:bookworm-slim
# ~80MB قاعدة + ~70MB ملف ثنائي = ~150MB إجمالي
 
# مقابل Alpine مع Node.js
# node:20-alpine   ~130MB + node_modules

# استبدل npm/yarn/pnpm بـ bun install
# غيّر خط أنابيب CI:
# قبل:
npm ci
 
# بعد:
bun install --frozen-lockfile

# استخدم bun لتشغيل سكربتات التطوير
bun run dev
bun run lint
bun run format
 
# استخدم bun للسكربتات لمرة واحدة
bun run scripts/seed-database.ts
bun run scripts/migrate.ts

# استبدل vitest/jest بـ bun test لمجموعات الاختبار البسيطة
bun test
 
# أبقِ vitest لإعدادات الاختبار المعقدة
# (Testing Library، MSW، بيئات مخصصة)

// خدمات مصغّرة أو واجهات API جديدة — ابدأ مع Bun من اليوم الأول
Bun.serve({
  port: 3000,
  fetch(req) {
    // خدمتك الجديدة هنا
  },
});

# فقط بعد اختبار شامل:
# استبدل node بـ bun للخدمات الحالية
# قبل:
node dist/server.js
 
# بعد:
bun dist/server.js

# .env
DATABASE_URL=postgresql://localhost:5432/myapp
API_KEY=sk-test-12345
PORT=3000

// هذه متاحة بدون أي استيراد
console.log(process.env.DATABASE_URL);
console.log(process.env.API_KEY);
console.log(Bun.env.PORT); // بديل خاص بـ Bun

# مُصحح Bun — يعمل مع VS Code
bun --inspect run server.ts
 
# inspect-brk في Bun — توقف عند السطر الأول
bun --inspect-brk run server.ts

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Bun",
      "program": "${workspaceFolder}/src/server.ts",
      "cwd": "${workspaceFolder}",
      "stopOnEntry": false,
      "watchMode": false
    }
  ]
}

# مقارنة أعداد التبعيات
# مشروع Express + SQLite + WebSocket نموذجي:
npm ls --all | wc -l
# ~340 حزمة
 
# نفس الوظائف مع ميزات Bun المدمجة:
bun pm ls --all | wc -l
# ~12 حزمة (فقط كود تطبيقك)

// استخدم خيارات Bun.serve() لضبط الإنتاج
Bun.serve({
  port: 3000,
 
  // زيادة الحد الأقصى لحجم جسم الطلب (الافتراضي 128MB)
  maxRequestBodySize: 1024 * 1024 * 50, // 50MB
 
  // تفعيل وضع التطوير لصفحات خطأ أفضل
  development: process.env.NODE_ENV !== "production",
 
  // إعادة استخدام المنفذ (مفيد لإعادة التشغيل بدون توقف)
  reusePort: true,
 
  fetch(req) {
    return new Response("OK");
  },
});

// استخدم Bun.Transpiler لتحويل الكود في وقت التشغيل
const transpiler = new Bun.Transpiler({
  loader: "tsx",
  target: "browser",
});
 
const code = transpiler.transformSync(`
  const App: React.FC = () => <div>مرحباً</div>;
  export default App;
`);

# علامات استخدام ذاكرة Bun
bun --smol run server.ts  # تقليل أثر الذاكرة (أبطأ قليلاً)
 
# تعيين الحد الأقصى لحجم الكومة
BUN_JSC_forceRAMSize=512000000 bun run server.ts  # ~512MB حد

// fetch في Node.js 18+ و fetch في Bun مختلفتان قليلاً
// في كيفية التعامل مع بعض الرؤوس وعمليات إعادة التوجيه
 
// Bun يتبع إعادة التوجيه افتراضياً (مثل المتصفحات)
// fetch في Node.js أيضاً يتبع إعادة التوجيه، لكن السلوك
// مع بعض رموز الحالة (303، 307، 308) يمكن أن يختلف
 
const response = await fetch("https://api.example.com/data", {
  redirect: "manual", // كن صريحاً في التعامل مع إعادة التوجيه
});

// Bun يخرج عندما تكون حلقة الأحداث فارغة
// Node.js أحياناً يستمر في العمل بسبب مقابض متبقية
 
// إذا خرج سكربت Bun بشكل غير متوقع، شيء ما لا
// يحافظ على حلقة الأحداث حية
 
// هذا سيخرج فوراً في Bun:
setTimeout(() => {}, 0);
 
// هذا سيستمر في العمل:
setTimeout(() => {}, 1000);
// (Bun يخرج بعد أن يُطلق المؤقت)

// لدى Bun إعدادات tsconfig الافتراضية الخاصة
// إذا كنت تشارك مشروعاً بين Bun و Node.js،
// كن صريحاً في tsconfig.json:
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"]  // أضف تعريفات أنواع Bun
  }
}

# تثبيت أنواع Bun
bun add -d @types/bun

# لدى Bun وضع مراقبة مدمج
bun --watch run server.ts
 
# هذا يعيد تشغيل العملية عند تغيّر الملفات
# ليس HMR (استبدال الوحدات الساخنة) — إنه إعادة تشغيل كاملة
# لكن لأن Bun يبدأ بسرعة كبيرة، يبدو فورياً

# bunfig.toml — ملف تهيئة Bun (اختياري)
 
[install]
# استخدام سجل خاص
registry = "https://npm.mycompany.com"
 
# سجلات ذات نطاق
[install.scopes]
"@mycompany" = "https://npm.mycompany.com"
 
[test]
# تهيئة الاختبارات
coverage = true
coverageReporter = ["text", "lcov"]
 
[run]
# الصدفة لاستخدامها مع bun run
shell = "bash"