تنفذ حزمة Bun مجموعة من المحملات الافتراضية خارج الصندوق.

كقاعدة عامة: الحزمة ووقت التشغيل يدعمان نفس المجموعة من أنواع الملفات خارج الصندوق.

.js .cjs .mjs .mts .cts .ts .tsx .jsx .css .json .jsonc .toml .yaml .yml .txt .wasm .node .html .sh

تستخدم Bun امتداد الملف لتحديد المحمل المدمج الذي يجب استخدامه لتحليل الملف. كل محمل له اسم، مثل js أو tsx أو json. تُستخدم هذه الأسماء عند بناء المكونات الإضافية التي توسع Bun بمحملات مخصصة.

يمكنك تحديد المحمل الذي يجب استخدامه صراحةً باستخدام سمة الاستيراد 'type'.

index.ts

import my_toml from "./my_file" with { type: "toml" };
// أو مع الواردات الديناميكية
const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

المحملات المدمجة

js

محمل JavaScript. افتراضي لـ .cjs و .mjs.

يحلل الكود ويطبق مجموعة من التحويلات الافتراضية مثل إزالة الكود الميت وهز الشجرة. لاحظ أن Bun لا تحاول تحويل الصيغة لأسفل في الوقت الحالي.

---

jsx

محمل JavaScript + JSX. افتراضي لـ .js و .jsx.

مثل محمل js، لكن صيغة JSX مدعومة. افتراضيًا، يتم تحويل JSX إلى JavaScript عادي؛ تفاصيل كيفية القيام بذلك تعتمد على خيارات المترجم jsx* في tsconfig.json. راجع وثائق TypeScript حول JSX لمزيد من المعلومات.

---

ts

محمل TypeScript. افتراضي لـ .ts و .mts و .cts.

يزيل جميع صيغ TypeScript، ثم يتصرف بشكل مطابق لمحمل js. Bun لا تقوم بالتحقق من النوع.

---

tsx

محمل TypeScript + JSX. افتراضي لـ .tsx.

يترجم كل من TypeScript و JSX إلى JavaScript عادي.

---

json

محمل JSON. افتراضي لـ .json.

يمكن استيراد ملفات JSON مباشرة.

import pkg from "./package.json";
pkg.name; // => "my-package"

أثناء الحزمة، يتم تضمين JSON الذي تم تحليله في الحزمة ككائن JavaScript.

const pkg = {
  name: "my-package",
  // ... حقول أخرى
};

pkg.name;

إذا تم تمرير ملف .json كنقطة دخول للحزمة، سيتم تحويله إلى وحدة .js تقوم export default للكائن الذي تم تحليله.

{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

---

jsonc

محمل JSON مع تعليقات. افتراضي لـ .jsonc.

يمكن استيراد ملفات JSONC (JSON مع تعليقات) مباشرة. ستقوم Bun بتحليلها، وإزالة التعليقات والفواصل اللاحقة.

import config from "./config.jsonc";
console.log(config);

أثناء الحزمة، يتم تضمين JSONC الذي تم تحليله في الحزمة ككائن JavaScript، مطابق لمحمل json.

var config = {
  option: "value",
};

NOTE

تستخدم Bun تلقائيًا محمل `jsonc` لملفات `tsconfig.json` و `jsconfig.json` و `package.json` و `bun.lock`.

---

toml

محمل TOML. افتراضي لـ .toml.

يمكن استيراد ملفات TOML مباشرة. ستقوم Bun بتحليلها باستخدام محلل TOML الأصلي السريع.

import config from "./bunfig.toml";
config.logLevel; // => "debug"

// عبر سمة الاستيراد:
// import myCustomTOML from './my.config' with {type: "toml"};

أثناء الحزمة، يتم تضمين TOML الذي تم تحليله في الحزمة ككائن JavaScript.

var config = {
  logLevel: "debug",
  // ...حقول أخرى
};
config.logLevel;

إذا تم تمرير ملف .toml كنقطة دخول، سيتم تحويله إلى وحدة .js تقوم export default للكائن الذي تم تحليله.

name = "John Doe"
age = 35
email = "johndoe@example.com"

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

---

yaml

محمل YAML. افتراضي لـ .yaml و .yml.

يمكن استيراد ملفات YAML مباشرة. ستقوم Bun بتحليلها باستخدام محلل YAML الأصلي السريع.

import config from "./config.yaml";
console.log(config);

// عبر سمة الاستيراد:
import data from "./data.txt" with { type: "yaml" };

أثناء الحزمة، يتم تضمين YAML الذي تم تحليله في الحزمة ككائن JavaScript.

var config = {
  name: "my-app",
  version: "1.0.0",
  // ...حقول أخرى
};

إذا تم تمرير ملف .yaml أو .yml كنقطة دخول، سيتم تحويله إلى وحدة .js تقوم export default للكائن الذي تم تحليله.

name: John Doe
age: 35
email: johndoe@example.com

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

---

text

محمل نصي. افتراضي لـ .txt.

يتم قراءة محتويات الملف النصي وتضمينها في الحزمة كسلسلة. يمكن استيراد الملفات النصية مباشرة. يتم قراءة الملف وإرجاعه كسلسلة.

import contents from "./file.txt";
console.log(contents); // => "Hello, world!"

// لاستيراد ملف html كنص
// يمكن استخدام سمة "type" لتجاوز المحمل الافتراضي.
import html from "./index.html" with { type: "text" };

عند الإشارة إليه أثناء البناء، يتم تضمين المحتويات في الحزمة كسلسلة.

var contents = `Hello, world!`;
console.log(contents);

إذا تم تمرير ملف .txt كنقطة دخول، سيتم تحويله إلى وحدة .js تقوم export default لمحتويات الملف.

Hello, world!

export default "Hello, world!";

---

napi

محمل الإضافات الأصلية. افتراضي لـ .node.

في وقت التشغيل، يمكن استيراد الإضافات الأصلية مباشرة.

import addon from "./addon.node";
console.log(addon);

NOTE

في الحزمة، يتم التعامل مع ملفات `.node` باستخدام محمل الملفات.

---

sqlite

محمل SQLite. يتطلب سمة الاستيراد with { "type": "sqlite" }.

في وقت التشغيل والحزمة، يمكن استيراد قواعد بيانات SQLite مباشرة. هذا سيحمل قاعدة البيانات باستخدام bun:sqlite.

import db from "./my.db" with { type: "sqlite" };

افتراضيًا، قاعدة البيانات خارجية عن الحزمة (حتى تتمكن من استخدام قاعدة بيانات محملة في مكان آخر)، لذا لن يتم حزمة ملف قاعدة البيانات على القرص في الإخراج النهائي.

يمكنك تغيير هذا السلوك باستخدام سمة "embed":

// تضمين قاعدة البيانات في الحزمة
import db from "./my.db" with { type: "sqlite", embed: "true" };

---

html

محمل HTML. افتراضي لـ .html.

يعالج محمل html ملفات HTML ويحزم أي أصول مرجعية. سيقوم بـ:

• حزمة وتجزئة ملفات JavaScript المرجعية (<script src="...">)
• حزمة وتجزئة ملفات CSS المرجعية (<link rel="stylesheet" href="...">)
• تجزئة الصور المرجعية (<img src="...">)
• الحفاظ على URLs الخارجية (افتراضيًا، أي شيء يبدأ بـ http:// أو https://)

على سبيل المثال، مع ملف HTML هذا:

src/index.html

<!DOCTYPE html>
<html>
  <body>
    <img src="./image.jpg" alt="صورة محلية" />
    <img src="https://example.com/image.jpg" alt="صورة خارجية" />
    <script type="module" src="./script.js"></script>
  </body>
</html>

سيخرج ملف HTML جديد مع الأصول المحزمة:

dist/index.html

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="صورة محلية" />
    <img src="https://example.com/image.jpg" alt="صورة خارجية" />
    <script type="module" src="./output-ALSO-HASHED.js"></script>
  </body>
</html>

تحت الغطاء، يستخدم lol-html لاستخراج وسوم البرنامج النصي والرابط كنقاط دخول، والأصول الأخرى كخارجية.

قائمة محددات HTML المدعومة">

حاليًا، قائمة المحددات هي:

• audio[src]
• iframe[src]
• img[src]
• img[srcset]
• link:not([rel~='stylesheet']):not([rel~='modulepreload']):not([rel~='manifest']):not([rel~='icon']):not([rel~='apple-touch-icon'])[href]
• link[as='font'][href], link[type^='font/'][href]
• link[as='image'][href]
• link[as='style'][href]
• link[as='video'][href], link[as='audio'][href]
• link[as='worker'][href]
• link[rel='icon'][href], link[rel='apple-touch-icon'][href]
• link[rel='manifest'][href]
• link[rel='stylesheet'][href]
• script[src]
• source[src]
• source[srcset]
• video[poster]
• video[src]

NOTE

سلوك محمل HTML في سياقات مختلفة

يتصرف محمل html بشكل مختلف اعتمادًا على كيفية استخدامه:

• البناء الثابت: عند تشغيل bun build ./index.html، تنتج Bun موقعًا ثابتًا مع جميع الأصول المحزمة والمجزأة.
• وقت التشغيل: عند تشغيل bun run server.ts (حيث يستورد server.ts ملف HTML)، تحزم Bun الأصول أثناء الطيران أثناء التطوير، مما يمكّن ميزات مثل استبدال الوحدة الساخن.
• بناء المكدس الكامل: عند تشغيل bun build --target=bun server.ts (حيث يستورد server.ts ملف HTML)، يتم حل الاستيراد إلى كائن بيان تستخدمه Bun.serve لخدمة الأصول المحزمة مسبقًا بكفاءة في الإنتاج.

---

css

محمل CSS. افتراضي لـ .css.

يمكن استيراد ملفات CSS مباشرة. ستقوم الحزمة بتحليل وحزمة ملفات CSS، والتعامل مع بيانات @import ومراجع url().

import "./styles.css";

أثناء الحزمة، يتم حزمة جميع ملفات CSS المستوردة معًا في ملف .css واحد في دليل الإخراج.

.my-class {
  background: url("./image.png");
}

---

sh

محمل Bun Shell. افتراضي لملفات .sh.

يستخدم هذا المحمل لتحليل نصوص Bun Shell. إنه مدعوم فقط عند بدء Bun نفسه، لذا فهو غير متوفر في الحزمة أو في وقت التشغيل.

bun run ./script.sh

---

file

محمل الملفات. افتراضي لجميع أنواع الملفات غير المعترف بها.

يحل محمل الملفات الاستيراد كمسار/URL إلى الملف المستورد. يُستخدم عادةً للإشارة إلى أصول الوسائط أو الخطوط.

// logo.ts
import logo from "./logo.svg";
console.log(logo);

في وقت التشغيل، تتحقق Bun من وجود ملف logo.svg وتحوله إلى مسار مطلق لموقع logo.svg على القرص.

bun run logo.ts
# الإخراج: /path/to/project/logo.svg

في الحزمة، الأمور مختلفة قليلاً. يتم نسخ الملف إلى outdir كما هو، ويتم حل الاستيراد كمسار نسبي يشير إلى الملف المنسوخ.

// الإخراج
var logo = "./logo.svg";
console.log(logo);

إذا تم تحديد قيمة لـ publicPath، سيستخدم الاستيراد القيمة كبادئة لإنشاء مسار/URL مطلق.

المسار العام	الاستيراد المحلول
"" (افتراضي)	/logo.svg
"/assets"	/assets/logo.svg
"https://cdn.example.com/"	https://cdn.example.com/logo.svg

NOTE

موقع واسم الملف المنسوخ يتم تحديده بواسطة قيمة `naming.asset`.

يتم نسخ هذا المحمل إلى outdir كما هو. يتم تحديد اسم الملف المنسوخ باستخدام قيمة naming.asset.