Tweaks to bundler docs (#2867)

* WIP

* Fix typo

* Updates

* Document --compile

* Add bundler benchmark

* Remove esbuild

* Add bench to docs

* Add buttons

* Updates

7 files changed, 243 insertions, 0 deletions

diff --git a/bench/bundle/.gitignore b/bench/bundle/.gitignore
new file mode 100644
index 000000000..6463d8435
--- /dev/null
+++ b/bench/bundle/.gitignore
@@ -0,0 +1,171 @@
+# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*
+
+esbuild
\ No newline at end of file
diff --git a/bench/bundle/README.md b/bench/bundle/README.md
new file mode 100644
index 000000000..e973fcd35
--- /dev/null
+++ b/bench/bundle/README.md
@@ -0,0 +1,40 @@
+# Bundler benchmark
+
+This is a performance benchmark of the following bundlers:
+
+- Bun
+- esbuild
+- Parcel 2
+- Rollup + Terser
+- Webpack
+
+It is an exact copy of [`esbuild`'s benchmark](https://github.com/evanw/esbuild/blob/main/Makefile), aside from the fast that Bun [has been added](https://github.com/colinhacks/esbuild/commit/1b928b7981aa7edfadf77fcf8931bb8d6f38cd96). The benchmark bundles 10 copies of the large [three.js](https://threejs.org/), with minification and source maps enabled.
+
+To run the benchmark:
+
+```sh
+$ chmod +x run-bench.sh
+$ ./run-bench.sh
+```
+
+Various output will be written to the console by each bundler. Scan through the results for lines that look like this underneath each bundler output:
+
+```sh
+real <number>
+user <number>
+sys <number>
+```
+
+These lines are generated by the `time` command which is used to benchmark each build.
+
+## Results
+
+The `real` results, as run on a 16-inch M1 Macbook Pro:
+
+| Bundler | Time   |
+| ------- | ------ |
+| Bun     | 0.17s  |
+| esbuild | 0.33s  |
+| Rollup  | 18.82s |
+| Webpack | 26.21  |
+| Parcel  | 17.95s |
diff --git a/bench/bundle/bun.lockb b/bench/bundle/bun.lockb
new file mode 100755
index 000000000..b5ea51df5
--- /dev/null
+++ b/bench/bundle/bun.lockb
diff --git a/bench/bundle/index.ts b/bench/bundle/index.ts
new file mode 100644
index 000000000..f67b2c645
--- /dev/null
+++ b/bench/bundle/index.ts
@@ -0,0 +1 @@
+console.log("Hello via Bun!");
\ No newline at end of file
diff --git a/bench/bundle/package.json b/bench/bundle/package.json
new file mode 100644
index 000000000..c80d9b81e
--- /dev/null
+++ b/bench/bundle/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "bundle",
+  "module": "index.ts",
+  "type": "module",
+  "devDependencies": {
+    "bun-types": "^0.5.0"
+  }
+}
\ No newline at end of file
diff --git a/bench/bundle/run-bench.sh b/bench/bundle/run-bench.sh
new file mode 100755
index 000000000..c14a370d5
--- /dev/null
+++ b/bench/bundle/run-bench.sh
@@ -0,0 +1,3 @@
+git clone git@github.com:colinhacks/esbuild.git
+cd esbuild
+make bench-three
\ No newline at end of file
diff --git a/bench/bundle/tsconfig.json b/bench/bundle/tsconfig.json
new file mode 100644
index 000000000..5c0ced989
--- /dev/null
+++ b/bench/bundle/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext"
+    ],
+    "module": "esnext",
+    "target": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "downlevelIteration": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowJs": true,
+    "types": [
+      "bun-types" // add Bun global
+    ]
+  }
+}
\ No newline at end of file