Skip to main content
The @healthzkit/s3 package provides HealthAdapter helpers for AWS SDK v2 aws-sdk and v3 @aws-sdk/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:
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: 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.

Existing client

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.

Existing client

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).