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

Azure Blob Storage

Azure Blob Storage via @azure/storage-blob. Five credential modes - connection string, account key, token credential, SAS token, or anonymous.

Installation

@azure/storage-blob is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @azure/storage-blob
pnpm add files-sdk @azure/storage-blob
yarn add files-sdk @azure/storage-blob
bun add files-sdk @azure/storage-blob
nub add files-sdk @azure/storage-blob
aube add files-sdk @azure/storage-blob

Usage

Azure Blob Storage via the official @azure/storage-blob SDK. Five credential modes: connection string, account name + account key, account name + token credential, account name + SAS token, or anonymous (public-read containers only). Connection-string parsing recovers the account name + key so signing methods keep working.

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

const files = new Files({
  adapter: azure({
    container: "uploads",
    // Auto-loads from AZURE_STORAGE_CONNECTION_STRING, or
    // AZURE_STORAGE_ACCOUNT_NAME + AZURE_STORAGE_ACCOUNT_KEY
    // (or AZURE_STORAGE_SAS_TOKEN). Passing any of connectionString /
    // accountKey / credential / sasToken turns the auth env vars off, and
    // env credentials for another account never apply to an explicit
    // accountName.
  }),
});

For Microsoft Entra ID (Azure AD / Managed Identity), install @azure/identity as well and pass a credential:

import { DefaultAzureCredential } from "@azure/identity";
import { Files } from "files-sdk";
import { azure } from "files-sdk/azure";

const files = new Files({
  adapter: azure({
    accountName: "mystorageaccount",
    container: "uploads",
    credential: new DefaultAzureCredential(),
  }),
});

Options

PropType
containerstring

Azure container name. Surfaced as `bucket` on the returned adapter for cross-adapter API consistency (S3/R2/GCS/MinIO all expose `bucket`). Azure's own term is "container".

Typestring
connectionString?string

Full connection string (`DefaultEndpointsProtocol=...;AccountName=...; AccountKey=...;EndpointSuffix=core.windows.net`). Highest precedence. Falls back to `AZURE_STORAGE_CONNECTION_STRING`, but only when none of `connectionString`, `accountKey`, `credential`, or `sasToken` is passed: explicit auth options always beat ambient environment variables. The env connection string is also skipped when it names a different account than an explicit `accountName`. The adapter parses out `AccountName` + `AccountKey` so `url()` and `signedUploadUrl()` can mint new SAS without a separate credential.

Typestring
accountName?string

Storage account name (e.g. `mystorageaccount`). Used with `accountKey`, `sasToken`, or anonymously. Falls back to `AZURE_STORAGE_ACCOUNT_NAME`, then `AZURE_STORAGE_ACCOUNT` (the Azure CLI uses both at different times).

Typestring
accountKey?string

Shared-key (account key). Required to sign URLs with shared-key credentials. Falls back to `AZURE_STORAGE_ACCOUNT_KEY`, then `AZURE_STORAGE_KEY`, when no explicit auth option is passed — and not when `AZURE_STORAGE_ACCOUNT_NAME` (or `AZURE_STORAGE_ACCOUNT`) names a different account than an explicit `accountName`.

Typestring
credential?TokenCredential

Microsoft Entra credential used for Azure AD / Managed Identity workloads. When supplied without a shared key, reads/writes/listing use token-based auth and `url()` / `signedUploadUrl()` mint User Delegation SAS URLs. A User Delegation SAS can live at most 7 days (the lifetime of the delegation key that signs it): a longer `expiresIn` throws, and `signedUrl.maxExpiresIn` / `signedUpload.maxExpiresIn` report the cap. The principal must be allowed to access blob data and call `Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action` (for example via Storage Blob Delegator at the account scope).

TypeTokenCredential
useUserDelegationSas?boolean

Controls whether `credential`-backed adapters mint User Delegation SAS URLs. Defaults to true when `credential` is supplied. Set false only when you want token-authenticated SDK operations but no signed URL support; `copy()` then authorizes its source with the credential's bearer token.

Typeboolean
sasToken?string

Pre-issued SAS token (with or without leading `?`). When set without `accountKey`, `url()` and `signedUploadUrl()` cannot mint new SAS — they throw an `Unsupported` error. Reading/writing/listing still works as long as the SAS has the relevant permissions. Falls back to `AZURE_STORAGE_SAS_TOKEN` when no explicit auth option is passed, with the same account-name pairing as `accountKey`.

Typestring
endpoint?string

Override the service endpoint host. Defaults to `https://${accountName}.blob.core.windows.net`. Used for Azurite (`http://127.0.0.1:10000/devstoreaccount1`) or sovereign clouds (`*.blob.core.usgovcloudapi.net`, `*.blob.core.chinacloudapi.cn`). Also wins over a connection string's endpoint when that connection string carries an account key or SAS.

Typestring
publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing — appropriate for a public container (`Blob` or `Container` access level) or a CDN (`*.azureedge.net`) in front of the account. Passing `expiresIn` or `responseContentDisposition` still mints a SAS.

Typestring
defaultUrlExpiresIn?number

Default expiry, in seconds, for the SAS read URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour). Per-call `url(key, { expiresIn })` overrides.

Typenumber

Limitations

Azure AD / Managed Identity is supported via the credential option (install @azure/identity); it authenticates SDK calls and mints User Delegation SAS URLs for url(), signedUploadUrl(), and copy(). The principal needs blob data access plus permission to call generateUserDelegationKey. A User Delegation SAS can’t outlive the 7-day delegation key that signs it, so an expiresIn above 7 days throws in this mode, and files.capabilities.signedUrl.maxExpiresIn reports the cap. With useUserDelegationSas: false, url() and signedUploadUrl() throw, and copy() authorizes its source with the credential’s bearer token instead.

Explicit auth options always win over environment variables: the AZURE_STORAGE_CONNECTION_STRING, AZURE_STORAGE_ACCOUNT_KEY, and AZURE_STORAGE_SAS_TOKEN fallbacks are read only when you pass none of connectionString, accountKey, credential, or sasToken. Env credentials also stay with their own account: with an explicit accountName, an AZURE_STORAGE_CONNECTION_STRING whose AccountName differs is ignored, and so are AZURE_STORAGE_ACCOUNT_KEY and AZURE_STORAGE_SAS_TOKEN when AZURE_STORAGE_ACCOUNT_NAME (or AZURE_STORAGE_ACCOUNT) names a different account. An explicit endpoint also wins over the endpoint in a connection string that carries an account key or SAS.

To develop against Azurite, point endpoint at it (http://127.0.0.1:10000/devstoreaccount1). @azure/storage-blob 12.34 and later send storage service version 2026-10-06, which is newer than the latest Azurite release (3.37.0) accepts, so start Azurite with --skipApiVersionCheck until it catches up.

Compatibility

Method Status Notes
upload ✅
download ✅
delete ✅
list ✅
search ✅
head ✅
exists ✅
copy ✅ Server-side copy via syncCopyFromURL. SAS-only adapter mode reuses the configured token; shared-key and User Delegation modes mint a 5-min read SAS; a credential with useUserDelegationSas: false sends its bearer token as the source authorization. A source over that API’s 256 MiB cap falls back to the asynchronous Copy Blob (beginCopyFromURL), authorized by the adapter’s own credentials, and copy() resolves once the copy finishes. An aborted signal stops the wait but not the copy, which still completes server-side.
url ⚠️ Signs a SAS read URL. Shared-key mode uses the account key; TokenCredential mode uses User Delegation SAS, capped at 7 days (a longer expiresIn throws). Throws in SAS-only or anonymous mode (no signer available), where signedUrl.supported is false. Pass accountKey + accountName, a connection string with an account key, credential + accountName, or set publicBaseUrl for a public container.
signedUploadUrl ⚠️ PUT URL only - Azure has no POST policy equivalent. maxSize throws because Azure SAS has no content-length-range policy, a positive minSize throws because SAS has no minimum-size constraint either (minSize: 0 is accepted), and contentType throws because Azure SAS does not bind Content-Type into the signature; enforce those checks at your application gateway instead. Shared-key mode uses the account key; TokenCredential mode uses User Delegation SAS. Throws in SAS-only or anonymous mode (no signer available). The returned headers include the required x-ms-blob-type: BlockBlob.

Last updated on

Was this page helpful?