diff options
Diffstat (limited to '')
-rw-r--r-- | docs/bundler/intro.md | 75 |
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 |