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.
  }),
});

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

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` reports 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 a Provider 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.

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.

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. An explicit endpoint also wins over the endpoint in a connection string that carries an account key or SAS.

Compatibility

Method Status Notes
upload ✅
download ✅
delete ✅
list ✅
search ✅
head ✅
exists ✅
copy ⚠️ Server-side copy via syncCopyFromURL - capped at 256 MB source size. Larger blobs need beginCopyFromURL (poller); drop down to adapter.raw for that. 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.
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.

Was this page helpful?