# 02 - esbuild & IIFE Architecture

This document explains the esbuild CLI command flags and the Immediately Invoked Function Expression (IIFE) format.

---

## 1. Deconstructing the Build Command

In `widget/package.json`, the build script is defined as:

```json
"scripts": {
  "build": "esbuild src/widget.js --bundle --format=iife --outfile=dist/widget.js"
}
```

When you run `npm run build`, npm executes the underlying `esbuild` command:

```bash
esbuild src/widget.js --bundle --format=iife --outfile=dist/widget.js
```

### Breakdown of Command Flags:

| Flag / Argument | Purpose |
|---|---|
| `src/widget.js` | **Entry point:** The source file where esbuild begins reading code and resolving imports. |
| `--bundle` | Recursively resolves and merges all imported files and dependencies into a single output file. |
| `--format=iife` | Wraps the output in an Immediately Invoked Function Expression (IIFE) for browser execution. |
| `--outfile=dist/widget.js` | Specifies the destination path for the compiled output bundle. |

---

## 2. What is an IIFE? (Immediately Invoked Function Expression)

An **IIFE** is a JavaScript function that runs as soon as it is defined.

### Syntax:
```javascript
(() => {
  // Widget code runs inside here immediately!
})();
```

---

## 3. Why IIFE is Essential for Third-Party Embeddable Widgets

Our chatbot widget will be embedded on thousands of host websites (Shopify, WordPress, custom React apps, etc.).

### Problem: Scope Pollution & Conflicts
If the widget script uses global variables like `var config = ...` or `function init()`, it risks:
1. Overwriting global variables on the host site.
2. Having its own variables overwritten by the host site's scripts.

### Solution: IIFE Encapsulation
An IIFE creates a private closure scope. Everything defined inside the IIFE stays inside the IIFE.
- Zero pollution of host website `window` scope.
- Zero risk of global variable name collisions.
- Automatically executes when loaded via `<script src="widget.js"></script>` without requiring host sites to call any manual import functions.

---

## 4. Module System Comparisons

| Format | Execution Environment | Manual Import Needed? | Suitable for Widget Tag? |
|---|---|---|---|
| **IIFE** (`--format=iife`) | Browsers (`<script src="...">`) | **No** (Executes automatically) | **YES (Ideal)** |
| **ES Module** (`import / export`) | Modern browsers (`type="module"`) | **Yes** (`import ...`) | No (Requires host setup) |
| **CommonJS** (`require`) | Node.js backend | **Yes** (`require(...)`) | No (Not browser native) |

---

## 5. Generated Output Inspection

Source file (`src/widget.js`):
```javascript
(function () {
  console.log("Universal Chatbot Widget loaded");
})();
```

Generated bundle (`dist/widget.js`):
```javascript
(() => {
  // src/widget.js
  (function() {
    console.log("Universal Chatbot Widget loaded");
  })();
})();
```

Notice how esbuild cleanly safely wraps the code inside an IIFE arrow function (`(() => { ... })();`).