diff --git a/docs/api/s3.md b/docs/api/s3.md index 5db2210953..fe98908466 100644 --- a/docs/api/s3.md +++ b/docs/api/s3.md @@ -25,7 +25,7 @@ const url = metadata.presign({ await metadata.delete(); ``` -S3 is the [de facto standard](https://en.wikipedia.org/wiki/De_facto_standard) internet filesystem. You can use Bun's S3 API with S3-compatible storage services like: +S3 is the [de facto standard](https://en.wikipedia.org/wiki/De_facto_standard) internet filesystem. Bun's S3 API works with S3-compatible storage services like: - AWS S3 - Cloudflare R2 @@ -42,7 +42,7 @@ There are several ways to interact with Bun's S3 API. `Bun.s3` is equivalent to `new Bun.S3Client()`, relying on environment variables for credentials. -To explicitly set credentials, you can pass them to the `Bun.S3Client` constructor. +To explicitly set credentials, pass them to the `Bun.S3Client` constructor. ```ts import { S3Client } from "bun"; @@ -76,7 +76,7 @@ Like `Bun.file(path)`, the `S3Client`'s `file` method is synchronous. It does ze ### Reading files from S3 -If you've used the `fetch` API, you're familiar with the `Response` and `Blob` APIs. `S3File` extends `Blob`, so you can use the same methods on it as you would for a `Response` or a `Blob`. +If you've used the `fetch` API, you're familiar with the `Response` and `Blob` APIs. `S3File` extends `Blob`. The same methods that work on `Blob` also work on `S3File`. ```ts // Read an S3File as text @@ -231,7 +231,7 @@ const url = s3file.presign({ ### `new Response(S3File)` -To quickly redirect users to a presigned URL for an S3 file, you can pass an `S3File` instance to a `Response` object as the body. +To quickly redirect users to a presigned URL for an S3 file, pass an `S3File` instance to a `Response` object as the body. ```ts const response = new Response(s3file); @@ -258,6 +258,43 @@ Response (0 KB) { Bun's S3 implementation works with any S3-compatible storage service. Just specify the appropriate endpoint: +### Using Bun's S3Client with AWS S3 + +AWS S3 is the default. You can also pass a `region` option instead of an `endpoint` option for AWS S3. + +```ts +import { S3Client } from "bun"; + +// AWS S3 +const s3 = new S3Client({ + accessKeyId: "access-key", + secretAccessKey: "secret-key", + bucket: "my-bucket", + // endpoint: "https://s3.us-east-1.amazonaws.com", + // region: "us-east-1", +}); +``` + +### Using Bun's S3Client with Google Cloud Storage + +To use Bun's S3 client with [Google Cloud Storage](https://cloud.google.com/storage), set `endpoint` to `"https://storage.googleapis.com"` in the `S3Client` constructor. + +```ts +import { S3Client } from "bun"; + +// Google Cloud Storage +const gcs = new S3Client({ + accessKeyId: "access-key", + secretAccessKey: "secret-key", + bucket: "my-bucket", + endpoint: "https://storage.googleapis.com", +}); +``` + +### Using Bun's S3Client with Cloudflare R2 + +To use Bun's S3 client with [Cloudflare R2](https://developers.cloudflare.com/r2/), set `endpoint` to the R2 endpoint in the `S3Client` constructor. The R2 endpoint includes your account ID. + ```ts import { S3Client } from "bun"; @@ -268,20 +305,38 @@ const r2 = new S3Client({ bucket: "my-bucket", endpoint: "https://.r2.cloudflarestorage.com", }); +``` + +### Using Bun's S3Client with DigitalOcean Spaces + +To use Bun's S3 client with [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces/), set `endpoint` to the DigitalOcean Spaces endpoint in the `S3Client` constructor. + +```ts +import { S3Client } from "bun"; -// DigitalOcean Spaces const spaces = new S3Client({ accessKeyId: "access-key", secretAccessKey: "secret-key", bucket: "my-bucket", + // region: "nyc3", endpoint: "https://.digitaloceanspaces.com", }); +``` + +### Using Bun's S3Client with MinIO + +To use Bun's S3 client with [MinIO](https://min.io/), set `endpoint` to the URL that MinIO is running on in the `S3Client` constructor. + +```ts +import { S3Client } from "bun"; -// MinIO const minio = new S3Client({ accessKeyId: "access-key", secretAccessKey: "secret-key", bucket: "my-bucket", + + // Make sure to use the correct endpoint URL + // It might not be localhost in production! endpoint: "http://localhost:9000", }); ``` @@ -346,7 +401,7 @@ await file.delete(); ### `S3Client.prototype.write` -You can call `.write` on the `S3Client` instance to write a file to S3. +To upload or write a file to S3, call `write` on the `S3Client` instance. ```ts const client = new Bun.S3Client({ @@ -364,7 +419,7 @@ await client.write("my-file.txt", new Response("Hello World!")); ### `S3Client.prototype.delete` -To delete a file from S3, you can use the `delete` method. +To delete a file from S3, call `delete` on the `S3Client` instance. ```ts const client = new Bun.S3Client({ @@ -380,7 +435,7 @@ await client.delete("my-file.txt"); ### `S3Client.prototype.exists` -To check if a file exists in S3, you can use the `exists` method. +To check if a file exists in S3, call `exists` on the `S3Client` instance. ```ts const client = new Bun.S3Client({