Lesson 14 / الدرس 14

Modules: import and export / الوحدات: import وexport

How a project stops being one enormous file. Each file keeps its own names, publishes the few it wants shared, and states plainly which other files it depends on.

كيف يكفّ مشروع عن كونه ملفًا ضخمًا واحدًا. فكل ملف يحتفظ بأسمائه، وينشر القليل الذي يريد مشاركته، ويصرّح بوضوح بالملفات الأخرى التي يعتمد عليها.

The problem modules solve

<script src="cart.js"></script>     the old way: two files,
<script src="search.js"></script>   one shared global scope

both files declare `let total` -> the second one wins, silently

Two ordinary scripts on one page share a single global scope, so a name used in both files is the same variable. The demonstration below shows that collision happening. Nothing errors; a value simply becomes wrong somewhere far from where it was set.

The syntax

// cart.js
export function add(price) { }        named export
export const TAX = 0.14;
export default class Cart { }         one default per file, optional

// main.js
import { add, TAX } from './cart.js';       named: braces, exact names
import Cart from './cart.js';               default: no braces, any name
import { add as addItem } from './cart.js'; renamed on the way in
import * as cart from './cart.js';          everything, under one name

<!-- in the HTML, once -->
<script type="module" src="main.js"></script>

Named imports use braces and must match the exported name exactly, which is the same destructuring shape from lesson 11. A default import has no braces and you may call it whatever you like. The page loads one entry file with type="module"; every other file arrives because something imported it.

والاستيرادات المسمّاة تستخدم أقواسًا معقوفة ويجب أن تطابق الاسم المصدَّر تمامًا، وهو شكل التفكيك نفسه من الدرس 11. والاستيراد الافتراضي بلا أقواس ولك أن تسميه ما شئت. والصفحة تحمّل ملف دخول واحدًا بـtype="module"؛ وكل ملف آخر يصل لأن شيئًا استورده.

A module file	An ordinary script
Top-level names stay private	Top-level names are global
Runs once, however many files import it	Runs once per script tag
Deferred — runs after the HTML is parsed	Blocks parsing where it sits
Always strict mode	Sloppy mode unless declared
Needs http:// or https://	Works from file:// too

The last row is the one that ambushes beginners, and it is worth the warning below.

وفتح ملف HTML فيه وحدات بالنقر المزدوج يفشل. فالعنوان يصير file://، والوحدات خاضعة لـCORS، والمتصفح يرفض الاستيراد برسالة عن الأصول لا تقول شيئًا عن السبب الحقيقي. والملف سليم؛ إنما يُقدَّم على نحو خاطئ. استخدم خادمًا محليًا — ودورة الطرفية تغطي هذا، وسطر واحد مثل php -S localhost:8000 في مجلد المشروع يكفي. والمعاينة بجوار هذه الدروس مستند واحد لا ملفات حوله، ولذلك يعرض البيان أعلاه المشكلة التي تحلها الوحدات لا الاستيرادات نفسها.

Two habits worth forming now. Prefer named exports to default ones: a default import can be given any name at all, so the same class ends up called three different things across a project and searching for it stops working. And import only what you use — import * as everything is rarely what you want, because it hides which parts of a file you actually depend on.

وعادتان جديرتان بالتكوين الآن. فضّل الصادرات المسمّاة على الافتراضية: فالاستيراد الافتراضي يمكن أن يُعطى أي اسم البتة، فينتهي الصنف نفسه بثلاثة أسماء مختلفة عبر مشروع ويكف البحث عنه عن العمل. واستورد ما تستخدمه فقط — فـimport * as everything نادرًا ما يكون مرادك، لأنه يخفي أي أجزاء الملف تعتمد عليها فعلًا.

Try it live / جرّب بنفسك

<pre id="out"></pre>

<script>
  var count = 0;
  function addOne() { count = count + 1; }
  addOne();
  addOne();
</script>

<script>
  // Somebody else's file. Same name, different meaning.
  var count = 99;
</script>

<script>
  document.getElementById('out').textContent =
    'The first script expected 2. It is: ' + count;
</script>

Preview / المعاينة

Check yourself / اختبر نفسك

1. What is the difference between a module file and an ordinary script?

2. Why does double-clicking an HTML file with modules fail?

3. Why prefer named exports to default ones?

Your task / مهمتك

On your own machine, split a small program into three files: a math.js with two named exports, a format.js with one, and a main.js that imports from both and writes the result into the page. Load it with one type="module" tag. Then do two things deliberately: open the page by double-clicking the file and record the exact error, and serve it properly and record that it works. In the editor here, reproduce the global-collision demonstration with two names of your own choosing and explain in a comment which value was lost.

على جهازك، قسّم برنامجًا صغيرًا إلى ثلاثة ملفات: math.js بصادرين مسمّيين، وformat.js بواحد، وmain.js يستورد من كليهما ويكتب النتيجة في الصفحة. حمّله بوسم type="module" واحد. ثم افعل شيئين عمدًا: افتح الصفحة بالنقر المزدوج وسجّل الخطأ بنصه، وقدّمها بشكل صحيح وسجّل أنها تعمل. وفي المحرر هنا، أعد إنتاج بيان التصادم العام باسمين من اختيارك واشرح في تعليق أي قيمة ضاعت.

Three files, named exports, one module tag ثلاثة ملفات وصادرات مسمّاة ووسم وحدة واحد
The file:// error recorded verbatim خطأ file:// مسجَّلًا بنصه
The same page working from a local server الصفحة نفسها تعمل من خادم محلي
A collision reproduced here, with the lost value named تصادم مُعاد إنتاجه هنا مع تسمية القيمة الضائعة