Skip to content

Services · Reference

S3 Service

An Effect service wrapping Bun's S3 client for object reads, writes, metadata, presigned URLs, listing, and deletion with typed service errors.

Last updated October 8, 2026

Overview

service-s3 provides an Effect service around Bun's built-in S3 client. It reads S3 configuration from environment variables, exposes a reusable S3Service.layer, and maps client failures into S3ServiceError values.

Install

shell
bunx shadcn@latest add @krak-stack/service-s3

Included Files

  • services/s3/index.ts - S3 config service, S3 client service, production layer, and test layer helper
  • services/s3/schema.ts - Typed S3ServiceError schema

Usage

ts
import { Effect } from "effect";
import { S3Service } from "@/services/s3";

const program = Effect.gen(function* () {
  const s3 = yield* S3Service;

  yield* s3.write("uploads/hello.txt", "Hello world", {
    type: "text/plain",
  });

  const text = yield* s3.text("uploads/hello.txt");
  const url = yield* s3.presign("uploads/hello.txt", { expiresIn: 60 });

  return { text, url };
});

const result = await Effect.runPromise(
  program.pipe(Effect.provide(S3Service.layer)),
);

Available Operations

  • file(path, options?) - Create a Bun S3File reference
  • write(path, data, options?) - Write object data
  • text(path), json(path), bytes(path), arrayBuffer(path), stream(path) - Read object data
  • exists(path), stat(path), size(path) - Read object metadata
  • delete(path) - Delete an object
  • presign(path, options?) - Create a presigned object URL
  • list(options?) - List bucket objects

Environment Variables

  • S3_ACCESS_KEY_ID - S3 access key ID
  • S3_SECRET_ACCESS_KEY - S3 secret access key
  • S3_BUCKET - S3 bucket name
  • S3_REGION - Optional S3 region
  • S3_ENDPOINT - Optional custom S3-compatible endpoint
  • S3_SESSION_TOKEN - Optional session token

This service uses Bun's S3Client, so it is intended for Bun runtimes or compatible S3-compatible deployments.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Dev Dependencies