# 01 - Widget Build Tooling Concepts

Welcome to the learning guide for **Milestone 1, Step 1.3** of the Universal Chatbot Widget project!

In this document, we explain the core concepts behind modern frontend build tooling from first principles.

---

## 1. What is Browser JavaScript?
Browser JavaScript is code executed directly inside a web browser engine (like Chrome V8, Firefox SpiderMonkey, or Safari JavaScriptCore). Browsers read HTML, fetch script tags, and execute JavaScript to make web pages interactive.

---

## 2. What does "Vanilla JavaScript" mean?
**Vanilla JavaScript** means plain, native JavaScript without using any heavy frontend frameworks or libraries like React, Vue, Angular, or jQuery.

### Why Vanilla JS for an Embeddable Widget?
- **Zero Heavy Dependencies:** Host websites don't need to load 500KB of React just to display a chat widget.
- **Fast Execution:** Vanilla JS boots up instantly in any browser.
- **Compatibility:** Runs everywhere without framework version conflicts.

---

## 3. What is Node.js and npm?
- **Node.js:** A JavaScript runtime environment that lets developers run JavaScript outside the browser (e.g. on your laptop command line).
- **npm (Node Package Manager):** The standard package manager and dependency registry for Node.js. It helps download build tools and manage project scripts.

---

## 4. What is `package.json`?
`package.json` is the manifest file for a JavaScript/Node project. It records:
- **Project details:** Name, version, description, author.
- **Scripts:** Command shortcuts (e.g. `npm run build` or `npm run watch`).
- **Dependencies (`devDependencies`):** External build tools required during development (e.g. `esbuild`).

---

## 5. What is a Build Dependency?
A **dependency** is third-party code or tooling that your project relies on.
- **`dependencies`:** Code required at application runtime.
- **`devDependencies`:** Tools required only during development/building (e.g. `esbuild`). Our end users never need Node or npm—they only load the output `dist/widget.js`.

---

## 6. What is Bundling & Why Use `esbuild`?

### What is Bundling?
As a project grows, source code is split across dozens of smaller JavaScript modules (for UI, network, state, etc.). Browsers struggle if they have to download 50 separate files over HTTP.

**Bundling** takes multiple source files and combines them into **one optimized, single browser-loadable file** (`dist/widget.js`).

### Why `esbuild`?
`esbuild` is an extremely fast, next-generation JavaScript bundler written in Go.
- **Blazing Fast:** Bundles scripts in milliseconds (over 100x faster than traditional tools like Webpack).
- **Zero Config:** Works out-of-the-box with simple CLI flags (`--bundle`, `--format=iife`).

---

## 7. Summary
- Customers install our widget using one script tag: `<script src=".../widget.js"></script>`.
- We write clean source code in `src/widget.js`.
- `esbuild` bundles it into `dist/widget.js`.
- The customer's browser loads the bundled file effortlessly.