bun-types 1.3.2-canary.20251106T140813 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (316) hide show
  1. package/bun.d.ts +102 -6
  2. package/docs/bundler/bytecode.mdx +465 -0
  3. package/docs/bundler/css.mdx +1024 -0
  4. package/docs/bundler/esbuild.mdx +253 -0
  5. package/docs/bundler/executables.mdx +535 -0
  6. package/docs/bundler/fullstack.mdx +1064 -0
  7. package/docs/bundler/hot-reloading.mdx +229 -0
  8. package/docs/bundler/html-static.mdx +386 -0
  9. package/docs/bundler/index.mdx +1499 -0
  10. package/docs/bundler/loaders.mdx +356 -0
  11. package/docs/bundler/macros.mdx +328 -0
  12. package/docs/bundler/minifier.mdx +1306 -0
  13. package/docs/bundler/plugins.mdx +411 -0
  14. package/docs/feedback.mdx +85 -0
  15. package/docs/guides/binary/arraybuffer-to-array.mdx +29 -0
  16. package/docs/guides/binary/arraybuffer-to-blob.mdx +26 -0
  17. package/docs/guides/binary/arraybuffer-to-buffer.mdx +27 -0
  18. package/docs/guides/binary/arraybuffer-to-string.mdx +17 -0
  19. package/docs/guides/binary/arraybuffer-to-typedarray.mdx +41 -0
  20. package/docs/guides/binary/blob-to-arraybuffer.mdx +16 -0
  21. package/docs/guides/binary/blob-to-dataview.mdx +16 -0
  22. package/docs/guides/binary/blob-to-stream.mdx +16 -0
  23. package/docs/guides/binary/blob-to-string.mdx +17 -0
  24. package/docs/guides/binary/blob-to-typedarray.mdx +16 -0
  25. package/docs/guides/binary/buffer-to-arraybuffer.mdx +16 -0
  26. package/docs/guides/binary/buffer-to-blob.mdx +16 -0
  27. package/docs/guides/binary/buffer-to-readablestream.mdx +43 -0
  28. package/docs/guides/binary/buffer-to-string.mdx +27 -0
  29. package/docs/guides/binary/buffer-to-typedarray.mdx +16 -0
  30. package/docs/guides/binary/dataview-to-string.mdx +17 -0
  31. package/docs/guides/binary/typedarray-to-arraybuffer.mdx +27 -0
  32. package/docs/guides/binary/typedarray-to-blob.mdx +18 -0
  33. package/docs/guides/binary/typedarray-to-buffer.mdx +16 -0
  34. package/docs/guides/binary/typedarray-to-dataview.mdx +16 -0
  35. package/docs/guides/binary/typedarray-to-readablestream.mdx +43 -0
  36. package/docs/guides/binary/typedarray-to-string.mdx +18 -0
  37. package/docs/guides/deployment/aws-lambda.mdx +204 -0
  38. package/docs/guides/deployment/digital-ocean.mdx +161 -0
  39. package/docs/guides/deployment/google-cloud-run.mdx +197 -0
  40. package/docs/guides/deployment/railway.mdx +145 -0
  41. package/docs/guides/deployment/render.mdx +82 -0
  42. package/docs/guides/deployment/vercel.mdx +99 -0
  43. package/docs/guides/ecosystem/astro.mdx +82 -0
  44. package/docs/guides/ecosystem/discordjs.mdx +80 -0
  45. package/docs/guides/ecosystem/docker.mdx +151 -0
  46. package/docs/guides/ecosystem/drizzle.mdx +195 -0
  47. package/docs/guides/ecosystem/edgedb.mdx +257 -0
  48. package/docs/guides/ecosystem/elysia.mdx +31 -0
  49. package/docs/guides/ecosystem/express.mdx +43 -0
  50. package/docs/guides/ecosystem/hono.mdx +47 -0
  51. package/docs/guides/ecosystem/mongoose.mdx +92 -0
  52. package/docs/guides/ecosystem/neon-drizzle.mdx +234 -0
  53. package/docs/guides/ecosystem/neon-serverless-postgres.mdx +60 -0
  54. package/docs/guides/ecosystem/nextjs.mdx +57 -0
  55. package/docs/guides/ecosystem/nuxt.mdx +90 -0
  56. package/docs/guides/ecosystem/pm2.mdx +55 -0
  57. package/docs/guides/ecosystem/prisma-postgres.mdx +169 -0
  58. package/docs/guides/ecosystem/prisma.mdx +164 -0
  59. package/docs/guides/ecosystem/qwik.mdx +114 -0
  60. package/docs/guides/ecosystem/react.mdx +52 -0
  61. package/docs/guides/ecosystem/remix.mdx +97 -0
  62. package/docs/guides/ecosystem/sentry.mdx +54 -0
  63. package/docs/guides/ecosystem/solidstart.mdx +66 -0
  64. package/docs/guides/ecosystem/ssr-react.mdx +49 -0
  65. package/docs/guides/ecosystem/stric.mdx +54 -0
  66. package/docs/guides/ecosystem/sveltekit.mdx +138 -0
  67. package/docs/guides/ecosystem/systemd.mdx +114 -0
  68. package/docs/guides/ecosystem/upstash.mdx +87 -0
  69. package/docs/guides/ecosystem/vite.mdx +77 -0
  70. package/docs/guides/html-rewriter/extract-links.mdx +72 -0
  71. package/docs/guides/html-rewriter/extract-social-meta.mdx +97 -0
  72. package/docs/guides/http/cluster.mdx +69 -0
  73. package/docs/guides/http/fetch-unix.mdx +35 -0
  74. package/docs/guides/http/fetch.mdx +26 -0
  75. package/docs/guides/http/file-uploads.mdx +97 -0
  76. package/docs/guides/http/hot.mdx +28 -0
  77. package/docs/guides/http/proxy.mdx +26 -0
  78. package/docs/guides/http/server.mdx +48 -0
  79. package/docs/guides/http/simple.mdx +20 -0
  80. package/docs/guides/http/stream-file.mdx +50 -0
  81. package/docs/guides/http/stream-iterator.mdx +49 -0
  82. package/docs/guides/http/stream-node-streams-in-bun.mdx +22 -0
  83. package/docs/guides/http/tls.mdx +32 -0
  84. package/docs/guides/index.mdx +10 -0
  85. package/docs/guides/install/add-dev.mdx +28 -0
  86. package/docs/guides/install/add-git.mdx +38 -0
  87. package/docs/guides/install/add-optional.mdx +27 -0
  88. package/docs/guides/install/add-peer.mdx +45 -0
  89. package/docs/guides/install/add-tarball.mdx +35 -0
  90. package/docs/guides/install/add.mdx +44 -0
  91. package/docs/guides/install/azure-artifacts.mdx +76 -0
  92. package/docs/guides/install/cicd.mdx +43 -0
  93. package/docs/guides/install/custom-registry.mdx +32 -0
  94. package/docs/guides/install/from-npm-install-to-bun-install.mdx +230 -0
  95. package/docs/guides/install/git-diff-bun-lockfile.mdx +47 -0
  96. package/docs/guides/install/jfrog-artifactory.mdx +28 -0
  97. package/docs/guides/install/npm-alias.mdx +25 -0
  98. package/docs/guides/install/registry-scope.mdx +40 -0
  99. package/docs/guides/install/trusted.mdx +50 -0
  100. package/docs/guides/install/workspaces.mdx +70 -0
  101. package/docs/guides/install/yarnlock.mdx +50 -0
  102. package/docs/guides/process/argv.mdx +66 -0
  103. package/docs/guides/process/ctrl-c.mdx +18 -0
  104. package/docs/guides/process/ipc.mdx +69 -0
  105. package/docs/guides/process/nanoseconds.mdx +15 -0
  106. package/docs/guides/process/os-signals.mdx +41 -0
  107. package/docs/guides/process/spawn-stderr.mdx +34 -0
  108. package/docs/guides/process/spawn-stdout.mdx +28 -0
  109. package/docs/guides/process/spawn.mdx +43 -0
  110. package/docs/guides/process/stdin.mdx +62 -0
  111. package/docs/guides/read-file/arraybuffer.mdx +30 -0
  112. package/docs/guides/read-file/buffer.mdx +21 -0
  113. package/docs/guides/read-file/exists.mdx +18 -0
  114. package/docs/guides/read-file/json.mdx +19 -0
  115. package/docs/guides/read-file/mime.mdx +22 -0
  116. package/docs/guides/read-file/stream.mdx +28 -0
  117. package/docs/guides/read-file/string.mdx +24 -0
  118. package/docs/guides/read-file/uint8array.mdx +23 -0
  119. package/docs/guides/read-file/watch.mdx +66 -0
  120. package/docs/guides/runtime/build-time-constants.mdx +295 -0
  121. package/docs/guides/runtime/cicd.mdx +45 -0
  122. package/docs/guides/runtime/codesign-macos-executable.mdx +61 -0
  123. package/docs/guides/runtime/define-constant.mdx +149 -0
  124. package/docs/guides/runtime/delete-directory.mdx +39 -0
  125. package/docs/guides/runtime/delete-file.mdx +21 -0
  126. package/docs/guides/runtime/heap-snapshot.mdx +28 -0
  127. package/docs/guides/runtime/import-html.mdx +17 -0
  128. package/docs/guides/runtime/import-json.mdx +46 -0
  129. package/docs/guides/runtime/import-toml.mdx +32 -0
  130. package/docs/guides/runtime/import-yaml.mdx +104 -0
  131. package/docs/guides/runtime/read-env.mdx +37 -0
  132. package/docs/guides/runtime/set-env.mdx +51 -0
  133. package/docs/guides/runtime/shell.mdx +42 -0
  134. package/docs/guides/runtime/timezone.mdx +38 -0
  135. package/docs/guides/runtime/tsconfig-paths.mdx +31 -0
  136. package/docs/guides/runtime/typescript.mdx +51 -0
  137. package/docs/guides/runtime/vscode-debugger.mdx +48 -0
  138. package/docs/guides/runtime/web-debugger.mdx +103 -0
  139. package/docs/guides/streams/node-readable-to-arraybuffer.mdx +13 -0
  140. package/docs/guides/streams/node-readable-to-blob.mdx +13 -0
  141. package/docs/guides/streams/node-readable-to-json.mdx +14 -0
  142. package/docs/guides/streams/node-readable-to-string.mdx +14 -0
  143. package/docs/guides/streams/node-readable-to-uint8array.mdx +13 -0
  144. package/docs/guides/streams/to-array.mdx +16 -0
  145. package/docs/guides/streams/to-arraybuffer.mdx +16 -0
  146. package/docs/guides/streams/to-blob.mdx +16 -0
  147. package/docs/guides/streams/to-buffer.mdx +17 -0
  148. package/docs/guides/streams/to-json.mdx +16 -0
  149. package/docs/guides/streams/to-string.mdx +16 -0
  150. package/docs/guides/streams/to-typedarray.mdx +24 -0
  151. package/docs/guides/test/bail.mdx +24 -0
  152. package/docs/guides/test/coverage-threshold.mdx +67 -0
  153. package/docs/guides/test/coverage.mdx +49 -0
  154. package/docs/guides/test/happy-dom.mdx +73 -0
  155. package/docs/guides/test/migrate-from-jest.mdx +125 -0
  156. package/docs/guides/test/mock-clock.mdx +50 -0
  157. package/docs/guides/test/mock-functions.mdx +70 -0
  158. package/docs/guides/test/rerun-each.mdx +16 -0
  159. package/docs/guides/test/run-tests.mdx +116 -0
  160. package/docs/guides/test/skip-tests.mdx +43 -0
  161. package/docs/guides/test/snapshot.mdx +102 -0
  162. package/docs/guides/test/spy-on.mdx +49 -0
  163. package/docs/guides/test/svelte-test.mdx +113 -0
  164. package/docs/guides/test/testing-library.mdx +93 -0
  165. package/docs/guides/test/timeout.mdx +17 -0
  166. package/docs/guides/test/todo-tests.mdx +74 -0
  167. package/docs/guides/test/update-snapshots.mdx +49 -0
  168. package/docs/guides/test/watch-mode.mdx +24 -0
  169. package/docs/guides/util/base64.mdx +17 -0
  170. package/docs/guides/util/deep-equals.mdx +41 -0
  171. package/docs/guides/util/deflate.mdx +20 -0
  172. package/docs/guides/util/detect-bun.mdx +25 -0
  173. package/docs/guides/util/entrypoint.mdx +19 -0
  174. package/docs/guides/util/escape-html.mdx +24 -0
  175. package/docs/guides/util/file-url-to-path.mdx +16 -0
  176. package/docs/guides/util/gzip.mdx +20 -0
  177. package/docs/guides/util/hash-a-password.mdx +56 -0
  178. package/docs/guides/util/import-meta-dir.mdx +15 -0
  179. package/docs/guides/util/import-meta-file.mdx +15 -0
  180. package/docs/guides/util/import-meta-path.mdx +15 -0
  181. package/docs/guides/util/javascript-uuid.mdx +25 -0
  182. package/docs/guides/util/main.mdx +43 -0
  183. package/docs/guides/util/path-to-file-url.mdx +16 -0
  184. package/docs/guides/util/sleep.mdx +24 -0
  185. package/docs/guides/util/version.mdx +23 -0
  186. package/docs/guides/util/which-path-to-executable-bin.mdx +17 -0
  187. package/docs/guides/websocket/compression.mdx +33 -0
  188. package/docs/guides/websocket/context.mdx +74 -0
  189. package/docs/guides/websocket/pubsub.mdx +40 -0
  190. package/docs/guides/websocket/simple.mdx +35 -0
  191. package/docs/guides/write-file/append.mdx +54 -0
  192. package/docs/guides/write-file/basic.mdx +46 -0
  193. package/docs/guides/write-file/blob.mdx +30 -0
  194. package/docs/guides/write-file/cat.mdx +19 -0
  195. package/docs/guides/write-file/file-cp.mdx +18 -0
  196. package/docs/guides/write-file/filesink.mdx +54 -0
  197. package/docs/guides/write-file/response.mdx +19 -0
  198. package/docs/guides/write-file/stdout.mdx +23 -0
  199. package/docs/guides/write-file/stream.mdx +19 -0
  200. package/docs/guides/write-file/unlink.mdx +18 -0
  201. package/docs/index.mdx +133 -0
  202. package/docs/installation.mdx +365 -0
  203. package/docs/pm/bunx.mdx +83 -0
  204. package/docs/pm/catalogs.mdx +292 -0
  205. package/docs/pm/cli/add.mdx +179 -0
  206. package/docs/pm/cli/audit.mdx +60 -0
  207. package/docs/pm/cli/install.mdx +471 -0
  208. package/docs/pm/cli/link.mdx +48 -0
  209. package/docs/pm/cli/outdated.mdx +197 -0
  210. package/docs/pm/cli/patch.mdx +69 -0
  211. package/docs/pm/cli/pm.mdx +319 -0
  212. package/docs/pm/cli/publish.mdx +123 -0
  213. package/docs/pm/cli/remove.mdx +16 -0
  214. package/docs/pm/cli/update.mdx +140 -0
  215. package/docs/pm/cli/why.mdx +84 -0
  216. package/docs/pm/filter.mdx +102 -0
  217. package/docs/pm/global-cache.mdx +72 -0
  218. package/docs/pm/isolated-installs.mdx +205 -0
  219. package/docs/pm/lifecycle.mdx +57 -0
  220. package/docs/pm/lockfile.mdx +64 -0
  221. package/docs/pm/npmrc.mdx +111 -0
  222. package/docs/pm/overrides.mdx +83 -0
  223. package/docs/pm/scopes-registries.mdx +35 -0
  224. package/docs/pm/security-scanner-api.mdx +95 -0
  225. package/docs/pm/workspaces.mdx +109 -0
  226. package/docs/project/benchmarking.mdx +218 -0
  227. package/docs/project/bindgen.mdx +223 -0
  228. package/docs/project/building-windows.mdx +133 -0
  229. package/docs/project/contributing.mdx +343 -0
  230. package/docs/project/feedback.mdx +20 -0
  231. package/docs/project/license.mdx +78 -0
  232. package/docs/project/roadmap.mdx +8 -0
  233. package/docs/quickstart.mdx +240 -0
  234. package/docs/runtime/auto-install.mdx +97 -0
  235. package/docs/runtime/binary-data.mdx +846 -0
  236. package/docs/runtime/bun-apis.mdx +59 -0
  237. package/docs/runtime/bunfig.mdx +642 -0
  238. package/docs/runtime/c-compiler.mdx +204 -0
  239. package/docs/runtime/child-process.mdx +532 -0
  240. package/docs/runtime/color.mdx +267 -0
  241. package/docs/runtime/console.mdx +67 -0
  242. package/docs/runtime/cookies.mdx +454 -0
  243. package/docs/runtime/debugger.mdx +335 -0
  244. package/docs/runtime/environment-variables.mdx +214 -0
  245. package/docs/runtime/ffi.mdx +565 -0
  246. package/docs/runtime/file-io.mdx +306 -0
  247. package/docs/runtime/file-system-router.mdx +118 -0
  248. package/docs/runtime/file-types.mdx +354 -0
  249. package/docs/runtime/glob.mdx +181 -0
  250. package/docs/runtime/globals.mdx +72 -0
  251. package/docs/runtime/hashing.mdx +315 -0
  252. package/docs/runtime/html-rewriter.mdx +340 -0
  253. package/docs/runtime/http/cookies.mdx +79 -0
  254. package/docs/runtime/http/error-handling.mdx +40 -0
  255. package/docs/runtime/http/metrics.mdx +36 -0
  256. package/docs/runtime/http/routing.mdx +289 -0
  257. package/docs/runtime/http/server.mdx +647 -0
  258. package/docs/runtime/http/tls.mdx +101 -0
  259. package/docs/runtime/http/websockets.mdx +404 -0
  260. package/docs/runtime/index.mdx +223 -0
  261. package/docs/runtime/jsx.mdx +115 -0
  262. package/docs/runtime/module-resolution.mdx +342 -0
  263. package/docs/runtime/networking/dns.mdx +111 -0
  264. package/docs/runtime/networking/fetch.mdx +468 -0
  265. package/docs/runtime/networking/tcp.mdx +239 -0
  266. package/docs/runtime/networking/udp.mdx +129 -0
  267. package/docs/runtime/node-api.mdx +19 -0
  268. package/docs/runtime/nodejs-compat.mdx +468 -0
  269. package/docs/runtime/plugins.mdx +405 -0
  270. package/docs/runtime/redis.mdx +582 -0
  271. package/docs/runtime/s3.mdx +863 -0
  272. package/docs/runtime/secrets.mdx +336 -0
  273. package/docs/runtime/semver.mdx +57 -0
  274. package/docs/runtime/shell.mdx +637 -0
  275. package/docs/runtime/sql.mdx +1404 -0
  276. package/docs/runtime/sqlite.mdx +699 -0
  277. package/docs/runtime/streams.mdx +232 -0
  278. package/docs/runtime/templating/create.mdx +269 -0
  279. package/docs/runtime/templating/init.mdx +58 -0
  280. package/docs/runtime/transpiler.mdx +288 -0
  281. package/docs/runtime/typescript.mdx +58 -0
  282. package/docs/runtime/utils.mdx +922 -0
  283. package/docs/runtime/watch-mode.mdx +161 -0
  284. package/docs/runtime/web-apis.mdx +29 -0
  285. package/docs/runtime/workers.mdx +328 -0
  286. package/docs/runtime/yaml.mdx +469 -0
  287. package/docs/snippets/cli/add.mdx +166 -0
  288. package/docs/snippets/cli/build.mdx +196 -0
  289. package/docs/snippets/cli/feedback.mdx +17 -0
  290. package/docs/snippets/cli/init.mdx +84 -0
  291. package/docs/snippets/cli/install.mdx +173 -0
  292. package/docs/snippets/cli/link.mdx +163 -0
  293. package/docs/snippets/cli/outdated.mdx +140 -0
  294. package/docs/snippets/cli/patch.mdx +171 -0
  295. package/docs/snippets/cli/publish.mdx +198 -0
  296. package/docs/snippets/cli/remove.mdx +146 -0
  297. package/docs/snippets/cli/run.mdx +293 -0
  298. package/docs/snippets/cli/test.mdx +100 -0
  299. package/docs/snippets/cli/update.mdx +144 -0
  300. package/docs/snippets/product-card.mdx +32 -0
  301. package/docs/snippets/product-tiles.mdx +94 -0
  302. package/docs/test/code-coverage.mdx +409 -0
  303. package/docs/test/configuration.mdx +467 -0
  304. package/docs/test/dates-times.mdx +129 -0
  305. package/docs/test/discovery.mdx +90 -0
  306. package/docs/test/dom.mdx +226 -0
  307. package/docs/test/index.mdx +380 -0
  308. package/docs/test/lifecycle.mdx +348 -0
  309. package/docs/test/mocks.mdx +637 -0
  310. package/docs/test/reporters.mdx +117 -0
  311. package/docs/test/runtime-behavior.mdx +342 -0
  312. package/docs/test/snapshots.mdx +434 -0
  313. package/docs/test/writing-tests.mdx +635 -0
  314. package/docs/typescript.mdx +54 -0
  315. package/package.json +8 -6
  316. package/test.d.ts +2 -2
@@ -0,0 +1,354 @@
1
+ ---
2
+ title: "File Types"
3
+ description: "File types and loaders supported by Bun's bundler and runtime"
4
+ ---
5
+
6
+ The Bun bundler implements a set of default loaders out of the box. As a rule of thumb, the bundler and the runtime both support the same set of file types out of the box.
7
+
8
+ `.js` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` `.jsx` `.toml` `.json` `.txt` `.wasm` `.node` `.html`
9
+
10
+ Bun uses the file extension to determine which built-in _loader_ should be used to parse the file. Every loader has a name, such as `js`, `tsx`, or `json`. These names are used when building [plugins](/bundler/plugins) that extend Bun with custom loaders.
11
+
12
+ You can explicitly specify which loader to use using the 'loader' import attribute.
13
+
14
+ ```ts
15
+ import my_toml from "./my_file" with { loader: "toml" };
16
+ ```
17
+
18
+ ---
19
+
20
+ ## Built-in loaders
21
+
22
+ ### `js`
23
+
24
+ **JavaScript**. Default for `.cjs` and `.mjs`.
25
+
26
+ Parses the code and applies a set of default transforms like dead-code elimination and tree shaking. Note that Bun does not attempt to down-convert syntax at the moment.
27
+
28
+ ### `jsx`
29
+
30
+ **JavaScript + JSX.**. Default for `.js` and `.jsx`.
31
+
32
+ Same as the `js` loader, but JSX syntax is supported. By default, JSX is down-converted to plain JavaScript; the details of how this is done depends on the `jsx*` compiler options in your `tsconfig.json`. Refer to the TypeScript documentation [on JSX](https://www.typescriptlang.org/docs/handbook/jsx.html) for more information.
33
+
34
+ ### `ts`
35
+
36
+ **TypeScript loader**. Default for `.ts`, `.mts`, and `.cts`.
37
+
38
+ Strips out all TypeScript syntax, then behaves identically to the `js` loader. Bun does not perform typechecking.
39
+
40
+ ### `tsx`
41
+
42
+ **TypeScript + JSX loader**. Default for `.tsx`. Transpiles both TypeScript and JSX to vanilla JavaScript.
43
+
44
+ ### `json`
45
+
46
+ **JSON loader**. Default for `.json`.
47
+
48
+ JSON files can be directly imported.
49
+
50
+ ```ts
51
+ import pkg from "./package.json";
52
+ pkg.name; // => "my-package"
53
+ ```
54
+
55
+ During bundling, the parsed JSON is inlined into the bundle as a JavaScript object.
56
+
57
+ ```ts
58
+ var pkg = {
59
+ name: "my-package",
60
+ // ... other fields
61
+ };
62
+ pkg.name;
63
+ ```
64
+
65
+ If a `.json` file is passed as an entrypoint to the bundler, it will be converted to a `.js` module that `export default`s the parsed object.
66
+
67
+ <CodeGroup>
68
+
69
+ ```json Input
70
+ {
71
+ "name": "John Doe",
72
+ "age": 35,
73
+ "email": "johndoe@example.com"
74
+ }
75
+ ```
76
+
77
+ ```ts Output
78
+ export default {
79
+ name: "John Doe",
80
+ age: 35,
81
+ email: "johndoe@example.com",
82
+ };
83
+ ```
84
+
85
+ </CodeGroup>
86
+
87
+ ### `toml`
88
+
89
+ **TOML loader**. Default for `.toml`.
90
+
91
+ TOML files can be directly imported. Bun will parse them with its fast native TOML parser.
92
+
93
+ ```ts
94
+ import config from "./bunfig.toml";
95
+ config.logLevel; // => "debug"
96
+
97
+ // via import attribute:
98
+ // import myCustomTOML from './my.config' with {type: "toml"};
99
+ ```
100
+
101
+ During bundling, the parsed TOML is inlined into the bundle as a JavaScript object.
102
+
103
+ ```ts
104
+ var config = {
105
+ logLevel: "debug",
106
+ // ...other fields
107
+ };
108
+ config.logLevel;
109
+ ```
110
+
111
+ If a `.toml` file is passed as an entrypoint, it will be converted to a `.js` module that `export default`s the parsed object.
112
+
113
+ <CodeGroup>
114
+
115
+ ```toml Input
116
+ name = "John Doe"
117
+ age = 35
118
+ email = "johndoe@example.com"
119
+ ```
120
+
121
+ ```ts Output
122
+ export default {
123
+ name: "John Doe",
124
+ age: 35,
125
+ email: "johndoe@example.com",
126
+ };
127
+ ```
128
+
129
+ </CodeGroup>
130
+
131
+ ### `text`
132
+
133
+ **Text loader**. Default for `.txt`.
134
+
135
+ The contents of the text file are read and inlined into the bundle as a string.
136
+ Text files can be directly imported. The file is read and returned as a string.
137
+
138
+ ```ts
139
+ import contents from "./file.txt";
140
+ console.log(contents); // => "Hello, world!"
141
+
142
+ // To import an html file as text
143
+ // The "type' attribute can be used to override the default loader.
144
+ import html from "./index.html" with { type: "text" };
145
+ ```
146
+
147
+ When referenced during a build, the contents are inlined into the bundle as a string.
148
+
149
+ ```ts
150
+ var contents = `Hello, world!`;
151
+ console.log(contents);
152
+ ```
153
+
154
+ If a `.txt` file is passed as an entrypoint, it will be converted to a `.js` module that `export default`s the file contents.
155
+
156
+ <CodeGroup>
157
+
158
+ ```txt Input
159
+ Hello, world!
160
+ ```
161
+
162
+ ```ts Output
163
+ export default "Hello, world!";
164
+ ```
165
+
166
+ </CodeGroup>
167
+
168
+ ### `napi`
169
+
170
+ **Native addon loader**. Default for `.node`.
171
+
172
+ In the runtime, native addons can be directly imported.
173
+
174
+ ```ts
175
+ import addon from "./addon.node";
176
+ console.log(addon);
177
+ ```
178
+
179
+ In the bundler, `.node` files are handled using the [`file`](#file) loader.
180
+
181
+ ### `sqlite`
182
+
183
+ **SQLite loader**. `with { "type": "sqlite" }` import attribute
184
+
185
+ In the runtime and bundler, SQLite databases can be directly imported. This will load the database using [`bun:sqlite`](/runtime/sqlite).
186
+
187
+ ```ts
188
+ import db from "./my.db" with { type: "sqlite" };
189
+ ```
190
+
191
+ This is only supported when the `target` is `bun`.
192
+
193
+ By default, the database is external to the bundle (so that you can potentially use a database loaded elsewhere), so the database file on-disk won't be bundled into the final output.
194
+
195
+ You can change this behavior with the `"embed"` attribute:
196
+
197
+ ```ts
198
+ // embed the database into the bundle
199
+ import db from "./my.db" with { type: "sqlite", embed: "true" };
200
+ ```
201
+
202
+ When using a [standalone executable](/bundler/executables), the database is embedded into the single-file executable.
203
+
204
+ Otherwise, the database to embed is copied into the `outdir` with a hashed filename.
205
+
206
+ ### `html`
207
+
208
+ The html loader processes HTML files and bundles any referenced assets. It will:
209
+
210
+ - Bundle and hash referenced JavaScript files (`<script src="...">`)
211
+ - Bundle and hash referenced CSS files (`<link rel="stylesheet" href="...">`)
212
+ - Hash referenced images (`<img src="...">`)
213
+ - Preserve external URLs (by default, anything starting with `http://` or `https://`)
214
+
215
+ For example, given this HTML file:
216
+
217
+ <CodeGroup>
218
+
219
+ ```html src/index.html
220
+ <!DOCTYPE html>
221
+ <html>
222
+ <body>
223
+ <img src="./image.jpg" alt="Local image" />
224
+ <img src="https://example.com/image.jpg" alt="External image" />
225
+ <script type="module" src="./script.js"></script>
226
+ </body>
227
+ </html>
228
+ ```
229
+
230
+ </CodeGroup>
231
+
232
+ It will output a new HTML file with the bundled assets:
233
+
234
+ <CodeGroup>
235
+
236
+ ```html dist/output.html
237
+ <!DOCTYPE html>
238
+ <html>
239
+ <body>
240
+ <img src="./image-HASHED.jpg" alt="Local image" />
241
+ <img src="https://example.com/image.jpg" alt="External image" />
242
+ <script type="module" src="./output-ALSO-HASHED.js"></script>
243
+ </body>
244
+ </html>
245
+ ```
246
+
247
+ </CodeGroup>
248
+
249
+ Under the hood, it uses [`lol-html`](https://github.com/cloudflare/lol-html) to extract script and link tags as entrypoints, and other assets as external.
250
+
251
+ Currently, the list of selectors is:
252
+
253
+ - `audio[src]`
254
+ - `iframe[src]`
255
+ - `img[src]`
256
+ - `img[srcset]`
257
+ - `link:not([rel~='stylesheet']):not([rel~='modulepreload']):not([rel~='manifest']):not([rel~='icon']):not([rel~='apple-touch-icon'])[href]`
258
+ - `link[as='font'][href], link[type^='font/'][href]`
259
+ - `link[as='image'][href]`
260
+ - `link[as='style'][href]`
261
+ - `link[as='video'][href], link[as='audio'][href]`
262
+ - `link[as='worker'][href]`
263
+ - `link[rel='icon'][href], link[rel='apple-touch-icon'][href]`
264
+ - `link[rel='manifest'][href]`
265
+ - `link[rel='stylesheet'][href]`
266
+ - `script[src]`
267
+ - `source[src]`
268
+ - `source[srcset]`
269
+ - `video[poster]`
270
+ - `video[src]`
271
+
272
+ <Note>
273
+
274
+ **HTML Loader Behavior in Different Contexts**
275
+
276
+ The `html` loader behaves differently depending on how it's used:
277
+
278
+ 1. **Static Build:** When you run `bun build ./index.html`, Bun produces a static site with all assets bundled and hashed.
279
+
280
+ 2. **Runtime:** When you run `bun run server.ts` (where `server.ts` imports an HTML file), Bun bundles assets on-the-fly during development, enabling features like hot module replacement.
281
+
282
+ 3. **Full-stack Build:** When you run `bun build --target=bun server.ts` (where `server.ts` imports an HTML file), the import resolves to a manifest object that `Bun.serve` uses to efficiently serve pre-bundled assets in production.
283
+
284
+ </Note>
285
+
286
+ ### `sh` loader
287
+
288
+ **Bun Shell loader**. Default for `.sh` files
289
+
290
+ This loader is used to parse [Bun Shell](/runtime/shell) scripts. It's only supported when starting Bun itself, so it's not available in the bundler or in the runtime.
291
+
292
+ ```sh
293
+ bun run ./script.sh
294
+ ```
295
+
296
+ ### `file`
297
+
298
+ **File loader**. Default for all unrecognized file types.
299
+
300
+ The file loader resolves the import as a _path/URL_ to the imported file. It's commonly used for referencing media or font assets.
301
+
302
+ ```ts logo.ts
303
+ import logo from "./logo.svg";
304
+ console.log(logo);
305
+ ```
306
+
307
+ _In the runtime_, Bun checks that the `logo.svg` file exists and converts it to an absolute path to the location of `logo.svg` on disk.
308
+
309
+ ```bash
310
+ bun run logo.ts
311
+ /path/to/project/logo.svg
312
+ ```
313
+
314
+ _In the bundler_, things are slightly different. The file is copied into `outdir` as-is, and the import is resolved as a relative path pointing to the copied file.
315
+
316
+ ```ts Output
317
+ var logo = "./logo.svg";
318
+ console.log(logo);
319
+ ```
320
+
321
+ If a value is specified for `publicPath`, the import will use value as a prefix to construct an absolute path/URL.
322
+
323
+ | Public path | Resolved import |
324
+ | ---------------------------- | ---------------------------------- |
325
+ | `""` (default) | `/logo.svg` |
326
+ | `"/assets"` | `/assets/logo.svg` |
327
+ | `"https://cdn.example.com/"` | `https://cdn.example.com/logo.svg` |
328
+
329
+ <Note>
330
+ The location and file name of the copied file is determined by the value of [`naming.asset`](/bundler#naming).
331
+ </Note>
332
+ This loader is copied into the `outdir` as-is. The name of the copied file is determined using the value of
333
+ `naming.asset`.
334
+
335
+ <Accordion title="Fixing TypeScript import errors">
336
+ If you're using TypeScript, you may get an error like this:
337
+
338
+ ```ts
339
+ // TypeScript error
340
+ // Cannot find module './logo.svg' or its corresponding type declarations.
341
+ ```
342
+
343
+ This can be fixed by creating `*.d.ts` file anywhere in your project (any name will work) with the following contents:
344
+
345
+ ```ts
346
+ declare module "*.svg" {
347
+ const content: string;
348
+ export default content;
349
+ }
350
+ ```
351
+
352
+ This tells TypeScript that any default imports from `.svg` should be treated as a string.
353
+
354
+ </Accordion>
@@ -0,0 +1,181 @@
1
+ ---
2
+ title: Glob
3
+ description: Use Bun's fast native implementation of file globbing
4
+ ---
5
+
6
+ ## Quickstart
7
+
8
+ **Scan a directory for files matching `*.ts`**:
9
+
10
+ ```ts
11
+ import { Glob } from "bun";
12
+
13
+ const glob = new Glob("**/*.ts");
14
+
15
+ // Scans the current working directory and each of its sub-directories recursively
16
+ for await (const file of glob.scan(".")) {
17
+ console.log(file); // => "index.ts"
18
+ }
19
+ ```
20
+
21
+ **Match a string against a glob pattern**:
22
+
23
+ ```ts
24
+ import { Glob } from "bun";
25
+
26
+ const glob = new Glob("*.ts");
27
+
28
+ glob.match("index.ts"); // => true
29
+ glob.match("index.js"); // => false
30
+ ```
31
+
32
+ `Glob` is a class which implements the following interface:
33
+
34
+ ```ts
35
+ class Glob {
36
+ scan(root: string | ScanOptions): AsyncIterable<string>;
37
+ scanSync(root: string | ScanOptions): Iterable<string>;
38
+
39
+ match(path: string): boolean;
40
+ }
41
+
42
+ interface ScanOptions {
43
+ /**
44
+ * The root directory to start matching from. Defaults to `process.cwd()`
45
+ */
46
+ cwd?: string;
47
+
48
+ /**
49
+ * Allow patterns to match entries that begin with a period (`.`).
50
+ *
51
+ * @default false
52
+ */
53
+ dot?: boolean;
54
+
55
+ /**
56
+ * Return the absolute path for entries.
57
+ *
58
+ * @default false
59
+ */
60
+ absolute?: boolean;
61
+
62
+ /**
63
+ * Indicates whether to traverse descendants of symbolic link directories.
64
+ *
65
+ * @default false
66
+ */
67
+ followSymlinks?: boolean;
68
+
69
+ /**
70
+ * Throw an error when symbolic link is broken
71
+ *
72
+ * @default false
73
+ */
74
+ throwErrorOnBrokenSymlink?: boolean;
75
+
76
+ /**
77
+ * Return only files.
78
+ *
79
+ * @default true
80
+ */
81
+ onlyFiles?: boolean;
82
+ }
83
+ ```
84
+
85
+ ## Supported Glob Patterns
86
+
87
+ Bun supports the following glob patterns:
88
+
89
+ ### `?` - Match any single character
90
+
91
+ ```ts
92
+ const glob = new Glob("???.ts");
93
+ glob.match("foo.ts"); // => true
94
+ glob.match("foobar.ts"); // => false
95
+ ```
96
+
97
+ ### `*` - Matches zero or more characters, except for path separators (`/` or `\`)
98
+
99
+ ```ts
100
+ const glob = new Glob("*.ts");
101
+ glob.match("index.ts"); // => true
102
+ glob.match("src/index.ts"); // => false
103
+ ```
104
+
105
+ ### `**` - Match any number of characters including `/`
106
+
107
+ ```ts
108
+ const glob = new Glob("**/*.ts");
109
+ glob.match("index.ts"); // => true
110
+ glob.match("src/index.ts"); // => true
111
+ glob.match("src/index.js"); // => false
112
+ ```
113
+
114
+ ### `[ab]` - Matches one of the characters contained in the brackets, as well as character ranges
115
+
116
+ ```ts
117
+ const glob = new Glob("ba[rz].ts");
118
+ glob.match("bar.ts"); // => true
119
+ glob.match("baz.ts"); // => true
120
+ glob.match("bat.ts"); // => false
121
+ ```
122
+
123
+ You can use character ranges (e.g `[0-9]`, `[a-z]`) as well as the negation operators `^` or `!` to match anything _except_ the characters contained within the braces (e.g `[^ab]`, `[!a-z]`)
124
+
125
+ ```ts
126
+ const glob = new Glob("ba[a-z][0-9][^4-9].ts");
127
+ glob.match("bar01.ts"); // => true
128
+ glob.match("baz83.ts"); // => true
129
+ glob.match("bat22.ts"); // => true
130
+ glob.match("bat24.ts"); // => false
131
+ glob.match("ba0a8.ts"); // => false
132
+ ```
133
+
134
+ ### `{a,b,c}` - Match any of the given patterns
135
+
136
+ ```ts
137
+ const glob = new Glob("{a,b,c}.ts");
138
+ glob.match("a.ts"); // => true
139
+ glob.match("b.ts"); // => true
140
+ glob.match("c.ts"); // => true
141
+ glob.match("d.ts"); // => false
142
+ ```
143
+
144
+ These match patterns can be deeply nested (up to 10 levels), and contain any of the wildcards from above.
145
+
146
+ ### `!` - Negates the result at the start of a pattern
147
+
148
+ ```ts
149
+ const glob = new Glob("!index.ts");
150
+ glob.match("index.ts"); // => false
151
+ glob.match("foo.ts"); // => true
152
+ ```
153
+
154
+ ### `\` - Escapes any of the special characters above
155
+
156
+ ```ts
157
+ const glob = new Glob("\\!index.ts");
158
+ glob.match("!index.ts"); // => true
159
+ glob.match("index.ts"); // => false
160
+ ```
161
+
162
+ ## Node.js `fs.glob()` compatibility
163
+
164
+ Bun also implements Node.js's `fs.glob()` functions with additional features:
165
+
166
+ ```ts
167
+ import { glob, globSync, promises } from "node:fs";
168
+
169
+ // Array of patterns
170
+ const files = await promises.glob(["**/*.ts", "**/*.js"]);
171
+
172
+ // Exclude patterns
173
+ const filtered = await promises.glob("**/*", {
174
+ exclude: ["node_modules/**", "*.test.*"],
175
+ });
176
+ ```
177
+
178
+ All three functions (`fs.glob()`, `fs.globSync()`, `fs.promises.glob()`) support:
179
+
180
+ - Array of patterns as the first argument
181
+ - `exclude` option to filter results
@@ -0,0 +1,72 @@
1
+ ---
2
+ title: Globals
3
+ description: Use Bun's global objects
4
+ ---
5
+
6
+ Bun implements the following globals.
7
+
8
+ | Global | Source | Notes |
9
+ | ----------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10
+ | [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) | Web | |
11
+ | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | Web | |
12
+ | [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert) | Web | Intended for command-line tools |
13
+ | [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) | Web | |
14
+ | [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) | Node.js | See [Node.js > `Buffer`](/runtime/nodejs-compat#node-buffer) |
15
+ | `Bun` | Bun | Subject to change as additional APIs are added |
16
+ | [`ByteLengthQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/ByteLengthQueuingStrategy) | Web | |
17
+ | [`confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm) | Web | Intended for command-line tools |
18
+ | [`__dirname`](https://nodejs.org/api/globals.html#__dirname) | Node.js | |
19
+ | [`__filename`](https://nodejs.org/api/globals.html#__filename) | Node.js | |
20
+ | [`atob()`](https://developer.mozilla.org/en-US/docs/Web/API/atob) | Web | |
21
+ | [`btoa()`](https://developer.mozilla.org/en-US/docs/Web/API/btoa) | Web | |
22
+ | `BuildMessage` | Bun | |
23
+ | [`clearImmediate()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/clearImmediate) | Web | |
24
+ | [`clearInterval()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/clearInterval) | Web | |
25
+ | [`clearTimeout()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/clearTimeout) | Web | |
26
+ | [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) | Web | |
27
+ | [`CountQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) | Web | |
28
+ | [`Crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) | Web | |
29
+ | [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/crypto) | Web | |
30
+ | [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) | Web | |
31
+ | [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) | Web | |
32
+ | [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) | Web | Also [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent) [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent) [`MessageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent). |
33
+ | [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | Web | |
34
+ | [`exports`](https://nodejs.org/api/globals.html#exports) | Node.js | |
35
+ | [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) | Web | |
36
+ | [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) | Web | |
37
+ | [`global`](https://nodejs.org/api/globals.html#global) | Node.js | See [Node.js > `global`](/runtime/nodejs-compat#global). |
38
+ | [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) | Cross-platform | Aliases to `global` |
39
+ | [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) | Web | |
40
+ | [`HTMLRewriter`](/runtime/html-rewriter) | Cloudflare | |
41
+ | [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) | Web | |
42
+ | [`MessageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent) | Web | |
43
+ | [`module`](https://nodejs.org/api/globals.html#module) | Node.js | |
44
+ | [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/performance) | Web | |
45
+ | [`process`](https://nodejs.org/api/process.html) | Node.js | See [Node.js > `process`](/runtime/nodejs-compat#node-process) |
46
+ | [`prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) | Web | Intended for command-line tools |
47
+ | [`queueMicrotask()`](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask) | Web | |
48
+ | [`ReadableByteStreamController`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableByteStreamController) | Web | |
49
+ | [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) | Web | |
50
+ | [`ReadableStreamDefaultController`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultController) | Web | |
51
+ | [`ReadableStreamDefaultReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader) | Web | |
52
+ | [`reportError`](https://developer.mozilla.org/en-US/docs/Web/API/reportError) | Web | |
53
+ | [`require()`](https://nodejs.org/api/globals.html#require) | Node.js | |
54
+ | `ResolveMessage` | Bun | |
55
+ | [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) | Web | |
56
+ | [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) | Web | |
57
+ | [`setImmediate()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate) | Web | |
58
+ | [`setInterval()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/setInterval) | Web | |
59
+ | [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout) | Web | |
60
+ | [`ShadowRealm`](https://github.com/tc39/proposal-shadowrealm) | Web | Stage 3 proposal |
61
+ | [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) | Web | |
62
+ | [`DOMException`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException) | Web | |
63
+ | [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) | Web | |
64
+ | [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) | Web | |
65
+ | [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) | Web | |
66
+ | [`TransformStreamDefaultController`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStreamDefaultController) | Web | |
67
+ | [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) | Web | |
68
+ | [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) | Web | |
69
+ | [`WebAssembly`](https://nodejs.org/api/globals.html#webassembly) | Web | |
70
+ | [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) | Web | |
71
+ | [`WritableStreamDefaultController`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultController) | Web | |
72
+ | [`WritableStreamDefaultWriter`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter) | Web | |