Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

OVHcloud Object Storage

OVHcloud Object Storage via the S3-compatible API. Endpoint derived from the region code.

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
nub add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
aube add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

upload also needs the optional @aws-sdk/lib-storage package when it uses onProgress, multipart, or a ReadableStream body of unknown length. It’s only loaded then.

Usage

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

const files = new Files({
  adapter: ovhcloud({
    bucket: "uploads",
    region: "gra", // or "sbg", "de", "uk", "waw", "sgp", "ap-southeast-syd"
    // accessKeyId / secretAccessKey auto-loaded from
    // OVH_ACCESS_KEY_ID / OVH_SECRET_ACCESS_KEY
  }),
});

OVHcloud Object Storage via its S3-compatible API. A thin wrapper around the S3 adapter - endpoint derived from the region code (gra, rbx, sbg, bhs, de, uk, waw, eu-west-par, sgp, ap-southeast-syd, …), virtual-hosted-style addressing, errors relabelled. The default host is https://s3.<region>.io.cloud.ovh.net, OVHcloud’s main S3 endpoint, which serves every storage class (Standard by default). To use the legacy https://s3.<region>.perf.cloud.ovh.net endpoint or the Swift-backed https://s3.<region>.cloud.ovh.net (some regions only), pass it as endpoint. Auto-loads from OVH_ACCESS_KEY_ID and OVH_SECRET_ACCESS_KEY. Generate S3 credentials in the OVHcloud Control Panel under Public Cloud -> Object Storage -> S3 users.

Options

PropType
bucketstring

OVHcloud bucket name. The adapter scopes all operations to it.

Typestring
regionstring

OVHcloud Object Storage region code, e.g. `"gra"` (Gravelines), `"rbx"` (Roubaix), `"sbg"` (Strasbourg), `"de"` (Frankfurt), `"uk"` (London), `"waw"` (Warsaw), `"eu-west-par"` (Paris), `"bhs"` (Beauharnois), `"sgp"` (Singapore), `"ap-southeast-syd"` (Sydney). Drives the endpoint host (`https://s3.<region>.io.cloud.ovh.net`); there's no env-var fallback. Doubles as the SigV4 region.

Typestring
endpoint?string

Override the OVHcloud endpoint. When unset, defaults to `https://s3.${region}.io.cloud.ovh.net`, OVHcloud's main S3 endpoint: it serves every storage class and stores new objects as Standard unless told otherwise. OVHcloud also keeps a legacy `https://s3.${region}.perf.cloud.ovh.net` endpoint (High Performance by default) and, in some regions, the Swift-backed `https://s3.${region}.cloud.ovh.net`; pass either here to use it. OVHcloud routes by Host header — the SDK prepends the bucket subdomain for virtual-hosted style.

Typestring
accessKeyId?string

Static credentials. Falls back to `OVH_ACCESS_KEY_ID`; required if that env var isn't set.

Typestring
secretAccessKey?string

Static credentials. Falls back to `OVH_SECRET_ACCESS_KEY`; required if that env var isn't set.

Typestring
forcePathStyle?boolean

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

Typeboolean
publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing. For public containers the natural value is `https://${bucket}.s3.${region}.io.cloud.ovh.net`; a custom CNAME fronting 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 ⚠️ The S3 list API returns no per-object Content-Type, so type is inferred from the key’s extension (application/octet-stream when unknown). Use head() for the stored value.
search ✅
head ✅
exists ✅
copy ✅
url ✅
signedUploadUrl ✅

Was this page helpful?