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

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";
import { DefaultAzureCredential } from "@azure/identity";

const files = new Files({
  adapter: azure({
    container: "uploads",
    // Auto-loads from AZURE_STORAGE_CONNECTION_STRING, or
    // AZURE_STORAGE_ACCOUNT_NAME + AZURE_STORAGE_ACCOUNT_KEY.
    // Pass connectionString / accountKey / credential / sasToken to override.
    // accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
    // credential: new DefaultAzureCredential(), // Azure AD / Managed Identity
  }),
});

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

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

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.

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

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.

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 mode mints a 5-min read SAS.
url ⚠️ Signs a SAS read URL. Shared-key mode uses the account key; TokenCredential mode uses User Delegation SAS. Throws in SAS-only or anonymous mode (no signer available). 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, 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?