Bun JS HTML والمواقع الثابتة

حزمة Bun في Bun لديها دعم من الدرجة الأولى لـ HTML. ابنِ مواقع ثابتة وصفحات هبوط وتطبيقات ويب بدون أي تكوين. فقط أشر Bun إلى ملف HTML الخاص بك وسيتعامل مع كل شيء آخر.

html

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./styles.css" />
    <script src="./app.ts" type="module"></script>
  </head>
  <body>
    <img src="./logo.png" />
  </body>
</html>

للبدء، مرر ملفات HTML إلى bun.

bash

bun ./index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

خادم التطوير في Bun يوفر ميزات قوية بدون أي تكوين:

الحزمة التلقائية - يحزم ويقدم HTML و JavaScript و CSS
دعم متعدد المدخلات - يتعامل مع نقاط دخول HTML متعددة ونقاط دخول glob
JavaScript الحديث - دعم TypeScript و JSX خارج الصندوق
تكوين ذكي - يقرأ tsconfig.json للمسارات وخيارات JSX والمزخرفات التجريبية وأكثر
المكونات الإضافية - مكونات إضافية لـ TailwindCSS وأكثر
ESM و CommonJS - استخدم ESM و CommonJS في ملفات JavaScript و TypeScript و JSX
حزمة CSS والتصغير - يحزم CSS من وسوم <link> وبيانات @import
إدارة الأصول - نسخ وتجزئة تلقائية للصور والأصول؛ يعيد كتابة مسارات الأصول في JavaScript و CSS و HTML

تطبيقات الصفحة الواحدة (SPA)

عندما تمرر ملف .html واحد إلى Bun، سيستخدمه Bun كمسار احتياطي لجميع المسارات. هذا يجعله مثاليًا لتطبيقات الصفحة الواحدة التي تستخدم التوجيه من جانب العميل:

bash

bun index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

سيعمل React أو SPA الآخر الخاص بك خارج الصندوق - لا حاجة لأي تكوين. جميع المسارات مثل /about و /users/123 إلخ ستقدم نفس ملف HTML، تاركة لجهاز التوجيه من جانب العميل التعامل مع التنقل.

html

<!doctype html>
<html>
  <head>
    <title>My SPA</title>
    <script src="./app.tsx" type="module"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

تطبيقات متعددة الصفحات (MPA)

بعض المشاريع لديها عدة مسارات منفصلة أو ملفات HTML كنقاط دخول. لدعم نقاط دخول متعددة، مررها جميعًا إلى bun:

bash

bun ./index.html ./about.html

txt

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

هذا سيقدم:

index.html عند /
about.html عند /about

أنماط Glob

لتحديد ملفات متعددة، يمكنك استخدام أنماط glob التي تنتهي بـ .html:

bash

bun ./**/*.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

تطبيع المسار

يتم اختيار المسار الأساسي من أطول بادئة مشتركة بين جميع الملفات.

bash

bun ./index.html ./about/index.html ./about/foo/index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about/index.html
  /about/foo ./about/foo/index.html
Press h + Enter to show shortcuts

JavaScript و TypeScript و JSX

مترجم Bun ينفذ دعم JavaScript و TypeScript و JSX أصلاً. اعرف المزيد عن المحملات في Bun.

NOTE

مترجم Bun يُستخدم أيضًا في وقت التشغيل.

ES Modules و CommonJS

يمكنك استخدام ESM و CJS في ملفات JavaScript و TypeScript و JSX. سيتعامل Bun مع الترجمة والحزمة تلقائيًا.

لا توجد خطوة بناء مسبقة أو تحسين منفصل. كل شيء يتم في نفس الوقت.

اعرف المزيد عن حل الوحدات في Bun.

CSS

محلل CSS في Bun أيضًا منفذ أصلاً (حوالي 58000 سطر من Zig).

هو أيضًا حزمة CSS. يمكنك استخدام @import في ملفات CSS لاستيراد ملفات CSS أخرى.

على سبيل المثال:

css

@import "./abc.css";

.container {
  background-color: blue;
}

css

body {
  background-color: red;
}

هذا يخرج:

css

body {
  background-color: red;
}

.container {
  background-color: blue;
}

الإشارة إلى الأصول المحلية في CSS

يمكنك الإشارة إلى الأصول المحلية في ملفات CSS.

css

body {
  background-image: url("./logo.png");
}

هذا سينسخ ./logo.png إلى دليل الإخراج ويعيد كتابة المسار في ملف CSS لتضمين تجزئة محتوى.

css

body {
  background-image: url("./logo-[ABC123].png");
}

استيراد CSS في JavaScript

لربط ملف CSS بملف JavaScript، يمكنك استيراده في ملف JavaScript.

import "./styles.css";
import "./more-styles.css";

هذا يولد ./app.css و ./app.js في دليل الإخراج. جميع ملفات CSS المستوردة من JavaScript سيتم حزمها في ملف CSS واحد لكل نقطة دخول. إذا استوردت نفس ملف CSS من ملفات JavaScript متعددة، سيتم تضمينه مرة واحدة فقط في ملف CSS الإخراج.

المكونات الإضافية

خادم التطوير يدعم المكونات الإضافية.

Tailwind CSS

لاستخدام TailwindCSS، قم بتثبيت المكون الإضافي bun-plugin-tailwind:

bash

# أو أي عميل npm
bun install --dev bun-plugin-tailwind

ثم، أضف المكون الإضافي إلى bunfig.toml:

bunfig.toml

toml

[serve.static]
plugins = ["bun-plugin-tailwind"]

ثم، أشر إلى TailwindCSS في HTML عبر وسم <link>، أو @import في CSS، أو استيراد في JavaScript.

html

<!-- أشر إلى TailwindCSS في HTML -->
<link rel="stylesheet" href="tailwindcss" />

styles.css

css

@import "tailwindcss";

import "tailwindcss";

متغيرات البيئة المضمنة

Bun يمكنه استبدال مراجع process.env.* في JavaScript و TypeScript بقيمها الفعلية في وقت البناء. هذا مفيد لحقن التكوين مثل URLs API أو أعلام الميزات في كود الواجهة الأمامية.

خادم التطوير (وقت التشغيل)

لتضمين متغيرات البيئة عند استخدام bun ./index.html، اضبط خيار env في bunfig.toml:

bunfig.toml

toml

[serve.static]
env = "PUBLIC_*"  # فقط متغيرات البيئة التي تبدأ بـ PUBLIC_ (موصى به)
# env = "inline"  # تضمين جميع متغيرات البيئة
# env = "disable" # تعطيل استبدال متغيرات البيئة (افتراضي)

NOTE

هذا يعمل فقط مع مراجع `process.env.FOO` الحرفية، وليس `import.meta.env` أو الوصول غير المباشر مثل `const env = process.env; env.FOO`.

إذا لم يتم تعيين متغير بيئة، قد ترى أخطاء وقت التشغيل مثل ReferenceError: process is not defined في المتصفح.

ثم شغل خادم التطوير:

bash

PUBLIC_API_URL=https://api.example.com bun ./index.html

البناء للإنتاج

عند بناء HTML ثابت للإنتاج، استخدم خيار env لتضمين متغيرات البيئة:

bash

# تضمين جميع متغيرات البيئة
bun build ./index.html --outdir=dist --env=inline

# فقط متغيرات البيئة مع بادئة محددة (موصى به)
bun build ./index.html --outdir=dist --env=PUBLIC_*

// تضمين جميع متغيرات البيئة
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", 
});

// فقط متغيرات البيئة مع بادئة محددة (موصى به)
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", 
});

مثال

بملف المصدر هذا:

const apiUrl = process.env.PUBLIC_API_URL;
console.log(`API URL: ${apiUrl}`);

والتشغيل مع PUBLIC_API_URL=https://api.example.com:

bash

PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_*

الإخراج المحزم سيحتوي على:

dist/app.js

const apiUrl = "https://api.example.com";
console.log(`API URL: ${apiUrl}`);

صدى سجلات console من المتصفح إلى المحطة

خادم تطوير Bun يدعم دفق سجلات console من المتصفح إلى المحطة.

للتفعيل، مرر علم CLI --console.

bash

bun ./index.html --console

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

كل استدعاء لـ console.log أو console.error سيتم بثه إلى المحطة التي شغلت الخادم. هذا مفيد لرؤية الأخطاء من المتصفح في نفس المكان الذي تشغل فيه خادمك. هذا أيضًا مفيد لوكلاء AI الذين يراقبون إخراج المحطة.

داخليًا، يعيد هذا استخدام اتصال WebSocket الموجود من إعادة تحميل الوحدة الساخنة لإرسال السجلات.

تحرير الملفات في المتصفح

خادم تطوير الواجهة الأمامية في Bun لديه دعم لمجلدات مساحة العمل التلقائية في Chrome DevTools، مما يسمح لك بحفظ التعديلات على الملفات في المتصفح.

اختصارات لوحة المفاتيح

أثناء تشغيل الخادم:

o + Enter - فتح في المتصفح
c + Enter - مسح console
q + Enter (أو Ctrl+C) - خروج من الخادم

البناء للإنتاج

عندما تكون جاهزًا للنشر، استخدم bun build لإنشاء حزم إنتاج محسنة:

bash

bun build ./index.html --minify --outdir=dist

await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,
});

وضع المراقبة

يمكنك تشغيل bun build --watch لمراقبة التغييرات وإعادة البناء تلقائيًا. هذا يعمل بشكل جيد لتطوير المكتبات.

واجهة برمجة تطبيقات المكونات الإضافية

تحتاج إلى مزيد من التحكم؟ قم بتكوين الحزمة من خلال واجهة برمجة تطبيقات JavaScript واستخدم HTMLRewriter المدمج في Bun لمعالجة HTML مسبقًا.

await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,

  plugins: [
    {
      // مكون إضافي يجعل كل وسم HTML بأحرف صغيرة
      name: "lowercase-html-plugin",
      setup({ onLoad }) {
        const rewriter = new HTMLRewriter().on("*", {
          element(element) {
            element.tagName = element.tagName.toLowerCase();
          },
          text(element) {
            element.replace(element.text.toLowerCase());
          },
        });

        onLoad({ filter: /\.html$/ }, async args => {
          const html = await Bun.file(args.path).text();

          return {
            // حزمة Bun ستمسح HTML بحثًا عن وسوم <script> ووسوم <link rel="stylesheet"> وأصول أخرى
            // وتحزمها تلقائيًا
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

ما تتم معالجته؟

Bun يتعامل تلقائيًا مع جميع أصول الويب الشائعة:

البرامج النصية (<script src>) يتم تشغيلها عبر حزمة JavaScript/TypeScript/JSX في Bun
أوراق الأنماط (<link rel="stylesheet">) يتم تشغيلها عبر محلل CSS وحزمة Bun
الصور (<img>، <picture>) يتم نسخها وتجزئتها
الوسائط (<video>، <audio>، <source>) يتم نسخها وتجزئتها
أي وسم <link> مع سمة href تشير إلى ملف محلي يتم إعادة كتابته إلى المسار الجديد، ويتم تجزئته

يتم حل جميع المسارات نسبة إلى ملف HTML، مما يجعل من السهل تنظيم مشروعك كما تريد.

كيف يعمل هذا

هذا غلاف صغير حول دعم Bun لواردات HTML في JavaScript.

إضافة خلفية إلى الواجهة الأمامية

لإضافة خلفية إلى الواجهة الأمامية، يمكنك استخدام خيار "routes" في Bun.serve.

اعرف المزيد في وثائق المكدس الكامل.

تطبيقات الصفحة الواحدة (SPA) ​

تطبيقات متعددة الصفحات (MPA) ​

أنماط Glob ​

تطبيع المسار ​

JavaScript و TypeScript و JSX ​

ES Modules و CommonJS ​

CSS ​

الإشارة إلى الأصول المحلية في CSS ​

استيراد CSS في JavaScript ​

المكونات الإضافية ​

Tailwind CSS ​

متغيرات البيئة المضمنة ​

خادم التطوير (وقت التشغيل) ​

البناء للإنتاج ​

مثال ​

صدى سجلات console من المتصفح إلى المحطة ​

تحرير الملفات في المتصفح ​

اختصارات لوحة المفاتيح ​

البناء للإنتاج ​

وضع المراقبة ​

واجهة برمجة تطبيقات المكونات الإضافية ​

ما تتم معالجته؟ ​

كيف يعمل هذا ​

إضافة خلفية إلى الواجهة الأمامية ​

تطبيقات الصفحة الواحدة (SPA)

تطبيقات متعددة الصفحات (MPA)

أنماط Glob

تطبيع المسار

JavaScript و TypeScript و JSX

ES Modules و CommonJS

CSS

الإشارة إلى الأصول المحلية في CSS

استيراد CSS في JavaScript

المكونات الإضافية

Tailwind CSS

متغيرات البيئة المضمنة

خادم التطوير (وقت التشغيل)

البناء للإنتاج

مثال

صدى سجلات console من المتصفح إلى المحطة

تحرير الملفات في المتصفح

اختصارات لوحة المفاتيح

البناء للإنتاج

وضع المراقبة

واجهة برمجة تطبيقات المكونات الإضافية

ما تتم معالجته؟

كيف يعمل هذا

إضافة خلفية إلى الواجهة الأمامية