@azure/storage-file-share (TypeScript/JavaScript)

SDK for Azure File Share operations — SMB file shares, directories, and file operations.

Installation

npm

install

@azure/storage-file-share @azure/identity

Current Version

12.x

Node.js

= 18.0.0 Environment Variables AZURE_STORAGE_ACCOUNT_NAME = < account-name

AZURE_STORAGE_ACCOUNT_KEY

< account-key

OR connection string

AZURE_STORAGE_CONNECTION_STRING

DefaultEndpointsProtocol

https ; AccountName = .. . Authentication Connection String (Simplest) import { ShareServiceClient } from "@azure/storage-file-share" ; const client = ShareServiceClient . fromConnectionString ( process . env . AZURE_STORAGE_CONNECTION_STRING ! ) ; StorageSharedKeyCredential (Node.js only) import { ShareServiceClient , StorageSharedKeyCredential } from "@azure/storage-file-share" ; const accountName = process . env . AZURE_STORAGE_ACCOUNT_NAME ! ; const accountKey = process . env . AZURE_STORAGE_ACCOUNT_KEY ! ; const sharedKeyCredential = new StorageSharedKeyCredential ( accountName , accountKey ) ; const client = new ShareServiceClient ( https:// ${ accountName } .file.core.windows.net , sharedKeyCredential ) ; DefaultAzureCredential import { ShareServiceClient } from "@azure/storage-file-share" ; import { DefaultAzureCredential } from "@azure/identity" ; const accountName = process . env . AZURE_STORAGE_ACCOUNT_NAME ! ; const client = new ShareServiceClient ( https:// ${ accountName } .file.core.windows.net , new DefaultAzureCredential ( ) ) ; SAS Token import { ShareServiceClient } from "@azure/storage-file-share" ; const accountName = process . env . AZURE_STORAGE_ACCOUNT_NAME ! ; const sasToken = process . env . AZURE_STORAGE_SAS_TOKEN ! ; const client = new ShareServiceClient ( https:// ${ accountName } .file.core.windows.net ${ sasToken } ) ; Client Hierarchy ShareServiceClient (account level) └── ShareClient (share level) └── ShareDirectoryClient (directory level) └── ShareFileClient (file level) Share Operations Create Share const shareClient = client . getShareClient ( "my-share" ) ; await shareClient . create ( ) ; // Create with quota (in GB) await shareClient . create ( { quota : 100 } ) ; List Shares for await ( const share of client . listShares ( ) ) { console . log ( share . name , share . properties . quota ) ; } // With prefix filter for await ( const share of client . listShares ( { prefix : "logs-" } ) ) { console . log ( share . name ) ; } Delete Share await shareClient . delete ( ) ; // Delete if exists await shareClient . deleteIfExists ( ) ; Get Share Properties const properties = await shareClient . getProperties ( ) ; console . log ( "Quota:" , properties . quota , "GB" ) ; console . log ( "Last Modified:" , properties . lastModified ) ; Set Share Quota await shareClient . setQuota ( 200 ) ; // 200 GB Directory Operations Create Directory const directoryClient = shareClient . getDirectoryClient ( "my-directory" ) ; await directoryClient . create ( ) ; // Create nested directory const nestedDir = shareClient . getDirectoryClient ( "parent/child/grandchild" ) ; await nestedDir . create ( ) ; List Directories and Files const directoryClient = shareClient . getDirectoryClient ( "my-directory" ) ; for await ( const item of directoryClient . listFilesAndDirectories ( ) ) { if ( item . kind === "directory" ) { console . log ( [DIR] ${ item . name } ) ; } else { console . log ( [FILE] ${ item . name } ( ${ item . properties . contentLength } bytes) ) ; } } Delete Directory await directoryClient . delete ( ) ; // Delete if exists await directoryClient . deleteIfExists ( ) ; Check if Directory Exists const exists = await directoryClient . exists ( ) ; if ( ! exists ) { await directoryClient . create ( ) ; } File Operations Upload File (Simple) const fileClient = shareClient . getDirectoryClient ( "my-directory" ) . getFileClient ( "my-file.txt" ) ; // Upload string const content = "Hello, World!" ; await fileClient . create ( content . length ) ; await fileClient . uploadRange ( content , 0 , content . length ) ; Upload File (Node.js - from local file) import * as fs from "fs" ; import * as path from "path" ; const fileClient = shareClient . rootDirectoryClient . getFileClient ( "uploaded.txt" ) ; const localFilePath = "/path/to/local/file.txt" ; const fileSize = fs . statSync ( localFilePath ) . size ; await fileClient . create ( fileSize ) ; await fileClient . uploadFile ( localFilePath ) ; Upload File (Buffer) const buffer = Buffer . from ( "Hello, Azure Files!" ) ; const fileClient = shareClient . rootDirectoryClient . getFileClient ( "buffer-file.txt" ) ; await fileClient . create ( buffer . length ) ; await fileClient . uploadRange ( buffer , 0 , buffer . length ) ; Upload File (Stream) import * as fs from "fs" ; const fileClient = shareClient . rootDirectoryClient . getFileClient ( "streamed.txt" ) ; const readStream = fs . createReadStream ( "/path/to/local/file.txt" ) ; const fileSize = fs . statSync ( "/path/to/local/file.txt" ) . size ; await fileClient . create ( fileSize ) ; await fileClient . uploadStream ( readStream , fileSize , 4 * 1024 * 1024 , 4 ) ; // 4MB buffer, 4 concurrency Download File const fileClient = shareClient . getDirectoryClient ( "my-directory" ) . getFileClient ( "my-file.txt" ) ; const downloadResponse = await fileClient . download ( ) ; // Read as string const chunks : Buffer [ ] = [ ] ; for await ( const chunk of downloadResponse . readableStreamBody ! ) { chunks . push ( Buffer . from ( chunk ) ) ; } const content = Buffer . concat ( chunks ) . toString ( "utf-8" ) ; Download to File (Node.js) const fileClient = shareClient . rootDirectoryClient . getFileClient ( "my-file.txt" ) ; await fileClient . downloadToFile ( "/path/to/local/destination.txt" ) ; Download to Buffer (Node.js) const fileClient = shareClient . rootDirectoryClient . getFileClient ( "my-file.txt" ) ; const buffer = await fileClient . downloadToBuffer ( ) ; console . log ( buffer . toString ( ) ) ; Delete File const fileClient = shareClient . rootDirectoryClient . getFileClient ( "my-file.txt" ) ; await fileClient . delete ( ) ; // Delete if exists await fileClient . deleteIfExists ( ) ; Copy File const sourceUrl = "https://account.file.core.windows.net/share/source.txt" ; const destFileClient = shareClient . rootDirectoryClient . getFileClient ( "destination.txt" ) ; // Start copy operation const copyPoller = await destFileClient . startCopyFromURL ( sourceUrl ) ; await copyPoller . pollUntilDone ( ) ; File Properties & Metadata Get File Properties const fileClient = shareClient . rootDirectoryClient . getFileClient ( "my-file.txt" ) ; const properties = await fileClient . getProperties ( ) ; console . log ( "Content-Length:" , properties . contentLength ) ; console . log ( "Content-Type:" , properties . contentType ) ; console . log ( "Last Modified:" , properties . lastModified ) ; console . log ( "ETag:" , properties . etag ) ; Set Metadata await fileClient . setMetadata ( { author : "John Doe" , category : "documents" , } ) ; Set HTTP Headers await fileClient . setHttpHeaders ( { fileContentType : "text/plain" , fileCacheControl : "max-age=3600" , fileContentDisposition : "attachment; filename=download.txt" , } ) ; Range Operations Upload Range const data = Buffer . from ( "partial content" ) ; await fileClient . uploadRange ( data , 100 , data . length ) ; // Write at offset 100 Download Range const downloadResponse = await fileClient . download ( 100 , 50 ) ; // offset 100, length 50 Clear Range await fileClient . clearRange ( 0 , 100 ) ; // Clear first 100 bytes Snapshot Operations Create Snapshot const snapshotResponse = await shareClient . createSnapshot ( ) ; console . log ( "Snapshot:" , snapshotResponse . snapshot ) ; Access Snapshot const snapshotShareClient = shareClient . withSnapshot ( snapshotResponse . snapshot ! ) ; const snapshotFileClient = snapshotShareClient . rootDirectoryClient . getFileClient ( "file.txt" ) ; const content = await snapshotFileClient . downloadToBuffer ( ) ; Delete Snapshot await shareClient . delete ( { deleteSnapshots : "include" } ) ; SAS Token Generation (Node.js only) Generate File SAS import { generateFileSASQueryParameters , FileSASPermissions , StorageSharedKeyCredential , } from "@azure/storage-file-share" ; const sharedKeyCredential = new StorageSharedKeyCredential ( accountName , accountKey ) ; const sasToken = generateFileSASQueryParameters ( { shareName : "my-share" , filePath : "my-directory/my-file.txt" , permissions : FileSASPermissions . parse ( "r" ) , // read only expiresOn : new Date ( Date . now ( ) + 3600 * 1000 ) , // 1 hour } , sharedKeyCredential ) . toString ( ) ; const sasUrl = https:// ${ accountName } .file.core.windows.net/my-share/my-directory/my-file.txt? ${ sasToken } ; Generate Share SAS import { ShareSASPermissions , generateFileSASQueryParameters } from "@azure/storage-file-share" ; const sasToken = generateFileSASQueryParameters ( { shareName : "my-share" , permissions : ShareSASPermissions . parse ( "rcwdl" ) , // read, create, write, delete, list expiresOn : new Date ( Date . now ( ) + 24 * 3600 * 1000 ) , // 24 hours } , sharedKeyCredential ) . toString ( ) ; Error Handling import { RestError } from "@azure/storage-file-share" ; try { await shareClient . create ( ) ; } catch ( error ) { if ( error instanceof RestError ) { switch ( error . statusCode ) { case 404 : console . log ( "Share not found" ) ; break ; case 409 : console . log ( "Share already exists" ) ; break ; case 403 : console . log ( "Access denied" ) ; break ; default : console . error ( Storage error ${ error . statusCode } : ${ error . message } ) ; } } throw error ; } TypeScript Types Reference import { // Clients ShareServiceClient , ShareClient , ShareDirectoryClient , ShareFileClient , // Authentication StorageSharedKeyCredential , AnonymousCredential , // SAS FileSASPermissions , ShareSASPermissions , AccountSASPermissions , AccountSASServices , AccountSASResourceTypes , generateFileSASQueryParameters , generateAccountSASQueryParameters , // Options & Responses ShareCreateResponse , FileDownloadResponseModel , DirectoryItem , FileItem , ShareProperties , FileProperties , // Errors RestError , } from "@azure/storage-file-share" ; Best Practices Use connection strings for simplicity — Easiest setup for development Use DefaultAzureCredential for production — Enable managed identity in Azure Set quotas on shares — Prevent unexpected storage costs Use streaming for large files — uploadStream / downloadToFile for files > 256MB Use ranges for partial updates — More efficient than full file replacement Create snapshots before major changes — Point-in-time recovery Handle errors gracefully — Check RestError.statusCode for specific handling Use *IfExists methods — For idempotent operations Platform Differences Feature Node.js Browser StorageSharedKeyCredential ✅ ❌ uploadFile() ✅ ❌ uploadStream() ✅ ❌ downloadToFile() ✅ ❌ downloadToBuffer() ✅ ❌ SAS generation ✅ ❌ DefaultAzureCredential ✅ ❌ Anonymous/SAS access ✅ ✅ When to Use This skill is applicable to execute the workflow or actions described in the overview.