bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/guides/ecosystem/prisma.md

@@ -0,0 +1,140 @@
+---
+name: Use Prisma with Bun
+---
+
+{% callout %}
+**Note** — At the moment Prisma needs Node.js to be installed to run certain generation code. Make sure Node.js is installed in the environment where you're running `bunx prisma` commands.
+{% /callout %}
+
+---
+
+Prisma works out of the box with Bun. First, create a directory and initialize it with `bun init`.
+
+```bash
+$ mkdir prisma-app
+$ cd prisma-app
+$ bun init
+```
+
+---
+
+Then install the Prisma CLI (`prisma`) and Prisma Client (`@prisma/client`) as dependencies.
+
+```bash
+$ bun add -d prisma
+$ bun add @prisma/client
+```
+
+---
+
+We'll use the Prisma CLI with `bunx` to initialize our schema and migration directory. For simplicity we'll be using an in-memory SQLite database.
+
+```bash
+$ bunx prisma init --datasource-provider sqlite
+```
+
+---
+
+Open `prisma/schema.prisma` and add a simple `User` model.
+
+```prisma-diff#prisma/schema.prisma
+  generator client {
+    provider = "prisma-client-js"
+  }
+
+  datasource db {
+    provider = "sqlite"
+    url      = env("DATABASE_URL")
+  }
+
++ model User {
++   id    Int     @id @default(autoincrement())
++   email String  @unique
++   name  String?
++ }
+```
+
+---
+
+Then generate and run initial migration.
+
+This will generate a `.sql` migration file in `prisma/migrations`, create a new SQLite instance, and execute the migration against the new instance.
+
+```bash
+$ bunx prisma migrate dev --name init
+Environment variables loaded from .env
+Prisma schema loaded from prisma/schema.prisma
+Datasource "db": SQLite database "dev.db" at "file:./dev.db"
+
+SQLite database dev.db created at file:./dev.db
+
+Applying migration `20230928182242_init`
+
+The following migration(s) have been created and applied from new schema changes:
+
+migrations/
+  └─ 20230928182242_init/
+    └─ migration.sql
+
+Your database is now in sync with your schema.
+
+✔ Generated Prisma Client (v5.3.1) to ./node_modules/@prisma/client in 41ms
+```
+
+---
+
+As indicated in the output, Prisma re-generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. You can manually re-generate the client with the Prisma CLI.
+
+```sh
+$ bunx prisma generate
+```
+
+---
+
+We can import the generated client from `@prisma/client`.
+
+```ts#src/index.ts
+import {PrismaClient} from "@prisma/client";
+```
+
+---
+
+Let's write a simple script to create a new user, then count the number of users in the database.
+
+```ts#index.ts
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+// create a new user
+await prisma.user.create({
+  data: {
+    name: "John Dough",
+    email: `john-${Math.random()}@example.com`,
+  },
+});
+
+// count the number of users
+const count = await prisma.user.count();
+console.log(`There are ${count} users in the database.`);
+```
+
+---
+
+Let's run this script with `bun run`. Each time we run it, a new user is created.
+
+```bash
+$ bun run index.ts
+Created john-0.12802932895402364@example.com
+There are 1 users in the database.
+$ bun run index.ts
+Created john-0.8671308799782803@example.com
+There are 2 users in the database.
+$ bun run index.ts
+Created john-0.4465968383115295@example.com
+There are 3 users in the database.
+```
+
+---
+
+That's it! Now that you've set up Prisma using Bun, we recommend referring to the [official Prisma docs](https://www.prisma.io/docs/concepts/components/prisma-client) as you continue to develop your application.

package/docs/guides/ecosystem/qwik.md

@@ -0,0 +1,107 @@
+---
+name: Build an app with Qwik and Bun
+---
+
+Initialize a new Qwik app with `bunx create-qwik`.
+
+The `create-qwik` package detects when you are using `bunx` and will automatically install dependencies using `bun`.
+
+```sh
+$ bun create qwik
+
+      ............
+    .::: :--------:.
+   .::::  .:-------:.
+  .:::::.   .:-------.
+  ::::::.     .:------.
+ ::::::.        :-----:
+ ::::::.       .:-----.
+  :::::::.     .-----.
+   ::::::::..   ---:.
+    .:::::::::. :-:.
+     ..::::::::::::
+             ...::::
+
+
+┌  Let's create a  Qwik App  ✨ (v1.2.10)
+│
+◇  Where would you like to create your new project? (Use '.' or './' for current directory)
+│  ./my-app
+│
+●  Creating new project in  /path/to/my-app  ... 🐇
+│
+◇  Select a starter
+│  Basic App
+│
+◇  Would you like to install bun dependencies?
+│  Yes
+│
+◇  Initialize a new git repository?
+│  No
+│
+◇  Finishing the install. Wanna hear a joke?
+│  Yes
+│
+○  ────────────────────────────────────────────────────────╮
+│                                                          │
+│  How do you know if there’s an elephant under your bed?  │
+│  Your head hits the ceiling!                             │
+│                                                          │
+├──────────────────────────────────────────────────────────╯
+│
+◇  App Created 🐰
+│
+◇  Installed bun dependencies 📋
+│
+○  Result ─────────────────────────────────────────────╮
+│                                                      │
+│  Success!  Project created in my-app directory       │
+│                                                      │
+│  Integrations? Add Netlify, Cloudflare, Tailwind...  │
+│  bun qwik add                                        │
+│                                                      │
+│  Relevant docs:                                      │
+│  https://qwik.builder.io/docs/getting-started/       │
+│                                                      │
+│  Questions? Start the conversation at:               │
+│  https://qwik.builder.io/chat                        │
+│  https://twitter.com/QwikDev                         │
+│                                                      │
+│  Presentations, Podcasts and Videos:                 │
+│  https://qwik.builder.io/media/                      │
+│                                                      │
+│  Next steps:                                         │
+│  cd my-app                                           │
+│  bun start                                           │
+│                                                      │
+│                                                      │
+├──────────────────────────────────────────────────────╯
+│
+└  Happy coding! 🎉
+
+```
+
+---
+
+Run `bun run dev` to start the development server.
+
+```sh
+$ bun run dev
+  $ vite--mode ssr
+
+  VITE v4.4.7  ready in 1190 ms
+
+  ➜  Local:   http://localhost:5173/
+  ➜  Network: use --host to expose
+  ➜  press h to show help
+```
+
+---
+
+Open [http://localhost:5173](http://localhost:5173) with your browser to see the result. Qwik will hot-reload your app as you edit your source files.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/ec35f2f7-03dd-4c90-851e-fb4ad150bb28" alt="Qwik screenshot" /%}
+
+---
+
+Refer to the [Qwik docs](https://qwik.builder.io/docs/getting-started/) for complete documentation.

package/docs/guides/ecosystem/react.md

@@ -0,0 +1,49 @@
+---
+name: Use React and JSX
+---
+
+React just works with Bun. Bun supports `.jsx` and `.tsx` files out of the box.
+
+Remember that JSX is just a special syntax for including HTML-like syntax in JavaScript files. React uses JSX syntax, as do alternatives like [Preact](https://preactjs.com/) and [Solid](https://www.solidjs.com/). Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution.
+
+---
+
+Bun _assumes_ you're using React (unless you [configure it otherwise](https://bun.sh/docs/runtime/bunfig#jsx)) so a line like this:
+
+```
+const element = <h1>Hello, world!</h1>;
+```
+
+---
+
+is internally converted into something like this:
+
+```ts
+// jsxDEV
+import { jsx } from "react/jsx-dev-runtime";
+
+const element = jsx("h1", { children: "Hello, world!" });
+```
+
+---
+
+This code requires `react` to run, so make sure you've installed React.
+
+```bash
+$ bun install react
+```
+
+---
+
+Bun implements special logging for JSX components to make debugging easier.
+
+```bash
+$ bun run log-my-component.tsx
+<Component message="Hello world!" />
+```
+
+---
+
+As far as "official support" for React goes, that's it. React is a library like any other, and Bun can run that library. Bun is not a framework, so you should use a framework like [Vite](https://vitejs.dev/) to build an app with server-side rendering and hot reloading in the browser.
+
+Refer to [Runtime > JSX](https://bun.sh/docs/runtime/jsx) for complete documentation on configuring JSX.

package/docs/guides/ecosystem/remix.md

@@ -0,0 +1,78 @@
+---
+name: Build an app with Remix and Bun
+---
+
+{% callout %}
+Currently the Remix development server (`remix dev`) relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a project and install dependencies, but it uses Node.js to run the dev server.
+{% /callout %}
+
+---
+
+Initialize a Remix app with `create-remix`.
+
+```sh
+$ bun create remix
+
+ remix   v1.19.3 💿 Let's build a better website...
+
+   dir   Where should we create your new project?
+         ./my-app
+
+      ◼  Using basic template See https://remix.run/docs/en/main/guides/templates#templates for more
+      ✔  Template copied
+
+   git   Initialize a new git repository?
+         Yes
+
+  deps   Install dependencies with bun?
+         Yes
+
+      ✔  Dependencies installed
+
+      ✔  Git initialized
+
+  done   That's it!
+
+         Enter your project directory using cd ./my-app
+         Check out README.md for development and deploy instructions.
+```
+
+---
+
+To start the dev server, run `bun run dev` from the project root. This will start the dev server using the `remix dev` command. Note that Node.js will be used to run the dev server.
+
+```sh
+$ cd my-app
+$ bun run dev
+  $ remix dev
+
+  💿  remix dev
+
+  info  building...
+  info  built (263ms)
+  Remix App Server started at http://localhost:3000 (http://172.20.0.143:3000)
+```
+
+---
+
+Open [http://localhost:3000](http://localhost:3000) to see the app. Any changes you make to `app/routes/_index.tsx` will be hot-reloaded in the browser.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/c26f1059-a5d4-4c0b-9a88-d9902472fd77" caption="Remix app running on localhost" /%}
+
+---
+
+To build and start your app, run `bun run build` then `bun run start` from the project root.
+
+```sh
+$ bun run build
+ $ remix build
+ info  building... (NODE_ENV=production)
+ info  built (158ms)
+$ bun start
+ $ remix-serve ./build/index.js
+ [remix-serve] http://localhost:3000 (http://192.168.86.237:3000)
+```
+
+---
+
+Read the [Remix docs](https://remix.run/) for more information on how to build apps with Remix.

package/docs/guides/ecosystem/render.md

@@ -0,0 +1,79 @@
+---
+name: Deploy a Bun application on Render
+---
+
+[Render](https://render.com/) is a cloud platform that lets you flexibly build, deploy, and scale your apps.
+
+It offers features like auto deploys from GitHub, a global CDN, private networks, automatic HTTPS setup, and managed PostgreSQL and Redis.
+
+Render supports Bun natively. You can deploy Bun apps as web services, background workers, cron jobs, and more.
+
+---
+
+As an example, let's deploy a simple Express HTTP server to Render.
+
+---
+
+Create a new GitHub repo named `myapp`. Git clone it locally.
+
+```bash
+git clone git@github.com:my-github-username/myapp.git
+cd myapp
+```
+
+---
+
+Add the Express library.
+
+```bash
+bun add express
+```
+
+---
+
+Define a simple server with Express:
+
+```ts#app.ts
+import express from "express";
+
+const app = express();
+const port = process.env.PORT || 3001;
+
+app.get("/", (req, res) => {
+  res.send("Hello World!");
+});
+
+app.listen(port, () => {
+  console.log(`Listening on port ${port}...`);
+});
+```
+
+---
+
+Commit your changes and push to GitHub.
+
+```bash
+git add app.ts bun.lockb package.json
+git commit -m "Create simple Express app"
+git push origin main
+```
+
+---
+
+In your [Render Dashboard](https://dashboard.render.com/), click `New` > `Web Service` and connect your `myapp` repo.
+
+---
+
+In the Render UI, provide the following values during web service creation:
+
+|                   |               |
+| ----------------- | ------------- |
+| **Runtime**       | `Node`        |
+| **Build Command** | `bun install` |
+| **Start Command** | `bun app.js`  |
+
+---
+
+That's it! Your web service will be live at its assigned `onrender.com` URL as soon as the build finishes.
+
+You can view the [deploy logs](https://docs.render.com/logging#logs-for-an-individual-deploy-or-job) for details. Refer to [Render's documentation](https://docs.render.com/deploys) for a complete overview of deploying on Render.

package/docs/guides/ecosystem/sentry.md

@@ -0,0 +1,52 @@
+---
+name: Add Sentry to a Bun app
+---
+
+[Sentry](https://sentry.io) is a developer-first error tracking and performance monitoring platform. Sentry has a first-class SDK for Bun, `@sentry/bun`, that instruments your Bun application to automatically collect error and performance data.
+
+Don't already have an account and Sentry project established? Head over to [sentry.io](https://sentry.io/signup/), then return to this page.
+
+---
+
+To start using Sentry with Bun, first install the Sentry Bun SDK.
+
+```bash
+bun add @sentry/bun
+```
+
+---
+
+Then, initialize the Sentry SDK with your Sentry DSN in your app's entry file. You can find your DSN in your Sentry project settings.
+
+```js
+import * as Sentry from "@sentry/bun";
+
+// Ensure to call this before importing any other modules!
+Sentry.init({
+  dsn: "__SENTRY_DSN__",
+
+  // Add Performance Monitoring by setting tracesSampleRate
+  // We recommend adjusting this value in production
+  tracesSampleRate: 1.0,
+});
+```
+
+---
+
+You can verify that Sentry is working by capturing a test error:
+
+```js
+setTimeout(() => {
+  try {
+    foo();
+  } catch (e) {
+    Sentry.captureException(e);
+  }
+}, 99);
+```
+
+To view and resolve the recorded error, log into [sentry.io](https://sentry.io/) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.
+
+---
+
+To learn more about Sentry and using the Sentry Bun SDK, view the [Sentry documentation](https://docs.sentry.io/platforms/javascript/guides/bun).

package/docs/guides/ecosystem/solidstart.md

@@ -0,0 +1,58 @@
+---
+name: Build an app with SolidStart and Bun
+---
+
+{% callout %}
+SolidStart currently relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a project and install dependencies, but it uses Node.js to run the dev server.
+{% /callout %}
+
+---
+
+Initialize a SolidStart app with `create-solid`.
+
+```sh
+$ bun create solid my-app
+create-solid version 0.2.31
+
+Welcome to the SolidStart setup wizard!
+
+There are definitely bugs and some feature might not work yet.
+If you encounter an issue, have a look at
+https://github.com/solidjs/solid-start/issues and open a new one,
+if it is not already tracked.
+
+✔ Which template do you want to use? › todomvc
+✔ Server Side Rendering? … yes
+✔ Use TypeScript? … yes
+cloned solidjs/solid-start#main to /path/to/my-app/.solid-start
+✔ Copied project files
+```
+
+---
+
+As instructed by the `create-solid` CLI, let's install our dependencies.
+
+```sh
+$ cd my-app
+$ bun install
+```
+
+---
+
+Then run the development server.
+
+```sh
+$ bun run dev
+# or, equivalently
+$ bunx solid-start dev
+```
+
+---
+
+Open [localhost:3000](http://localhost:3000). Any changes you make to `src/routes/index.tsx` will be hot-reloaded automatically.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/1e8043c4-49d1-498c-9add-c1eaab6c7167" alt="SolidStart demo app" /%}
+
+---
+
+Refer to the [SolidStart website](https://start.solidjs.com/getting-started/what-is-solidstart) for complete framework documentation.

package/docs/guides/ecosystem/ssr-react.md

@@ -0,0 +1,51 @@
+---
+name: Server-side render (SSR) a React component
+---
+
+To get started, install the canary version of `react` & `react-dom`:
+
+```sh
+# Any package manager can be used
+$ bun add react@canary react-dom@canary
+```
+
+---
+
+To render a React component to an HTML stream server-side (SSR):
+
+```tsx
+import { renderToReadableStream } from "react-dom/server";
+
+function Component(props: { message: string }) {
+  return (
+    <body>
+      <h1>{props.message}</h1>
+    </body>
+  );
+}
+
+const stream = await renderToReadableStream(
+  <Component message="Hello from server!" />,
+);
+```
+
+---
+
+Combining this with `Bun.serve()`, we get a simple SSR HTTP server:
+
+```tsx
+Bun.serve({
+  async fetch() {
+    const stream = await renderToReadableStream(
+      <Component message="Hello from server!" />,
+    );
+    return new Response(stream, {
+      headers: { "Content-Type": "text/html" },
+    });
+  },
+});
+```
+
+---
+
+React `19` and later includes an [SSR optimization](https://github.com/facebook/react/pull/25597) that takes advantage of Bun's "direct" `ReadableStream` implementation. If you run into an error like `export named 'renderToReadableStream' not found`, please make sure to install the canary version of `react` & `react-dom`, or import from `react-dom/server.browser` instead of `react-dom/server`. See [facebook/react#28941](https://github.com/facebook/react/issues/28941) for more information.

package/docs/guides/ecosystem/stric.md

@@ -0,0 +1,55 @@
+---
+name: Build an HTTP server using StricJS and Bun
+---
+
+[StricJS](https://github.com/bunsvr) is a Bun framework for building high-performance web applications and APIs.
+
+- **Fast** — Stric is one of the fastest Bun frameworks. See [benchmark](https://github.com/bunsvr/benchmark) for more details.
+- **Minimal** — The basic components like `@stricjs/router` and `@stricjs/utils` are under 50kB and require no external dependencies.
+- **Extensible** — Stric includes with a plugin system, dependency injection, and optional optimizations for handling requests.
+
+---
+
+Use `bun init` to create an empty project.
+
+```bash
+$ mkdir myapp
+$ cd myapp
+$ bun init
+$ bun add @stricjs/router @stricjs/utils
+```
+
+---
+
+To implement a simple HTTP server with StricJS:
+
+```ts#index.ts
+import { Router } from '@stricjs/router';
+
+export default new Router()
+  .get('/', () => new Response('Hi'));
+```
+
+---
+
+To serve static files from `/public`:
+
+```ts#index.ts
+import { dir } from '@stricjs/utils';
+
+export default new Router()
+  .get('/', () => new Response('Hi'))
+  .get('/*', dir('./public'));
+```
+
+---
+
+Run the file in watch mode to start the development server.
+
+```bash
+$ bun --watch run index.ts
+```
+
+---
+
+For more info, see Stric's [documentation](https://stricjs.netlify.app).