aboutsummaryrefslogtreecommitdiff
path: root/docs/bundler/intro.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/bundler/intro.md75
1 files changed, 75 insertions, 0 deletions
diff --git a/docs/bundler/intro.md b/docs/bundler/intro.md
new file mode 100644
index 000000000..5056c26a9
--- /dev/null
+++ b/docs/bundler/intro.md
@@ -0,0 +1,75 @@
+<!-- This document is a work in progress. It's not currently included in the actual docs. -->
+
+The goal of this document is to break down why bundling is necessary, how it works, and how the bundler became such a key part of modern JavaScript development. The content is not specific to Bun's bundler, but is rather aimed at anyone looking for a greater understanding of how bundlers work and, by extension, how most modern frameworks are implemented.
+
+## What is bundling
+
+With the adoption of ECMAScript modules (ESM), browsers can now resolve `import`/`export` statements in JavaScript files loaded via `<script>` tags.
+
+{% codetabs %}
+
+```html#index.html
+<html>
+ <head>
+ <script type="module" src="/index.js" ></script>
+ </head>
+</html>
+```
+
+```js#index.js
+import {sayHello} from "./hello.js";
+
+sayHello();
+```
+
+```js#hello.js
+export function sayHello() {
+ console.log("Hello, world!");
+}
+```
+
+{% /codetabs %}
+
+When a user visits this website, the files are loaded in the following order:
+
+{% image src="/images/module_loading_unbundled.png" /%}
+
+{% callout %}
+**Relative imports** — Relative imports are resolved relative to the URL of the importing file. Because we're importing `./hello.js` from `/index.js`, the browser resolves it to `/hello.js`. If instead we'd imported `./hello.js` from `/src/index.js`, the browser would have resolved it to `/src/hello.js`.
+{% /callout %}
+
+This approach works, it requires three round-trip HTTP requests before the browser is ready to render the page. On slow internet connections, this may add up to a non-trivial delay.
+
+This example is extremely simplistic. A modern app may be loading dozens of modules from `node_modules`, each consisting of hundrends of files. Loading each of these files with a separate HTTP request becomes untenable very quickly. While most of these requests will be running in parallel, the number of round-trip requests can still be very high; plus, there are limits on how many simultaneous requests a browser can make.
+
+{% callout %}
+Some recent advances like modulepreload and HTTP/3 are intended to solve some of these problems, but at the moment bundling is still the most performant approach.
+{% /callout %}
+
+The answer: bundling.
+
+## Entrypoints
+
+A bundler accepts an "entrypoint" to your source code (in this case, `/index.js`) and outputs a single file containing all of the code needed to run your app. If does so by parsing your source code, reading the `import`/`export` statements, and building a "module graph" of your app's dependencies.
+
+{% image src="/images/bundling.png" /%}
+
+We can now load `/bundle.js` from our `index.html` file and eliminate a round trip request, decreasing load times for our app.
+
+{% image src="/images/module_loading_bundled.png" /%}
+
+## Loaders
+
+Bundlers typically have some set of built-in "loaders".
+
+## Transpilation
+
+The JavaScript files above are just that: plain JavaScript. They can be directly executed by any modern browser.
+
+But modern tooling goes far beyond HTML, JavaScript, and CSS. JSX, TypeScript, and PostCSS/CSS-in-JS are all popular technologies that involve non-standard syntax that must be converted into vanilla JavaScript and CSS before if can be consumed by a browser.
+
+## Chunking
+
+## Module resolution
+
+## Plugins