Yandex Object Storage

Yandex Object Storage via the S3-compatible API. Fixed global endpoint, region defaults to ru-central1.

Installation

@aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Usage

import { Files } from "files-sdk";
import { yandex } from "files-sdk/yandex";

const files = new Files({
  adapter: yandex({
    bucket: "uploads",
    // endpoint defaults to https://storage.yandexcloud.net
    // region defaults to "ru-central1"
    // accessKeyId / secretAccessKey auto-loaded from
    // YANDEX_ACCESS_KEY_ID / YANDEX_SECRET_ACCESS_KEY
  }),
});

Yandex Object Storage via its S3-compatible API. A thin wrapper around the S3 adapter - fixed global endpoint, region defaults to "ru-central1" for signing, virtual-hosted-style addressing, errors relabelled. Auto-loads from YANDEX_ACCESS_KEY_ID and YANDEX_SECRET_ACCESS_KEY. Generate static access keys in the Yandex Cloud console for a service account with the storage.editor role.

Options

PropType

bucketstring

Yandex Object Storage bucket name. The adapter scopes all operations to it.

Typestring

endpoint?string

Override the Yandex Object Storage endpoint. Defaults to `https://storage.yandexcloud.net` — Yandex serves a single global endpoint and routes internally. Override for a private deployment or proxy.

Typestring

accessKeyId?string

Static access key ID. Falls back to `YANDEX_ACCESS_KEY_ID`; required if that env var isn't set.

Typestring

secretAccessKey?string

Static secret access key. Falls back to `YANDEX_SECRET_ACCESS_KEY`; required if that env var isn't set.

Typestring

region?string

SigV4 region used for signing. Defaults to `"ru-central1"` — Yandex's only public region today. The value is required by the signature but doesn't drive routing (the endpoint is fixed). Leave the default unless you have a reason to change it.

Typestring

forcePathStyle?boolean

Use path-style addressing (`/<bucket>/<key>`) rather than virtual-hosted style. Defaults to `false` — virtual-hosted is canonical for Yandex Object Storage.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing. For public buckets the natural value is `https://${bucket}.storage.yandexcloud.net`; a custom domain bound to the bucket also works. When unset, `url()` falls back to a presigned GetObject (default expiry: 1 hour).

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the presigned URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour).

Typenumber

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅
`signedUploadUrl`	✅