yamcodes · yamcodes · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025
diff --git a/apps/playgrounds/bun/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc b/apps/playgrounds/bun/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc
@@ -0,0 +1,111 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+
+// import .css files directly and it works
+import './index.css';
+
+import { createRoot } from "react-dom/client";
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
diff --git a/apps/playgrounds/bun/.gitignore b/apps/playgrounds/bun/.gitignore
@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
diff --git a/apps/playgrounds/bun/README.md b/apps/playgrounds/bun/README.md
@@ -0,0 +1,15 @@
+# bun
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
diff --git a/apps/playgrounds/bun/bun.lock b/apps/playgrounds/bun/bun.lock
diff --git a/apps/playgrounds/bun/index.ts b/apps/playgrounds/bun/index.ts
@@ -0,0 +1 @@
+console.log("Hello via Bun!");
diff --git a/apps/playgrounds/bun/package.json b/apps/playgrounds/bun/package.json
@@ -0,0 +1,25 @@
+{
+	"name": "bun-playground",
+	"module": "index.ts",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"dev": "bun --watch run index.ts",
+		"start": "bun run index.ts",
+		"build": "tsc -b && bun run index.ts",
+		"preview": "bun run index.ts",
+		"fix": "pnpm -w run fix",
+		"clean": "rimraf dist node_modules"
+	},
+	"dependencies": {
+		"arkenv": "0.7.5",
+		"arktype": "2.1.26"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.2",
+		"typescript": "5.9.3"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}
diff --git a/apps/playgrounds/bun/tsconfig.json b/apps/playgrounds/bun/tsconfig.json
@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		// Environment setup & latest features
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}
diff --git a/apps/www/content/docs/quickstart.mdx b/apps/www/content/docs/quickstart.mdx
@@ -14,16 +14,20 @@ description: Let's get you started with a few simple steps.
   <Step>
     ## Configure your project
 
-    Enable strict mode for the best typesafety:
+    Enable strict mode for the best typesafety, and use a [modern TypeScript module resolution](https://www.typescriptlang.org/tsconfig/#moduleResolution):
 
     ```json title="tsconfig.json"
     // [!code word:config]
     {
       "compilerOptions": {
-        "strict": true // [!code focus]
+        "strict": true, // [!code focus]
+        "moduleResolution": "bundler" // [!code focus] or "node16" / "nodenext"
       }
     }
     ```
+
+    > [!TIP]
+    > You may omit `moduleResolution` if `module` is `"Preserve", "Node16", or "NodeNext"`. See [Requirements](https://github.com/yamcodes/arkenv?tab=readme-ov-file#requirements) for details.
 
     ArkEnv is built on top of [ArkType](https://arktype.io/). Follow the [ArkType setup instructions](https://arktype.io/docs/intro/setup) to configure your project.
   </Step>

diff --git a/arkenv.code-workspace b/arkenv.code-workspace
@@ -2,6 +2,7 @@
 	"settings": {
 		"files.associations": {
 			"turbo.json": "jsonc",
+			"tsconfig.json": "jsonc",
 			".github/renovate.json": "jsonc"
 		}
 	},
@@ -46,6 +47,10 @@
 			"path": "apps/playgrounds/node",
 			"name": "  node-playground"
 		},
+		{
+			"path": "apps/playgrounds/bun",
+			"name": "  bun-playground"
+		},
 		{
 			"path": "apps/playgrounds/vite",
 			"name": "  vite-playground"