bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/guides/deployment/digital-ocean.mdx

@@ -0,0 +1,161 @@
+---
+title: Deploy a Bun application on DigitalOcean
+sidebarTitle: Deploy on DigitalOcean
+mode: center
+---
+
+[DigitalOcean](https://www.digitalocean.com/) is a cloud platform that provides a range of services for building and deploying applications.
+
+In this guide, we will deploy a Bun HTTP server to DigitalOcean using a `Dockerfile`.
+
+<Note>
+	Before continuing, make sure you have:
+
+    - A Bun application ready for deployment
+    - A [DigitalOcean account](https://www.digitalocean.com/)
+    - [DigitalOcean CLI](https://docs.digitalocean.com/reference/doctl/how-to/install/#step-1-install-doctl) installed and configured
+    - [Docker](https://docs.docker.com/get-started/get-docker/) installed and added to your `PATH`
+
+</Note>
+
+---
+
+<Steps>
+	<Step title="Create a new DigitalOcean Container Registry">
+		Create a new Container Registry to store the Docker image.
+
+    	<Tabs>
+    		<Tab title="Through the DigitalOcean dashboard">
+    			In the DigitalOcean dashboard, go to [**Container Registry**](https://cloud.digitalocean.com/registry), and enter the details for the new registry.
+
+    			<Frame>
+    				![DigitalOcean registry dashboard](/images/guides/digitalocean-7.png)
+    			</Frame>
+
+    			Make sure the details are correct, then click **Create Registry**.
+    		</Tab>
+    		<Tab title="Through the DigitalOcean CLI">
+
+    			```bash terminal icon="terminal"
+    			doctl registry create bun-digitalocean-demo
+    			```
+    			```txt
+    			Name                     Endpoint                                           Region slug
+    			bun-digitalocean-demo    registry.digitalocean.com/bun-digitalocean-demo    sfo2
+    			```
+
+    		</Tab>
+    	</Tabs>
+
+    	You should see the new registry in the [**DigitalOcean registry dashboard**](https://cloud.digitalocean.com/registry):
+
+    	<Frame>
+    		![DigitalOcean registry dashboard](/images/guides/digitalocean-1.png)
+    	</Frame>
+    </Step>
+    <Step title="Create a new Dockerfile">
+    	Make sure you're in the directory containing your project, then create a new `Dockerfile` in the root of your project. This file contains the instructions to initialize the container, copy your local project files into it, install dependencies, and start the application.
+
+    	```docker Dockerfile icon="docker"
+    	# Use the official Bun image to run the application
+    	FROM oven/bun:debian
+
+    	# Set the work directory to `/app`
+    	WORKDIR /app
+
+    	# Copy the package.json and bun.lock into the container
+    	COPY package.json bun.lock ./
+
+    	# Install the dependencies
+    	RUN bun install --production --frozen-lockfile
+
+    	# Copy the rest of the application into the container
+    	COPY . .
+
+    	# Expose the port (DigitalOcean will set PORT env var)
+    	EXPOSE 8080
+
+    	# Run the application
+    	CMD ["bun", "index.ts"]
+    	```
+
+    	<Note>
+    		Make sure that the start command corresponds to your application's entry point. This can also be `CMD ["bun", "run", "start"]` if you have a start script in your `package.json`.
+
+    		This image installs dependencies and runs your app with Bun inside a container. If your app doesn't have dependencies, you can omit the `RUN bun install --production --frozen-lockfile` line.
+    	</Note>
+
+    	Create a new `.dockerignore` file in the root of your project. This file contains the files and directories that should be _excluded_ from the container image, such as `node_modules`. This makes your builds faster and smaller:
+
+    	```docker .dockerignore icon="Docker"
+    	node_modules
+    	Dockerfile*
+    	.dockerignore
+    	.git
+    	.gitignore
+    	README.md
+    	LICENSE
+    	.vscode
+    	.env
+    	# Any other files or directories you want to exclude
+    	```
+    </Step>
+    <Step title="Authenticate Docker with DigitalOcean registry">
+    	Before building and pushing the Docker image, authenticate Docker with the DigitalOcean Container Registry:
+
+    	```bash terminal icon="terminal"
+    	doctl registry login
+    	```
+    	```txt
+    	Successfully authenticated with registry.digitalocean.com
+    	```
+
+    	<Note>
+    		This command authenticates Docker with DigitalOcean's registry using your DigitalOcean credentials. Without this step, the build and push command will fail with a 401 authentication error.
+    	</Note>
+    </Step>
+    <Step title="Build and push the Docker image to the DigitalOcean registry">
+    	Make sure you're in the directory containing your `Dockerfile`, then build and push the Docker image to the DigitalOcean registry in one command:
+
+    	```bash terminal icon="terminal"
+    	docker buildx build --platform=linux/amd64 -t registry.digitalocean.com/bun-digitalocean-demo/bun-digitalocean-demo:latest --push .
+    	```
+
+    	<Note>
+    		If you're building on an ARM Mac (M1/M2), you must use `docker buildx` with `--platform=linux/amd64` to ensure compatibility with DigitalOcean's infrastructure. Using `docker build` without the platform flag will create an ARM64 image that won't run on DigitalOcean.
+    	</Note>
+
+    	Once the image is pushed, you should see it in the [**DigitalOcean registry dashboard**](https://cloud.digitalocean.com/registry):
+
+    	<Frame>
+    		![DigitalOcean registry dashboard](/images/guides/digitalocean-2.png)
+    	</Frame>
+    </Step>
+    <Step title="Create a new DigitalOcean App Platform project">
+    	In the DigitalOcean dashboard, go to [**App Platform**](https://cloud.digitalocean.com/apps) > **Create App**. We can create a project directly from the container image.
+
+    	<Frame>
+    		![DigitalOcean App Platform project dashboard](/images/guides/digitalocean-3.png)
+    	</Frame>
+
+    	Make sure the details are correct, then click **Next**.
+
+    	<Frame>
+    		![DigitalOcean App Platform service dashboard](/images/guides/digitalocean-4.png)
+    	</Frame>
+
+    	Review and configure resource settings, then click **Create app**.
+
+    	<Frame>
+    		![DigitalOcean App Platform service dashboard](/images/guides/digitalocean-6.png)
+    	</Frame>
+    </Step>
+    <Step title="Visit your live application">
+    	🥳 Your app is now live! Once the app is created, you should see it in the App Platform dashboard with the public URL.
+
+    	<Frame>
+    		![DigitalOcean App Platform app dashboard](/images/guides/digitalocean-5.png)
+    	</Frame>
+    </Step>
+
+</Steps>

package/docs/guides/deployment/google-cloud-run.mdx

@@ -0,0 +1,197 @@
+---
+title: Deploy a Bun application on Google Cloud Run
+sidebarTitle: Deploy on Google Cloud Run
+mode: center
+---
+
+[Google Cloud Run](https://cloud.google.com/run) is a managed platform for deploying and scaling serverless applications. Google handles the infrastructure for you.
+
+In this guide, we will deploy a Bun HTTP server to Google Cloud Run using a `Dockerfile`.
+
+<Note>
+	Before continuing, make sure you have:
+
+    - A Bun application ready for deployment
+    - A [Google Cloud account](https://cloud.google.com/) with billing enabled
+    - [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) installed and configured
+
+</Note>
+
+---
+
+<Steps> 
+<Step title={<span>Initialize <code>gcloud</code> by select/creating a project</span>}>
+
+Make sure that you've initialized the Google Cloud CLI. This command logs you in, and prompts you to either select an existing project or create a new one.
+
+For more help with the Google Cloud CLI, see the [official documentation](https://docs.cloud.google.com/sdk/gcloud/reference/init).
+
+```bash terminal icon="terminal"
+gcloud init
+```
+
+```txt
+Welcome! This command will take you through the configuration of gcloud.
+
+You must sign in to continue. Would you like to sign in (Y/n)? Y
+You are signed in as [email@example.com].
+
+Pick cloud project to use:
+ [1] existing-bun-app-1234
+ [2] Enter a project ID
+ [3] Create a new project
+Please enter numeric choice or text value (must exactly match list item): 3
+
+Enter a Project ID. my-bun-app
+Your current project has been set to: [my-bun-app]
+
+The Google Cloud CLI is configured and ready to use!
+```
+
+</Step>
+<Step title="(Optional) Store your project info in environment variables">
+Set variables for your project ID and number so they're easier to reuse in the following steps.
+
+```bash terminal icon="terminal"
+PROJECT_ID=$(gcloud projects list --format='value(projectId)' --filter='name="my bun app"')
+PROJECT_NUMBER=$(gcloud projects list --format='value(projectNumber)' --filter='name="my bun app"')
+
+echo $PROJECT_ID $PROJECT_NUMBER
+```
+
+```txt
+my-bun-app-... [PROJECT_NUMBER]
+```
+
+</Step> 
+<Step title="Link a billing account">
+List your available billing accounts and link one to your project:
+
+```bash terminal icon="terminal"
+gcloud billing accounts list
+```
+
+```txt
+ACCOUNT_ID            NAME                OPEN  MASTER_ACCOUNT_ID
+[BILLING_ACCOUNT_ID]  My Billing Account  True
+```
+
+Link your billing account to your project. Replace `[BILLING_ACCOUNT_ID]` with the ID of your billing account.
+
+```bash terminal icon="terminal"
+gcloud billing projects link $PROJECT_ID --billing-account=[BILLING_ACCOUNT_ID]
+```
+
+```txt
+billingAccountName: billingAccounts/[BILLING_ACCOUNT_ID]
+billingEnabled: true
+name: projects/my-bun-app-.../billingInfo
+projectId: my-bun-app-...
+```
+
+</Step> 
+<Step title="Enable APIs and configure IAM roles"> 
+Activate the necessary services and grant Cloud Build permissions:
+
+```bash terminal icon="terminal"
+gcloud services enable run.googleapis.com cloudbuild.googleapis.com
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
+  --role=roles/run.builder
+```
+
+<Note>  
+These commands enable Cloud Run (`run.googleapis.com`) and Cloud Build (`cloudbuild.googleapis.com`), which are required for deploying from source. Cloud Run runs your containerized app, while Cloud Build handles building and packaging it.
+
+The IAM binding grants the Compute Engine service account (`$PROJECT_NUMBER-compute@developer.gserviceaccount.com`) permission to build and deploy images on your behalf.
+
+</Note>
+
+</Step>
+<Step title="Add a Dockerfile">
+Create a new `Dockerfile` in the root of your project. This file contains the instructions to initialize the container, copy your local project files into it, install dependencies, and start the application.
+
+```docker Dockerfile icon="docker"
+# Use the official Bun image to run the application
+FROM oven/bun:latest
+
+# Copy the package.json and bun.lock into the container
+COPY package.json bun.lock ./
+
+# Install the dependencies
+# Install the dependencies
+RUN bun install --production --frozen-lockfile
+
+# Copy the rest of the application into the container
+COPY . .
+
+# Run the application
+CMD ["bun", "index.ts"]
+```
+
+<Note>
+  Make sure that the start command corresponds to your application's entry point. This can also be `CMD ["bun", "run", "start"]` if you have a start script in your `package.json`.
+
+    This image installs dependencies and runs your app with Bun inside a container. If your app doesn't have dependencies, you can omit the `RUN bun install --production --frozen-lockfile` line.
+
+    This image installs dependencies and runs your app with Bun inside a container. If your app doesn't have dependencies, you can omit the `RUN bun install --production --frozen-lockfile` line.
+
+</Note>
+
+Create a new `.dockerignore` file in the root of your project. This file contains the files and directories that should be _excluded_ from the container image, such as `node_modules`. This makes your builds faster and smaller:
+
+```docker .dockerignore icon="Docker"
+node_modules
+Dockerfile*
+.dockerignore
+.git
+.gitignore
+README.md
+LICENSE
+.vscode
+.env
+# Any other files or directories you want to exclude
+```
+
+</Step>
+<Step title="Deploy your service"> 
+Make sure you're in the directory containing your `Dockerfile`, then deploy directly from your local source:
+
+<Note>
+  Update the `--region` flag to your preferred region. You can also omit this flag to get an interactive prompt to
+  select a region. Update the `--region` flag to your preferred region. You can also omit this flag to get an
+  interactive prompt to select a region.
+</Note>
+
+```bash terminal icon="terminal"
+gcloud run deploy my-bun-app --source . --region=us-west1 --allow-unauthenticated
+```
+
+```txt
+Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named
+[cloud-run-source-deploy] in region [us-west1] will be created.
+
+Do you want to continue (Y/n)? Y
+
+Building using Dockerfile and deploying container to Cloud Run service [my-bun-app] in project [my-bun-app-...] region [us-west1]
+✓ Building and deploying... Done.
+  ✓ Validating Service...
+  ✓ Uploading sources...
+  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds...].
+  ✓ Creating Revision...
+  ✓ Routing traffic...
+  ✓ Setting IAM Policy...
+Done.
+Service [my-bun-app] revision [my-bun-app-...] has been deployed and is serving 100 percent of traffic.
+Service URL: https://my-bun-app-....us-west1.run.app
+```
+
+</Step>
+<Step title="Visit your live application">
+
+🎉 Your Bun application is now live!
+
+Visit the Service URL (`https://my-bun-app-....us-west1.run.app`) to confirm everything works as expected.
+
+</Step>
+</Steps>

package/docs/guides/deployment/railway.mdx

@@ -0,0 +1,145 @@
+---
+title: 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.
+sidebarTitle: Deploy on Railway
+mode: center
+---
+
+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:
+
+<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>
+
+---
+
+**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
+
+<Steps>
+<Step title="Step 1">
+Ensure sure you have the Railway CLI installed.
+
+```bash terminal icon="terminal"
+bun install -g @railway/cli
+```
+
+</Step>
+<Step title="Step 2">
+Log into your Railway account.
+
+```bash terminal icon="terminal"
+railway login
+```
+
+</Step>
+<Step title="Step 3">
+After successfully authenticating, initialize a new project.
+
+```bash terminal icon="terminal"
+railway init
+```
+
+</Step>
+<Step title="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.</Note>
+
+```bash terminal icon="terminal"
+# Add PostgreSQL database. Make sure to add this first!
+railway add --database postgres
+
+# Add your application service.
+railway add --service bun-react-db --variables DATABASE_URL=\${{Postgres.DATABASE_URL}}
+```
+
+</Step>
+<Step title="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 terminal icon="terminal"
+# Deploy your application
+railway up
+
+# Generate public domain
+railway domain
+```
+
+</Step>
+</Steps>
+
+Your app is now live! Railway auto-deploys on every GitHub push.
+
+---
+
+## Method 2: Deploy via Dashboard
+
+<Steps>
+<Step title="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>
+<Step title="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.</Note>
+
+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>
+<Step title="Step 3">
+Generate a public domain
+
+1. Select your service
+2. Go to **"Settings"** tab
+3. Under **"Networking"**, click **"Generate Domain"**
+
+</Step>
+</Steps>
+
+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 railway.json icon="file-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/deployment/render.mdx

@@ -0,0 +1,82 @@
+---
+title: Deploy a Bun application on Render
+sidebarTitle: Deploy on Render
+mode: center
+---
+
+[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.
+
+<Steps>
+	<Step title="Step 1">
+		Create a new GitHub repo named `myapp`. Git clone it locally.
+
+    	```sh
+    	git clone git@github.com:my-github-username/myapp.git
+    	cd myapp
+    	```
+    	</Step>
+    	<Step title="Step 2">
+    	Add the Express library.
+
+    	```sh
+    	bun add express
+    	```
+
+    </Step>
+
+    <Step title="Step 3">
+    	Define a simple server with Express:
+
+    	```ts app.ts icon="/icons/typescript.svg"
+    	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}...`);
+    	});
+    	```
+    </Step>
+    <Step title="Step 4">
+
+    	Commit your changes and push to GitHub.
+
+    	```sh terminal icon="terminal"
+    	git add app.ts bun.lock package.json
+    	git commit -m "Create simple Express app"
+    	git push origin main
+    	```
+    </Step>
+    <Step title="Step 5">
+    	In your [Render Dashboard](https://dashboard.render.com/), click `New` > `Web Service` and connect your `myapp` repo.
+
+    </Step>
+    <Step title="Step 6">
+    	In the Render UI, provide the following values during web service creation:
+
+    	|                   |               |
+    	| ----------------- | ------------- |
+    	| **Runtime**       | `Node`        |
+    	| **Build Command** | `bun install` |
+    	| **Start Command** | `bun app.ts`  |
+
+    </Step>
+
+</Steps>
+
+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/deployment/vercel.mdx

@@ -0,0 +1,99 @@
+---
+title: Deploy a Bun application on Vercel
+sidebarTitle: Deploy on Vercel
+mode: center
+---
+
+import { ProductCard } from "/snippets/product-card.mdx";
+
+[Vercel](https://vercel.com/) is a cloud platform that lets you build, deploy, and scale your apps.
+
+<Warning>
+  The Bun runtime is in Beta; certain features (e.g., automatic source maps, byte-code caching, metrics on
+  `node:http/https`) are not yet supported.
+</Warning>
+
+<Note>
+  `Bun.serve` is currently not supported on Vercel Functions. Use Bun with frameworks supported by Vercel, like Next.js,
+  Express, Hono, or Nitro.
+</Note>
+
+---
+
+<Steps>
+	<Step title="Configure Bun in vercel.json">
+		To enable the Bun runtime for your Functions, add a `bunVersion` field in your `vercel.json` file:
+
+    	```json vercel.json icon="file-json"
+    	{
+    		"bunVersion": "1.x" // [!code ++]
+    	}
+    	```
+
+    	Vercel automatically detects this configuration and runs your application on Bun. The value has to be `"1.x"`, Vercel handles the minor version internally.
+
+    	For best results, match your local Bun version with the version used by Vercel. **Currently, Bun version `1.2.23` is supported**.
+    </Step>
+
+    <Step title="Next.js configuration">
+    	If you’re deploying a **Next.js** project (including ISR), update your `package.json` scripts to use the Bun runtime:
+
+    	```json package.json icon="file-json"
+    	{
+    		"scripts": {
+    			"dev": "bun --bun next dev", // [!code ++]
+    			"build": "bun --bun next build" // [!code ++]
+    		}
+    	}
+    	```
+
+    	<Note>
+    		The `--bun` flag runs the Next.js CLI under Bun. Bundling (via Turbopack or Webpack) remains unchanged, but all commands execute within the Bun runtime.
+    	</Note>
+
+    	This ensures both local development and builds use Bun.
+    </Step>
+
+    <Step title="Deploy your app">
+    	Connect your repository to Vercel, or deploy from the CLI:
+
+    	```bash terminal icon="terminal"
+    	# Using bunx (no global install)
+    	bunx vercel login
+    	bunx vercel deploy
+    	```
+
+    	Or install the Vercel CLI globally:
+
+    	```bash terminal icon="terminal"
+    	bun i -g vercel
+    	vercel login
+    	vercel deploy
+    	```
+
+    	[Learn more in the Vercel Deploy CLI documentation →](https://vercel.com/docs/cli/deploy)
+    </Step>
+
+    <Step title="Verify the runtime">
+    	To confirm your deployment uses Bun, log the Bun version:
+
+    	```ts index.ts icon="/icons/typescript.svg"
+    	console.log("runtime", process.versions.bun);
+    	```
+    	```txt
+    	runtime 1.2.23
+    	```
+
+    	[See the Vercel Bun Runtime documentation for feature support →](https://vercel.com/docs/functions/runtimes/bun#feature-support)
+    </Step>
+
+</Steps>
+
+---
+
+- [Fluid compute](https://vercel.com/docs/fluid-compute): Both Bun and Node.js runtimes run on Fluid compute and support the same core Vercel Functions features.
+- [Middleware](https://vercel.com/docs/routing-middleware): To run Routing Middleware with Bun, set the runtime to `nodejs`:
+
+```ts middleware.ts icon="/icons/typescript.svg"
+export const config = { runtime: "nodejs" }; // [!code ++]
+```