> ## Documentation Index
> Fetch the complete documentation index at: https://healthzkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# S3 adapter

> Use @healthzkit/s3 adapters for AWS SDK v2 and v3 S3 clients—ListBuckets probes, bucket count and latency metadata, client options, and Healthzkit readiness examples for Amazon S3.

The **`@healthzkit/s3`** package provides [`HealthAdapter`](/guide/checks-and-adapters) helpers for AWS SDK v2 **[`aws-sdk`](https://github.com/aws/aws-sdk-js)** and v3 **[`@aws-sdk/client-s3`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/)**. Successful checks call **`ListBuckets`** and return **`ok`** with `metadata.latencyMs`, `metadata.bucketCount`, plus any fields from an optional **`metadata`** hook; failures return **`fail`** with the caught error.

Install the adapter package and **one** AWS SDK:

```bash theme={null}
pnpm add @healthzkit/s3 healthzkit
# plus one of:
pnpm add aws-sdk
pnpm add @aws-sdk/client-s3
```

Both SDKs are optional peers—install only the one you use.

## Package entrypoints

* **`@healthzkit/s3`** - `s3V2Adapter`, `s3V3Adapter`, and their option types.
* **`@healthzkit/s3/v2`** - `s3V2Adapter` only.
* **`@healthzkit/s3/v3`** - `s3V3Adapter` only.

Use subpath imports when you want to avoid pulling the unused SDK into your bundle analysis path.

## Shared options

Both factories accept `BaseS3Options`:

| Option         | Description                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| **`metadata`** | Optional `(client) => Record<string, unknown>` (sync or async) merged into metadata with `latencyMs`. |

Pass either **`config`** or an existing **`client`** (not both). The shape depends on the adapter (see below).

## `s3V2Adapter` (`aws-sdk`)

**Peer:** `aws-sdk` >= 2.

Uses the v2 **`S3`** client and **`listBuckets()`**. Suitable for legacy services still on AWS SDK for JavaScript v2.

### Config

The adapter lazily imports **`aws-sdk`**, constructs **`new AWS.S3(config)`** once, and reuses it across checks.

```ts theme={null}
import { createHealthKit } from "healthzkit";
import { s3V2Adapter } from "@healthzkit/s3";

const kit = createHealthKit({
  checks: [
    {
      name: "s3",
      type: ["readiness"],
      adapter: s3V2Adapter({
        config: { region: process.env.AWS_REGION ?? "us-east-1" },
      }),
    },
  ],
});
```

### Existing client

```ts theme={null}
import AWS from "aws-sdk";
import { s3V2Adapter } from "@healthzkit/s3/v2";

const client = new AWS.S3({ region: "us-east-1" });

const adapter = s3V2Adapter({
  client,
  metadata: () => ({ sdk: "v2" }),
});
```

## `s3V3Adapter` (`@aws-sdk/client-s3`)

**Peer:** `@aws-sdk/client-s3` >= 3.

Uses **`S3Client`** and **`ListBucketsCommand`**. Prefer this for new code on AWS SDK for JavaScript v3.

### Config

The adapter lazily imports **`@aws-sdk/client-s3`**, constructs **`new S3Client(config)`** once, and reuses it across checks.

```ts theme={null}
import { s3V3Adapter } from "@healthzkit/s3/v3";

const adapter = s3V3Adapter({
  config: { region: process.env.AWS_REGION ?? "us-east-1" },
});
```

### Existing client

```ts theme={null}
import { S3Client } from "@aws-sdk/client-s3";
import { s3V3Adapter } from "@healthzkit/s3";

const client = new S3Client({ region: "us-east-1" });

const adapter = s3V3Adapter({
  client,
  metadata: async () => ({ sdk: "v3" }),
});
```

## Scheduling

For S3 buckets that should not be queried on every probe, pair these adapters with a **`schedule`** on the check so readiness reads cached results (see [Scheduling](/guide/scheduling)).