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
package/docs/bundler/fullstack.mdx ADDED
@@ -0,0 +1,1064 @@
1
+ ---
2
+ title: "Fullstack dev server"
3
+ description: "Build fullstack applications with Bun's integrated dev server that bundles frontend assets and handles API routes"
4
+ ---
5
+
6
+ To get started, import HTML files and pass them to the `routes` option in `Bun.serve()`.
7
+
8
+ ```ts title="app.ts" icon="/icons/typescript.svg"
9
+ import { serve } from "bun";
10
+ import dashboard from "./dashboard.html";
11
+ import homepage from "./index.html";
12
+
13
+ const server = serve({
14
+ routes: {
15
+ // ** HTML imports **
16
+ // Bundle & route index.html to "/". This uses HTMLRewriter to scan
17
+ // the HTML for `<script>` and `<link>` tags, runs Bun's JavaScript
18
+ // & CSS bundler on them, transpiles any TypeScript, JSX, and TSX,
19
+ // downlevels CSS with Bun's CSS parser and serves the result.
20
+ "/": homepage,
21
+ // Bundle & route dashboard.html to "/dashboard"
22
+ "/dashboard": dashboard,
23
+
24
+ // ** API endpoints ** (Bun v1.2.3+ required)
25
+ "/api/users": {
26
+ async GET(req) {
27
+ const users = await sql`SELECT * FROM users`;
28
+ return Response.json(users);
29
+ },
30
+ async POST(req) {
31
+ const { name, email } = await req.json();
32
+ const [user] = await sql`INSERT INTO users (name, email) VALUES (${name}, ${email})`;
33
+ return Response.json(user);
34
+ },
35
+ },
36
+ "/api/users/:id": async req => {
37
+ const { id } = req.params;
38
+ const [user] = await sql`SELECT * FROM users WHERE id = ${id}`;
39
+ return Response.json(user);
40
+ },
41
+ },
42
+
43
+ // Enable development mode for:
44
+ // - Detailed error messages
45
+ // - Hot reloading (Bun v1.2.3+ required)
46
+ development: true,
47
+ });
48
+
49
+ console.log(`Listening on ${server.url}`);
50
+ ```
51
+
52
+ ```bash terminal icon="terminal"
53
+ bun run app.ts
54
+ ```
55
+
56
+ ## HTML Routes
57
+
58
+ ### HTML Imports as Routes
59
+
60
+ The web starts with HTML, and so does Bun's fullstack dev server.
61
+
62
+ To specify entrypoints to your frontend, import HTML files into your JavaScript/TypeScript/TSX/JSX files.
63
+
64
+ ```ts title="app.ts" icon="/icons/typescript.svg"
65
+ import dashboard from "./dashboard.html";
66
+ import homepage from "./index.html";
67
+ ```
68
+
69
+ These HTML files are used as routes in Bun's dev server you can pass to `Bun.serve()`.
70
+
71
+ ```ts title="app.ts" icon="/icons/typescript.svg"
72
+ Bun.serve({
73
+ routes: {
74
+ "/": homepage,
75
+ "/dashboard": dashboard,
76
+ },
77
+
78
+ fetch(req) {
79
+ // ... api requests
80
+ },
81
+ });
82
+ ```
83
+
84
+ When you make a request to `/dashboard` or `/`, Bun automatically bundles the `<script>` and `<link>` tags in the HTML files, exposes them as static routes, and serves the result.
85
+
86
+ ### HTML Processing Example
87
+
88
+ An `index.html` file like this:
89
+
90
+ ```html title="index.html" icon="file-code"
91
+ <!DOCTYPE html>
92
+ <html>
93
+ <head>
94
+ <title>Home</title>
95
+ <link rel="stylesheet" href="./reset.css" />
96
+ <link rel="stylesheet" href="./styles.css" />
97
+ </head>
98
+ <body>
99
+ <div id="root"></div>
100
+ <script type="module" src="./sentry-and-preloads.ts"></script>
101
+ <script type="module" src="./my-app.tsx"></script>
102
+ </body>
103
+ </html>
104
+ ```
105
+
106
+ Becomes something like this:
107
+
108
+ ```html title="index.html" icon="file-code"
109
+ <!DOCTYPE html>
110
+ <html>
111
+ <head>
112
+ <title>Home</title>
113
+ <link rel="stylesheet" href="/index-[hash].css" />
114
+ </head>
115
+ <body>
116
+ <div id="root"></div>
117
+ <script type="module" src="/index-[hash].js"></script>
118
+ </body>
119
+ </html>
120
+ ```
121
+
122
+ ## React Integration
123
+
124
+ To use React in your client-side code, import `react-dom/client` and render your app.
125
+
126
+ <CodeGroup>
127
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
128
+ import dashboard from "../public/dashboard.html";
129
+ import { serve } from "bun";
130
+
131
+ serve({
132
+ routes: {
133
+ "/": dashboard,
134
+ },
135
+ async fetch(req) {
136
+ // ...api requests
137
+ return new Response("hello world");
138
+ },
139
+ });
140
+
141
+ ````
142
+
143
+ ```tsx title="src/frontend.tsx" icon="/icons/typescript.svg"
144
+ import { createRoot } from 'react-dom/client';
145
+ import App from './app';
146
+
147
+ const container = document.getElementById('root');
148
+ const root = createRoot(container!);
149
+ root.render(<App />);
150
+ ````
151
+
152
+ ```html title="public/dashboard.html" icon="file-code"
153
+ <!DOCTYPE html>
154
+ <html>
155
+ <head>
156
+ <title>Dashboard</title>
157
+ <link rel="stylesheet" href="../src/styles.css" />
158
+ </head>
159
+ <body>
160
+ <div id="root"></div>
161
+ <script type="module" src="../src/frontend.tsx"></script>
162
+ </body>
163
+ </html>
164
+ ```
165
+
166
+ ```tsx title="src/app.tsx" icon="/icons/typescript.svg"
167
+ import { useState } from "react";
168
+
169
+ export default function App() {
170
+ const [count, setCount] = useState(0);
171
+
172
+ return (
173
+ <div>
174
+ <h1>Dashboard</h1>
175
+ <button onClick={() => setCount(count + 1)}>Count: {count}</button>
176
+ </div>
177
+ );
178
+ }
179
+ ```
180
+
181
+ </CodeGroup>
182
+
183
+ ## Development Mode
184
+
185
+ When building locally, enable development mode by setting `development: true` in `Bun.serve()`.
186
+
187
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
188
+ import homepage from "./index.html";
189
+ import dashboard from "./dashboard.html";
190
+
191
+ Bun.serve({
192
+ routes: {
193
+ "/": homepage,
194
+ "/dashboard": dashboard,
195
+ },
196
+
197
+ development: true,
198
+
199
+ fetch(req) {
200
+ // ... api requests
201
+ },
202
+ });
203
+ ```
204
+
205
+ ### Development Mode Features
206
+
207
+ When `development` is `true`, Bun will:
208
+
209
+ - Include the SourceMap header in the response so that devtools can show the original source code
210
+ - Disable minification
211
+ - Re-bundle assets on each request to a `.html` file
212
+ - Enable hot module reloading (unless `hmr: false` is set)
213
+ - Echo console logs from browser to terminal
214
+
215
+ ### Advanced Development Configuration
216
+
217
+ `Bun.serve()` supports echoing console logs from the browser to the terminal.
218
+
219
+ To enable this, pass `console: true` in the development object in `Bun.serve()`.
220
+
221
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
222
+ import homepage from "./index.html";
223
+
224
+ Bun.serve({
225
+ // development can also be an object.
226
+ development: {
227
+ // Enable Hot Module Reloading
228
+ hmr: true,
229
+
230
+ // Echo console logs from the browser to the terminal
231
+ console: true,
232
+ },
233
+
234
+ routes: {
235
+ "/": homepage,
236
+ },
237
+ });
238
+ ```
239
+
240
+ When `console: true` is set, Bun will stream console logs from the browser to the terminal. This reuses the existing WebSocket connection from HMR to send the logs.
241
+
242
+ ### Development vs Production
243
+
244
+ | Feature | Development | Production |
245
+ | ------------------- | --------------------- | ----------- |
246
+ | **Source maps** | ✅ Enabled | ❌ Disabled |
247
+ | **Minification** | ❌ Disabled | ✅ Enabled |
248
+ | **Hot reloading** | ✅ Enabled | ❌ Disabled |
249
+ | **Asset bundling** | 🔄 On each request | 💾 Cached |
250
+ | **Console logging** | 🖥️ Browser → Terminal | ❌ Disabled |
251
+ | **Error details** | 📝 Detailed | 🔒 Minimal |
252
+
253
+ ## Production Mode
254
+
255
+ Hot reloading and `development: true` helps you iterate quickly, but in production, your server should be as fast as possible and have as few external dependencies as possible.
256
+
257
+ ### Ahead of Time Bundling (Recommended)
258
+
259
+ As of Bun v1.2.17, you can use `Bun.build` or `bun build` to bundle your full-stack application ahead of time.
260
+
261
+ ```bash terminal icon="terminal"
262
+ bun build --target=bun --production --outdir=dist ./src/index.ts
263
+ ```
264
+
265
+ When Bun's bundler sees an HTML import from server-side code, it will bundle the referenced JavaScript/TypeScript/TSX/JSX and CSS files into a manifest object that `Bun.serve()` can use to serve the assets.
266
+
267
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
268
+ import { serve } from "bun";
269
+ import index from "./index.html";
270
+
271
+ serve({
272
+ routes: { "/": index },
273
+ });
274
+ ```
275
+
276
+ ### Runtime Bundling
277
+
278
+ When adding a build step is too complicated, you can set `development: false` in `Bun.serve()`.
279
+
280
+ This will:
281
+
282
+ - Enable in-memory caching of bundled assets. Bun will bundle assets lazily on the first request to an `.html` file, and cache the result in memory until the server restarts.
283
+ - Enable `Cache-Control` headers and `ETag` headers
284
+ - Minify JavaScript/TypeScript/TSX/JSX files
285
+
286
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
287
+ import { serve } from "bun";
288
+ import homepage from "./index.html";
289
+
290
+ serve({
291
+ routes: {
292
+ "/": homepage,
293
+ },
294
+
295
+ // Production mode
296
+ development: false,
297
+ });
298
+ ```
299
+
300
+ ## API Routes
301
+
302
+ ### HTTP Method Handlers
303
+
304
+ Define API endpoints with HTTP method handlers:
305
+
306
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
307
+ import { serve } from "bun";
308
+
309
+ serve({
310
+ routes: {
311
+ "/api/users": {
312
+ async GET(req) {
313
+ // Handle GET requests
314
+ const users = await getUsers();
315
+ return Response.json(users);
316
+ },
317
+
318
+ async POST(req) {
319
+ // Handle POST requests
320
+ const userData = await req.json();
321
+ const user = await createUser(userData);
322
+ return Response.json(user, { status: 201 });
323
+ },
324
+
325
+ async PUT(req) {
326
+ // Handle PUT requests
327
+ const userData = await req.json();
328
+ const user = await updateUser(userData);
329
+ return Response.json(user);
330
+ },
331
+
332
+ async DELETE(req) {
333
+ // Handle DELETE requests
334
+ await deleteUser(req.params.id);
335
+ return new Response(null, { status: 204 });
336
+ },
337
+ },
338
+ },
339
+ });
340
+ ```
341
+
342
+ ### Dynamic Routes
343
+
344
+ Use URL parameters in your routes:
345
+
346
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
347
+ serve({
348
+ routes: {
349
+ // Single parameter
350
+ "/api/users/:id": async req => {
351
+ const { id } = req.params;
352
+ const user = await getUserById(id);
353
+ return Response.json(user);
354
+ },
355
+
356
+ // Multiple parameters
357
+ "/api/users/:userId/posts/:postId": async req => {
358
+ const { userId, postId } = req.params;
359
+ const post = await getPostByUser(userId, postId);
360
+ return Response.json(post);
361
+ },
362
+
363
+ // Wildcard routes
364
+ "/api/files/*": async req => {
365
+ const filePath = req.params["*"];
366
+ const file = await getFile(filePath);
367
+ return new Response(file);
368
+ },
369
+ },
370
+ });
371
+ ```
372
+
373
+ ### Request Handling
374
+
375
+ ```ts title="src/backend.ts" icon="/icons/typescript.svg"
376
+ serve({
377
+ routes: {
378
+ "/api/data": {
379
+ async POST(req) {
380
+ // Parse JSON body
381
+ const body = await req.json();
382
+
383
+ // Access headers
384
+ const auth = req.headers.get("Authorization");
385
+
386
+ // Access URL parameters
387
+ const { id } = req.params;
388
+
389
+ // Access query parameters
390
+ const url = new URL(req.url);
391
+ const page = url.searchParams.get("page") || "1";
392
+
393
+ // Return response
394
+ return Response.json({
395
+ message: "Data processed",
396
+ page: parseInt(page),
397
+ authenticated: !!auth,
398
+ });
399
+ },
400
+ },
401
+ },
402
+ });
403
+ ```
404
+
405
+ ## Plugins
406
+
407
+ Bun's bundler plugins are also supported when bundling static routes.
408
+
409
+ To configure plugins for `Bun.serve`, add a `plugins` array in the `[serve.static]` section of your `bunfig.toml`.
410
+
411
+ ### TailwindCSS Plugin
412
+
413
+ You can use TailwindCSS by installing and adding the `tailwindcss` package and `bun-plugin-tailwind` plugin.
414
+
415
+ ```bash terminal icon="terminal"
416
+ bun add tailwindcss bun-plugin-tailwind
417
+ ```
418
+
419
+ ```toml title="bunfig.toml" icon="settings"
420
+ [serve.static]
421
+ plugins = ["bun-plugin-tailwind"]
422
+ ```
423
+
424
+ This will allow you to use TailwindCSS utility classes in your HTML and CSS files. All you need to do is import `tailwindcss` somewhere:
425
+
426
+ ```html title="index.html" icon="file-code"
427
+ <!doctype html>
428
+ <html>
429
+ <head>
430
+ <link rel="stylesheet" href="tailwindcss" />
431
+ <!-- [!code ++] -->
432
+ </head>
433
+ <!-- the rest of your HTML... -->
434
+ </html>
435
+ ```
436
+
437
+ Alternatively, you can import TailwindCSS in your CSS file:
438
+
439
+ ```css title="style.css" icon="file-code"
440
+ @import "tailwindcss";
441
+
442
+ .custom-class {
443
+ @apply bg-red-500 text-white;
444
+ }
445
+ ```
446
+
447
+ ```html index.html icon="file-code"
448
+ <!doctype html>
449
+ <html>
450
+ <head>
451
+ <link rel="stylesheet" href="./style.css" />
452
+ <!-- [!code ++] -->
453
+ </head>
454
+ <!-- the rest of your HTML... -->
455
+ </html>
456
+ ```
457
+
458
+ ### Custom Plugins
459
+
460
+ Any JS file or module which exports a valid bundler plugin object (essentially an object with a `name` and `setup` field) can be placed inside the plugins array:
461
+
462
+ ```toml title="bunfig.toml" icon="settings"
463
+ [serve.static]
464
+ plugins = ["./my-plugin-implementation.ts"]
465
+ ```
466
+
467
+ ```ts title="my-plugin-implementation.ts" icon="/icons/typescript.svg"
468
+ import type { BunPlugin } from "bun";
469
+
470
+ const myPlugin: BunPlugin = {
471
+ name: "my-custom-plugin",
472
+ setup(build) {
473
+ // Plugin implementation
474
+ build.onLoad({ filter: /\.custom$/ }, async args => {
475
+ const text = await Bun.file(args.path).text();
476
+ return {
477
+ contents: `export default ${JSON.stringify(text)};`,
478
+ loader: "js",
479
+ };
480
+ });
481
+ },
482
+ };
483
+
484
+ export default myPlugin;
485
+ ```
486
+
487
+ Bun will lazily resolve and load each plugin and use them to bundle your routes.
488
+
489
+ <Note>
490
+ This is currently in `bunfig.toml` to make it possible to know statically which plugins are in use when we eventually
491
+ integrate this with the `bun build` CLI. These plugins work in `Bun.build()`'s JS API, but are not yet supported in
492
+ the CLI.
493
+ </Note>
494
+
495
+ ## How It Works
496
+
497
+ Bun uses `HTMLRewriter` to scan for `<script>` and `<link>` tags in HTML files, uses them as entrypoints for Bun's bundler, generates an optimized bundle for the JavaScript/TypeScript/TSX/JSX and CSS files, and serves the result.
498
+
499
+ ### Processing Pipeline
500
+
501
+ <Steps>
502
+ <Step title="1. <script> Processing">
503
+ - Transpiles TypeScript, JSX, and TSX in `<script>` tags
504
+ - Bundles imported dependencies
505
+ - Generates sourcemaps for debugging
506
+ - Minifies when `development` is not `true` in `Bun.serve()`
507
+
508
+ ```html title="index.html" icon="file-code"
509
+ <script type="module" src="./counter.tsx"></script>
510
+ ```
511
+
512
+ </Step>
513
+ <Step title="2. <link> Processing">
514
+ - Processes CSS imports and `<link>` tags
515
+ - Concatenates CSS files
516
+ - Rewrites url and asset paths to include content-addressable hashes in URLs
517
+
518
+ ```html title="index.html" icon="file-code"
519
+ <link rel="stylesheet" href="./styles.css" />
520
+ ```
521
+
522
+ </Step>
523
+ <Step title="3. <img> & Asset Processing">
524
+ - Links to assets are rewritten to include content-addressable hashes in URLs
525
+ - Small assets in CSS files are inlined into `data:` URLs, reducing the total number of HTTP requests sent over the wire
526
+ </Step>
527
+ <Step title="4. HTML Rewriting">
528
+ - Combines all `<script>` tags into a single `<script>` tag with a content-addressable hash in the URL
529
+ - Combines all `<link>` tags into a single `<link>` tag with a content-addressable hash in the URL
530
+ - Outputs a new HTML file
531
+ </Step>
532
+ <Step title="5. Serving">
533
+ - All the output files from the bundler are exposed as static routes, using the same mechanism internally as when you pass a Response object to `static` in `Bun.serve()`.
534
+ - This works similarly to how `Bun.build` processes HTML files.
535
+ </Step>
536
+ </Steps>
537
+
538
+ ## Complete Example
539
+
540
+ Here's a complete fullstack application example:
541
+
542
+ ```ts title="server.ts" icon="/icons/typescript.svg"
543
+ import { serve } from "bun";
544
+ import { Database } from "bun:sqlite";
545
+ import homepage from "./public/index.html";
546
+ import dashboard from "./public/dashboard.html";
547
+
548
+ // Initialize database
549
+ const db = new Database("app.db");
550
+ db.exec(`
551
+ CREATE TABLE IF NOT EXISTS users (
552
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
553
+ name TEXT NOT NULL,
554
+ email TEXT UNIQUE NOT NULL,
555
+ created_at DATETIME DEFAULT CURRENT_TIMESTAMP
556
+ )
557
+ `);
558
+
559
+ const server = serve({
560
+ routes: {
561
+ // Frontend routes
562
+ "/": homepage,
563
+ "/dashboard": dashboard,
564
+
565
+ // API routes
566
+ "/api/users": {
567
+ async GET() {
568
+ const users = db.query("SELECT * FROM users").all();
569
+ return Response.json(users);
570
+ },
571
+
572
+ async POST(req) {
573
+ const { name, email } = await req.json();
574
+
575
+ try {
576
+ const result = db.query("INSERT INTO users (name, email) VALUES (?, ?) RETURNING *").get(name, email);
577
+
578
+ return Response.json(result, { status: 201 });
579
+ } catch (error) {
580
+ return Response.json({ error: "Email already exists" }, { status: 400 });
581
+ }
582
+ },
583
+ },
584
+
585
+ "/api/users/:id": {
586
+ async GET(req) {
587
+ const { id } = req.params;
588
+ const user = db.query("SELECT * FROM users WHERE id = ?").get(id);
589
+
590
+ if (!user) {
591
+ return Response.json({ error: "User not found" }, { status: 404 });
592
+ }
593
+
594
+ return Response.json(user);
595
+ },
596
+
597
+ async DELETE(req) {
598
+ const { id } = req.params;
599
+ const result = db.query("DELETE FROM users WHERE id = ?").run(id);
600
+
601
+ if (result.changes === 0) {
602
+ return Response.json({ error: "User not found" }, { status: 404 });
603
+ }
604
+
605
+ return new Response(null, { status: 204 });
606
+ },
607
+ },
608
+
609
+ // Health check endpoint
610
+ "/api/health": {
611
+ GET() {
612
+ return Response.json({
613
+ status: "ok",
614
+ timestamp: new Date().toISOString(),
615
+ });
616
+ },
617
+ },
618
+ },
619
+
620
+ // Enable development mode
621
+ development: {
622
+ hmr: true,
623
+ console: true,
624
+ },
625
+
626
+ // Fallback for unmatched routes
627
+ fetch(req) {
628
+ return new Response("Not Found", { status: 404 });
629
+ },
630
+ });
631
+
632
+ console.log(`🚀 Server running on ${server.url}`);
633
+ ```
634
+
635
+ ```html title="public/index.html"
636
+ <!DOCTYPE html>
637
+ <html>
638
+ <head>
639
+ <meta charset="utf-8" />
640
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
641
+ <title>Fullstack Bun App</title>
642
+ <link rel="stylesheet" href="../src/styles.css" />
643
+ </head>
644
+ <body>
645
+ <div id="root"></div>
646
+ <script type="module" src="../src/main.tsx"></script>
647
+ </body>
648
+ </html>
649
+ ```
650
+
651
+ ```tsx title="src/main.tsx"
652
+ import { createRoot } from "react-dom/client";
653
+ import { App } from "./App";
654
+
655
+ const container = document.getElementById("root")!;
656
+ const root = createRoot(container);
657
+ root.render(<App />);
658
+ ```
659
+
660
+ ```tsx title="src/App.tsx"
661
+ import { useState, useEffect } from "react";
662
+
663
+ interface User {
664
+ id: number;
665
+ name: string;
666
+ email: string;
667
+ created_at: string;
668
+ }
669
+
670
+ export function App() {
671
+ const [users, setUsers] = useState<User[]>([]);
672
+ const [name, setName] = useState("");
673
+ const [email, setEmail] = useState("");
674
+ const [loading, setLoading] = useState(false);
675
+
676
+ const fetchUsers = async () => {
677
+ const response = await fetch("/api/users");
678
+ const data = await response.json();
679
+ setUsers(data);
680
+ };
681
+
682
+ const createUser = async (e: React.FormEvent) => {
683
+ e.preventDefault();
684
+ setLoading(true);
685
+
686
+ try {
687
+ const response = await fetch("/api/users", {
688
+ method: "POST",
689
+ headers: { "Content-Type": "application/json" },
690
+ body: JSON.stringify({ name, email }),
691
+ });
692
+
693
+ if (response.ok) {
694
+ setName("");
695
+ setEmail("");
696
+ await fetchUsers();
697
+ } else {
698
+ const error = await response.json();
699
+ alert(error.error);
700
+ }
701
+ } catch (error) {
702
+ alert("Failed to create user");
703
+ } finally {
704
+ setLoading(false);
705
+ }
706
+ };
707
+
708
+ const deleteUser = async (id: number) => {
709
+ if (!confirm("Are you sure?")) return;
710
+
711
+ try {
712
+ const response = await fetch(`/api/users/${id}`, {
713
+ method: "DELETE",
714
+ });
715
+
716
+ if (response.ok) {
717
+ await fetchUsers();
718
+ }
719
+ } catch (error) {
720
+ alert("Failed to delete user");
721
+ }
722
+ };
723
+
724
+ useEffect(() => {
725
+ fetchUsers();
726
+ }, []);
727
+
728
+ return (
729
+ <div className="container">
730
+ <h1>User Management</h1>
731
+
732
+ <form onSubmit={createUser} className="form">
733
+ <input type="text" placeholder="Name" value={name} onChange={e => setName(e.target.value)} required />
734
+ <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required />
735
+ <button type="submit" disabled={loading}>
736
+ {loading ? "Creating..." : "Create User"}
737
+ </button>
738
+ </form>
739
+
740
+ <div className="users">
741
+ <h2>Users ({users.length})</h2>
742
+ {users.map(user => (
743
+ <div key={user.id} className="user-card">
744
+ <div>
745
+ <strong>{user.name}</strong>
746
+ <br />
747
+ <span>{user.email}</span>
748
+ </div>
749
+ <button onClick={() => deleteUser(user.id)} className="delete-btn">
750
+ Delete
751
+ </button>
752
+ </div>
753
+ ))}
754
+ </div>
755
+ </div>
756
+ );
757
+ }
758
+ ```
759
+
760
+ ```css title="src/styles.css"
761
+ * {
762
+ margin: 0;
763
+ padding: 0;
764
+ box-sizing: border-box;
765
+ }
766
+
767
+ body {
768
+ font-family: -apple-system, BlinkMacSystemFont, sans-serif;
769
+ background: #f5f5f5;
770
+ color: #333;
771
+ }
772
+
773
+ .container {
774
+ max-width: 800px;
775
+ margin: 0 auto;
776
+ padding: 2rem;
777
+ }
778
+
779
+ h1 {
780
+ color: #2563eb;
781
+ margin-bottom: 2rem;
782
+ }
783
+
784
+ .form {
785
+ background: white;
786
+ padding: 1.5rem;
787
+ border-radius: 8px;
788
+ box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
789
+ margin-bottom: 2rem;
790
+ display: flex;
791
+ gap: 1rem;
792
+ flex-wrap: wrap;
793
+ }
794
+
795
+ .form input {
796
+ flex: 1;
797
+ min-width: 200px;
798
+ padding: 0.75rem;
799
+ border: 1px solid #ddd;
800
+ border-radius: 4px;
801
+ }
802
+
803
+ .form button {
804
+ padding: 0.75rem 1.5rem;
805
+ background: #2563eb;
806
+ color: white;
807
+ border: none;
808
+ border-radius: 4px;
809
+ cursor: pointer;
810
+ }
811
+
812
+ .form button:hover {
813
+ background: #1d4ed8;
814
+ }
815
+
816
+ .form button:disabled {
817
+ opacity: 0.5;
818
+ cursor: not-allowed;
819
+ }
820
+
821
+ .users {
822
+ background: white;
823
+ padding: 1.5rem;
824
+ border-radius: 8px;
825
+ box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
826
+ }
827
+
828
+ .user-card {
829
+ display: flex;
830
+ justify-content: space-between;
831
+ align-items: center;
832
+ padding: 1rem;
833
+ border-bottom: 1px solid #eee;
834
+ }
835
+
836
+ .user-card:last-child {
837
+ border-bottom: none;
838
+ }
839
+
840
+ .delete-btn {
841
+ padding: 0.5rem 1rem;
842
+ background: #dc2626;
843
+ color: white;
844
+ border: none;
845
+ border-radius: 4px;
846
+ cursor: pointer;
847
+ }
848
+
849
+ .delete-btn:hover {
850
+ background: #b91c1c;
851
+ }
852
+ ```
853
+
854
+ ## Best Practices
855
+
856
+ ### Project Structure
857
+
858
+ ```
859
+ my-app/
860
+ ├── src/
861
+ │ ├── components/
862
+ │ │ ├── Header.tsx
863
+ │ │ └── UserList.tsx
864
+ │ ├── styles/
865
+ │ │ ├── globals.css
866
+ │ │ └── components.css
867
+ │ ├── utils/
868
+ │ │ └── api.ts
869
+ │ ├── App.tsx
870
+ │ └── main.tsx
871
+ ├── public/
872
+ │ ├── index.html
873
+ │ ├── dashboard.html
874
+ │ └── favicon.ico
875
+ ├── server/
876
+ │ ├── routes/
877
+ │ │ ├── users.ts
878
+ │ │ └── auth.ts
879
+ │ ├── db/
880
+ │ │ └── schema.sql
881
+ │ └── index.ts
882
+ ├── bunfig.toml
883
+ └── package.json
884
+ ```
885
+
886
+ ### Environment-Based Configuration
887
+
888
+ ```ts title="server/config.ts" icon="/icons/typescript.svg"
889
+ export const config = {
890
+ development: process.env.NODE_ENV !== "production",
891
+ port: process.env.PORT || 3000,
892
+ database: {
893
+ url: process.env.DATABASE_URL || "./dev.db",
894
+ },
895
+ cors: {
896
+ origin: process.env.CORS_ORIGIN || "*",
897
+ },
898
+ };
899
+ ```
900
+
901
+ ### Error Handling
902
+
903
+ ```ts title="server/middleware.ts" icon="/icons/typescript.svg"
904
+ export function errorHandler(error: Error, req: Request) {
905
+ console.error("Server error:", error);
906
+
907
+ if (process.env.NODE_ENV === "production") {
908
+ return Response.json({ error: "Internal server error" }, { status: 500 });
909
+ }
910
+
911
+ return Response.json(
912
+ {
913
+ error: error.message,
914
+ stack: error.stack,
915
+ },
916
+ { status: 500 },
917
+ );
918
+ }
919
+ ```
920
+
921
+ ### API Response Helpers
922
+
923
+ ```ts title="server/utils.ts" icon="/icons/typescript.svg"
924
+ export function json(data: any, status = 200) {
925
+ return Response.json(data, { status });
926
+ }
927
+
928
+ export function error(message: string, status = 400) {
929
+ return Response.json({ error: message }, { status });
930
+ }
931
+
932
+ export function notFound(message = "Not found") {
933
+ return error(message, 404);
934
+ }
935
+
936
+ export function unauthorized(message = "Unauthorized") {
937
+ return error(message, 401);
938
+ }
939
+ ```
940
+
941
+ ### Type Safety
942
+
943
+ ```ts title="types/api.ts" icon="/icons/typescript.svg"
944
+ export interface User {
945
+ id: number;
946
+ name: string;
947
+ email: string;
948
+ created_at: string;
949
+ }
950
+
951
+ export interface CreateUserRequest {
952
+ name: string;
953
+ email: string;
954
+ }
955
+
956
+ export interface ApiResponse<T> {
957
+ data?: T;
958
+ error?: string;
959
+ }
960
+ ```
961
+
962
+ ## Deployment
963
+
964
+ ### Production Build
965
+
966
+ ```bash terminal icon="terminal"
967
+ # Build for production
968
+ bun build --target=bun --production --outdir=dist ./server/index.ts
969
+
970
+ # Run production server
971
+ NODE_ENV=production bun dist/index.js
972
+ ```
973
+
974
+ ### Docker Deployment
975
+
976
+ ```dockerfile title="Dockerfile" icon="docker"
977
+ FROM oven/bun:1 as base
978
+ WORKDIR /usr/src/app
979
+
980
+ # Install dependencies
981
+ COPY package.json bun.lockb ./
982
+ RUN bun install --frozen-lockfile
983
+
984
+ # Copy source code
985
+ COPY . .
986
+
987
+ # Build application
988
+ RUN bun build --target=bun --production --outdir=dist ./server/index.ts
989
+
990
+ # Production stage
991
+ FROM oven/bun:1-slim
992
+ WORKDIR /usr/src/app
993
+ COPY --from=base /usr/src/app/dist ./
994
+ COPY --from=base /usr/src/app/public ./public
995
+
996
+ EXPOSE 3000
997
+ CMD ["bun", "index.js"]
998
+ ```
999
+
1000
+ ### Environment Variables
1001
+
1002
+ ```bash title=".env.production" icon="file-code"
1003
+ NODE_ENV=production
1004
+ PORT=3000
1005
+ DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
1006
+ CORS_ORIGIN=https://myapp.com
1007
+ ```
1008
+
1009
+ ## Migration from Other Frameworks
1010
+
1011
+ ### From Express + Webpack
1012
+
1013
+ ```ts title="server.ts" icon="/icons/typescript.svg"
1014
+ // Before (Express + Webpack)
1015
+ app.use(express.static("dist"));
1016
+ app.get("/api/users", (req, res) => {
1017
+ res.json(users);
1018
+ });
1019
+
1020
+ // After (Bun fullstack)
1021
+ serve({
1022
+ routes: {
1023
+ "/": homepage, // Replaces express.static
1024
+ "/api/users": {
1025
+ GET() {
1026
+ return Response.json(users);
1027
+ },
1028
+ },
1029
+ },
1030
+ });
1031
+ ```
1032
+
1033
+ ### From Next.js API Routes
1034
+
1035
+ ```ts title="server.ts" icon="/icons/typescript.svg"
1036
+ // Before (Next.js)
1037
+ export default function handler(req, res) {
1038
+ if (req.method === 'GET') {
1039
+ res.json(users);
1040
+ }
1041
+ }
1042
+
1043
+ // After (Bun)
1044
+ "/api/users": {
1045
+ GET() { return Response.json(users); }
1046
+ }
1047
+ ```
1048
+
1049
+ ## Limitations and Future Plans
1050
+
1051
+ ### Current Limitations
1052
+
1053
+ - `bun build` CLI integration is not yet available for fullstack apps
1054
+ - Auto-discovery of API routes is not implemented
1055
+ - Server-side rendering (SSR) is not built-in
1056
+
1057
+ ### Planned Features
1058
+
1059
+ - Integration with `bun build` CLI
1060
+ - File-based routing for API endpoints
1061
+ - Built-in SSR support
1062
+ - Enhanced plugin ecosystem
1063
+
1064
+ <Note>This is a work in progress. Features and APIs may change as Bun continues to evolve.</Note>