bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/guides/deployment/railway.md

@@ -1,157 +0,0 @@
----
-name: Deploy a Bun application on Railway
-description: Deploy Bun applications to Railway with this step-by-step guide covering CLI and dashboard methods, optional PostgreSQL setup, and automatic SSL configuration.
----
-
-Railway is an infrastructure platform where you can provision infrastructure, develop with that infrastructure locally, and then deploy to the cloud. It enables instant deployments from GitHub with zero configuration, automatic SSL, and built-in database provisioning.
-
-This guide walks through deploying a Bun application with a PostgreSQL database (optional), which is exactly what the template below provides.
-
-You can either follow this guide step-by-step or simply deploy the pre-configured template with one click:
-
-{% raw %}
-
-<a href="https://railway.com/deploy/bun-react-postgres?referralCode=Bun&utm_medium=integration&utm_source=template&utm_campaign=bun" target="_blank">
-  <img src="https://railway.com/button.svg" alt="Deploy on Railway" />
-</a>
-
-{% /raw %}
-
----
-
-**Prerequisites**:
-
-- A Bun application ready for deployment
-- A [Railway account](https://railway.app/)
-- Railway CLI (for CLI deployment method)
-- A GitHub account (for Dashboard deployment method)
-
----
-
-## Method 1: Deploy via CLI
-
----
-
-#### Step 1
-
-Ensure sure you have the Railway CLI installed.
-
-```bash
-bun install -g @railway/cli
-```
-
----
-
-#### Step 2
-
-Log into your Railway account.
-
-```bash
-railway login
-```
-
----
-
-#### Step 3
-
-After successfully authenticating, initialize a new project.
-
-```bash
-# Initialize project
-bun-react-postgres$ railway init
-```
-
----
-
-#### Step 4
-
-After initializing the project, add a new database and service.
-
-> **Note:** Step 4 is only necessary if your application uses a database. If you don't need PostgreSQL, skip to Step 5.
-
-```bash
-# Add PostgreSQL database. Make sure to add this first!
-bun-react-postgres$ railway add --database postgres
-
-# Add your application service.
-bun-react-postgres$ railway add --service bun-react-db --variables DATABASE_URL=\${{Postgres.DATABASE_URL}}
-```
-
----
-
-#### Step 5
-
-After the services have been created and connected, deploy the application to Railway. By default, services are only accessible within Railway's private network. To make your app publicly accessible, you need to generate a public domain.
-
-```bash
-# Deploy your application
-bun-nextjs-starter$ railway up
-
-# Generate public domain
-bun-nextjs-starter$ railway domain
-```
-
----
-
-## Method 2: Deploy via Dashboard
-
----
-
-#### Step 1
-
-Create a new project
-
-1. Go to [Railway Dashboard](http://railway.com/dashboard?utm_medium=integration&utm_source=docs&utm_campaign=bun)
-2. Click **"+ New"** → **"GitHub repo"**
-3. Choose your repository
-
----
-
-#### Step 2
-
-Add a PostgreSQL database, and connect this database to the service
-
-> **Note:** Step 2 is only necessary if your application uses a database. If you don't need PostgreSQL, skip to Step 3.
-
-1. Click **"+ New"** → **"Database"** → **"Add PostgreSQL"**
-2. After the database has been created, select your service (not the database)
-3. Go to **"Variables"** tab
-4. Click **"+ New Variable"** → **"Add Reference"**
-5. Select `DATABASE_URL` from postgres
-
----
-
-#### Step 3
-
-Generate a public domain
-
-1. Select your service
-2. Go to **"Settings"** tab
-3. Under **"Networking"**, click **"Generate Domain"**
-
----
-
-Your app is now live! Railway auto-deploys on every GitHub push.
-
----
-
-## Configuration (Optional)
-
----
-
-By default, Railway uses [Nixpacks](https://docs.railway.com/guides/build-configuration#nixpacks-options) to automatically detect and build your Bun application with zero configuration.
-
-However, using the [Railpack](https://docs.railway.com/guides/build-configuration#railpack) application builder provides better Bun support, and will always support the latest version of Bun. The pre-configured templates use Railpack by default.
-
-To enable Railpack in a custom project, add the following to your `railway.json`:
-
-```json
-{
-  "$schema": "https://railway.com/railway.schema.json",
-  "build": {
-    "builder": "RAILPACK"
-  }
-}
-```
-
-For more build configuration settings, check out the [Railway documentation](https://docs.railway.com/guides/build-configuration).

package/docs/guides/ecosystem/astro.md

@@ -1,72 +0,0 @@
----
-name: Build an app with Astro and Bun
----
-
-Initialize a fresh Astro app with `bun create astro`. The `create-astro` package detects when you are using `bunx` and will automatically install dependencies using `bun`.
-
-```sh
-$ bun create astro
-╭─────╮  Houston:
-│ ◠ ◡ ◠  We're glad to have you on board.
-╰─────╯
-
- astro   v3.1.4 Launch sequence initiated.
-
-   dir   Where should we create your new project?
-         ./fumbling-field
-
-  tmpl   How would you like to start your new project?
-         Use blog template
-      ✔  Template copied
-
-  deps   Install dependencies?
-         Yes
-      ✔  Dependencies installed
-
-    ts   Do you plan to write TypeScript?
-         Yes
-
-   use   How strict should TypeScript be?
-         Strict
-      ✔  TypeScript customized
-
-   git   Initialize a new git repository?
-         Yes
-      ✔  Git initialized
-
-  next   Liftoff confirmed. Explore your project!
-
-         Enter your project directory using cd ./fumbling-field
-         Run `bun run dev` to start the dev server. CTRL+C to stop.
-         Add frameworks like react or tailwind using astro add.
-
-         Stuck? Join us at https://astro.build/chat
-
-╭─────╮  Houston:
-│ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
-╰─────╯
-```
-
----
-
-Start the dev server with `bunx`.
-
-By default, Bun will run the dev server with Node.js. To use the Bun runtime instead, use the `--bun` flag.
-
-```sh
-$ bunx --bun astro dev
-  🚀  astro  v3.1.4 started in 200ms
-
-  ┃ Local    http://localhost:4321/
-  ┃ Network  use --host to expose
-```
-
----
-
-Open [http://localhost:4321](http://localhost:4321) with your browser to see the result. Astro will hot-reload your app as you edit your source files.
-
-{% image src="https://i.imgur.com/Dswiu6w.png" caption="An Astro v3 starter app running on Bun" %}
-
----
-
-Refer to the [Astro docs](https://docs.astro.build/en/getting-started/) for complete documentation.

package/docs/guides/ecosystem/discordjs.md

@@ -1,77 +0,0 @@
----
-name: Create a Discord bot
----
-
-Discord.js works out of the box with Bun. Let's write a simple bot. First create a directory and initialize it with `bun init`.
-
-```sh
-$ mkdir my-bot
-$ cd my-bot
-$ bun init
-```
-
----
-
-Now install Discord.js.
-
-```sh
-$ bun add discord.js
-```
-
----
-
-Before we go further, we need to go to the [Discord developer portal](https://discord.com/developers/applications), login/signup, create a new _Application_, then create a new _Bot_ within that application. Follow the [official guide](https://discordjs.guide/preparations/setting-up-a-bot-application.html#creating-your-bot) for step-by-step instructions.
-
----
-
-Once complete, you'll be presented with your bot's _private key_. Let's add this to a file called `.env.local`. Bun automatically reads this file and loads it into `process.env`.
-
-{% callout %}
-This is an example token that has already been invalidated.
-{% /callout %}
-
-```txt#.env.local
-DISCORD_TOKEN=NzkyNzE1NDU0MTk2MDg4ODQy.X-hvzA.Ovy4MCQywSkoMRRclStW4xAYK7I
-```
-
----
-
-Be sure to add `.env.local` to your `.gitignore`! It is dangerous to check your bot's private key into version control.
-
-```txt#.gitignore
-node_modules
-.env.local
-```
-
----
-
-Now let's actually write our bot in a new file called `bot.ts`.
-
-```ts#bot.ts
-// import discord.js
-import {Client, Events, GatewayIntentBits} from 'discord.js';
-
-// create a new Client instance
-const client = new Client({intents: [GatewayIntentBits.Guilds]});
-
-// listen for the client to be ready
-client.once(Events.ClientReady, (c) => {
-  console.log(`Ready! Logged in as ${c.user.tag}`);
-});
-
-// login with the token from .env.local
-client.login(process.env.DISCORD_TOKEN);
-```
-
----
-
-Now we can run our bot with `bun run`. It may take a several seconds for the client to initialize the first time you run the file.
-
-```sh
-$ bun run bot.ts
-Ready! Logged in as my-bot#1234
-```
-
----
-
-You're up and running with a bare-bones Discord.js bot! This is a basic guide to setting up your bot with Bun; we recommend the [official discord.js docs](https://discordjs.guide/) for complete information on the `discord.js` API.

package/docs/guides/ecosystem/docker.md

@@ -1,140 +0,0 @@
----
-name: Containerize a Bun application with Docker
----
-
-{% callout %}
-This guide assumes you already have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed.
-{% /callout %}
-
-[Docker](https://www.docker.com) is a platform for packaging and running an application as a lightweight, portable _container_ that encapsulates all the necessary dependencies.
-
----
-
-To _containerize_ our application, we define a `Dockerfile`. This file contains a list of instructions to initialize the container, copy our local project files into it, install dependencies, and starts the application.
-
-```docker#Dockerfile
-# use the official Bun image
-# see all versions at https://hub.docker.com/r/oven/bun/tags
-FROM oven/bun:1 AS base
-WORKDIR /usr/src/app
-
-# install dependencies into temp directory
-# this will cache them and speed up future builds
-FROM base AS install
-RUN mkdir -p /temp/dev
-COPY package.json bun.lock /temp/dev/
-RUN cd /temp/dev && bun install --frozen-lockfile
-
-# install with --production (exclude devDependencies)
-RUN mkdir -p /temp/prod
-COPY package.json bun.lock /temp/prod/
-RUN cd /temp/prod && bun install --frozen-lockfile --production
-
-# copy node_modules from temp directory
-# then copy all (non-ignored) project files into the image
-FROM base AS prerelease
-COPY --from=install /temp/dev/node_modules node_modules
-COPY . .
-
-# [optional] tests & build
-ENV NODE_ENV=production
-RUN bun test
-RUN bun run build
-
-# copy production dependencies and source code into final image
-FROM base AS release
-COPY --from=install /temp/prod/node_modules node_modules
-COPY --from=prerelease /usr/src/app/index.ts .
-COPY --from=prerelease /usr/src/app/package.json .
-
-# run the app
-USER bun
-EXPOSE 3000/tcp
-ENTRYPOINT [ "bun", "run", "index.ts" ]
-```
-
----
-
-Now that you have your docker image, let's look at `.dockerignore` which has the same syntax as `.gitignore`, here you need to specify the files/directories that must not go in any stage of the docker build. An example for a ignore file is
-
-```txt#.dockerignore
-node_modules
-Dockerfile*
-docker-compose*
-.dockerignore
-.git
-.gitignore
-README.md
-LICENSE
-.vscode
-Makefile
-helm-charts
-.env
-.editorconfig
-.idea
-coverage*
-```
-
----
-
-We'll now use `docker build` to convert this `Dockerfile` into a _Docker image_, a self-contained template containing all the dependencies and configuration required to run the application.
-
-The `-t` flag lets us specify a name for the image, and `--pull` tells Docker to automatically download the latest version of the base image (`oven/bun`). The initial build will take longer, as Docker will download all the base images and dependencies.
-
-```bash
-$ docker build --pull -t bun-hello-world .
-[+] Building 0.9s (21/21) FINISHED
- => [internal] load build definition from Dockerfile                                                                                     0.0s
- => => transferring dockerfile: 37B                                                                                                      0.0s
- => [internal] load .dockerignore                                                                                                        0.0s
- => => transferring context: 35B                                                                                                         0.0s
- => [internal] load metadata for docker.io/oven/bun:1                                                                                    0.8s
- => [auth] oven/bun:pull token for registry-1.docker.io                                                                                  0.0s
- => [base 1/2] FROM docker.io/oven/bun:1@sha256:373265748d3cd3624cb3f3ee6004f45b1fc3edbd07a622aeeec17566d2756997                         0.0s
- => [internal] load build context                                                                                                        0.0s
- => => transferring context: 155B                                                                                                        0.0s
- # ...lots of commands...
- => exporting to image                                                                                                                   0.0s
- => => exporting layers                                                                                                                  0.0s
- => => writing image sha256:360663f7fdcd6f11e8e94761d5592e2e4dfc8d167f034f15cd5a863d5dc093c4                                             0.0s
- => => naming to docker.io/library/bun-hello-world                                                                                       0.0s
-```
-
----
-
-We've built a new _Docker image_. Now let's use that image to spin up an actual, running _container_.
-
-We'll use `docker run` to start a new container using the `bun-hello-world` image. It will be run in _detached_ mode (`-d`) and we'll map the container's port 3000 to our local machine's port 3000 (`-p 3000:3000`).
-
-The `run` command prints a string representing the _container ID_.
-
-```sh
-$ docker run -d -p 3000:3000 bun-hello-world
-7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d
-```
-
----
-
-The container is now running in the background. Visit [localhost:3000](http://localhost:3000). You should see a `Hello, World!` message.
-
----
-
-To stop the container, we'll use `docker stop <container-id>`.
-
-```sh
-$ docker stop 7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d
-```
-
----
-
-If you can't find the container ID, you can use `docker ps` to list all running containers.
-
-```sh
-$ docker ps
-CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
-7f03e212a15e        bun-hello-world     "bun run index.ts"       2 minutes ago       Up 2 minutes        0.0.0.0:3000->3000/tcp   flamboyant_cerf
-```
-
----
-
-That's it! Refer to the [Docker documentation](https://docs.docker.com/) for more advanced usage.

package/docs/guides/ecosystem/drizzle.md

@@ -1,185 +0,0 @@
----
-name: Use Drizzle ORM with Bun
----
-
-Drizzle is an ORM that supports both a SQL-like "query builder" API and an ORM-like [Queries API](https://orm.drizzle.team/docs/rqb). It supports the `bun:sqlite` built-in module.
-
----
-
-Let's get started by creating a fresh project with `bun init` and installing Drizzle.
-
-```sh
-$ bun init -y
-$ bun add drizzle-orm
-$ bun add -D drizzle-kit
-```
-
----
-
-Then we'll connect to a SQLite database using the `bun:sqlite` module and create the Drizzle database instance.
-
-```ts#db.ts
-import { drizzle } from "drizzle-orm/bun-sqlite";
-import { Database } from "bun:sqlite";
-
-const sqlite = new Database("sqlite.db");
-export const db = drizzle(sqlite);
-```
-
----
-
-To see the database in action, add these lines to `index.ts`.
-
-```ts#index.ts
-import { db } from "./db";
-import { sql } from "drizzle-orm";
-
-const query = sql`select "hello world" as text`;
-const result = db.get<{ text: string }>(query);
-console.log(result);
-```
-
----
-
-Then run `index.ts` with Bun. Bun will automatically create `sqlite.db` and execute the query.
-
-```sh
-$ bun run index.ts
-{
-  text: "hello world"
-}
-```
-
----
-
-Lets give our database a proper schema. Create a `schema.ts` file and define a `movies` table.
-
-```ts#schema.ts
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
-
-export const movies = sqliteTable("movies", {
-  id: integer("id").primaryKey(),
-  title: text("name"),
-  releaseYear: integer("release_year"),
-});
-```
-
----
-
-We can use the `drizzle-kit` CLI to generate an initial SQL migration.
-
-```sh
-$ bunx drizzle-kit generate --dialect sqlite --schema ./schema.ts
-```
-
----
-
-This creates a new `drizzle` directory containing a `.sql` migration file and `meta` directory.
-
-```txt
-drizzle
-├── 0000_ordinary_beyonder.sql
-└── meta
-    ├── 0000_snapshot.json
-    └── _journal.json
-```
-
----
-
-We can execute these migrations with a simple `migrate.ts` script.
-
-This script creates a new connection to a SQLite database that writes to `sqlite.db`, then executes all unexecuted migrations in the `drizzle` directory.
-
-```ts#migrate.ts
-import { migrate } from "drizzle-orm/bun-sqlite/migrator";
-
-import { drizzle } from "drizzle-orm/bun-sqlite";
-import { Database } from "bun:sqlite";
-
-const sqlite = new Database("sqlite.db");
-const db = drizzle(sqlite);
-migrate(db, { migrationsFolder: "./drizzle" });
-```
-
----
-
-We can run this script with `bun` to execute the migration.
-
-```sh
-$ bun run migrate.ts
-```
-
----
-
-Now that we have a database, let's add some data to it. Create a `seed.ts` file with the following contents.
-
-```ts#seed.ts
-import { db } from "./db";
-import * as schema from "./schema";
-
-await db.insert(schema.movies).values([
-  {
-    title: "The Matrix",
-    releaseYear: 1999,
-  },
-  {
-    title: "The Matrix Reloaded",
-    releaseYear: 2003,
-  },
-  {
-    title: "The Matrix Revolutions",
-    releaseYear: 2003,
-  },
-]);
-
-console.log(`Seeding complete.`);
-```
-
----
-
-Then run this file.
-
-```sh
-$ bun run seed.ts
-Seeding complete.
-```
-
----
-
-We finally have a database with a schema and some sample data. Let's use Drizzle to query it. Replace the contents of `index.ts` with the following.
-
-```ts#index.ts
-import * as schema from "./schema";
-import { db } from "./db";
-
-const result = await db.select().from(schema.movies);
-console.log(result);
-```
-
----
-
-Then run the file. You should see the three movies we inserted.
-
-```sh
-$ bun run index.ts
-bun run index.ts
-[
-  {
-    id: 1,
-    title: "The Matrix",
-    releaseYear: 1999
-  }, {
-    id: 2,
-    title: "The Matrix Reloaded",
-    releaseYear: 2003
-  }, {
-    id: 3,
-    title: "The Matrix Revolutions",
-    releaseYear: 2003
-  }
-]
-```
-
----
-
-Refer to the [Drizzle website](https://orm.drizzle.team/docs/overview) for complete documentation.