يُنفذ حزمة 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'.

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.

var 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);

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

sqlite

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

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

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

هذا مدعوم فقط عندما يكون target هو bun.

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

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

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

عند استخدام تنفيذ مستقل، يتم تضمين قاعدة البيانات في الملف التنفيذي الواحد.

خلاف ذلك، يتم نسخ قاعدة البيانات المراد تضمينها إلى outdir باسم ملف مشفر.

html

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

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

على سبيل المثال، بالنظر إلى ملف HTML هذا:

<!DOCTYPE html>
<html>
  <body>
    <img src="./image.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./script.js"></script>
  </body>
</html>

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

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./output-ALSO-HASHED.js"></script>
  </body>
</html>

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

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

• 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 بشكل مختلف اعتمادًا على كيفية استخدامه:

1. بناء ثابت: عند تشغيل bun build ./index.html، ينتج Bun موقعًا ثابتًا مع جميع الأصول المحزمة والمجزأة.

2. وقت التشغيل: عند تشغيل bun run server.ts (حيث يستورد server.ts ملف HTML)، يحزم Bun الأصول أثناء التطوير، مما يمكّن ميزات مثل استبدال الوحدة الساخن.

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

css

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

يمكن استيراد ملفات CSS مباشرة. هذا مفيد بشكل أساسي لـ تطبيقات المكدس الكامل حيث يتم حزم CSS مع HTML.

import "./styles.css";

لا يتم إرجاع أي قيمة من الاستيراد، يُستخدم فقط للآثار الجانبية.

محمل sh

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

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

bun run ./script.sh

file

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

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

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`](/ar/bundler#naming).

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

إصلاح أخطاء استيراد TypeScript">

إذا كنت تستخدم TypeScript، فقد تحصل على خطأ مثل هذا:

// خطأ TypeScript
// Cannot find module './logo.svg' or its corresponding type declarations.

يمكن إصلاح ذلك بإنشاء ملف *.d.ts في أي مكان في مشروعك (أي اسم سيعمل) بالمحتويات التالية:

declare module "*.svg" {
  const content: string;
  export default content;
}

يخبر هذا TypeScript أن أي استيراد افتراضي من .svg يجب أن يُعامل كسلسلة نصية.