Azure Storage File Share TS

MicrosoftOfficialCreated by Microsoft

Skill
Tool integration
Cloud and DevOps
MIT
No issues found

From the author

Azure File Share JavaScript/TypeScript SDK (@azure/storage-file-share) for SMB file share operations. Use for creating shares, managing directories, uploading/downloading files, and handling file metadata. Supports Azure Files SMB protocol scenarios. Triggers: "file share", "@azure/storage-file-share", "ShareServiceClient", "ShareClient", "SMB", "Azure Files".

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The @azure/storage-file-share SDK provides a comprehensive interface for interacting with Azure Files. It enables developers to perform administrative tasks like creating and managing shares, as well as granular file operations including uploading, downloading, and metadata management. The library supports various authentication methods, including connection strings, shared keys, and Microsoft Entra ID (formerly Azure AD) via the @azure/identity package. It is designed for both Node.js and browser environments, though certain file system-dependent features are exclusive to Node.js.

What it does

Create, list, and delete Azure File Shares.
Manage directory structures within file shares.
Upload and download files using streams, buffers, or local file paths.
Handle file metadata, HTTP headers, and range-based operations.
Generate SAS tokens for secure, delegated access to resources.
Manage share snapshots for point-in-time recovery.

When to use it

When building applications that require persistent file storage on Azure.
When you need to programmatically manage file shares and directory hierarchies.
When implementing file upload/download features in a Node.js or browser-based application.
When you need to secure file access using Shared Access Signatures (SAS).

Advantages

Native TypeScript support with full type definitions.
Supports efficient streaming for large file transfers.
Flexible authentication options including Managed Identity for production security.
Comprehensive error handling via standard RestError classes.
Idempotent operation support with *IfExists methods.

Usage examples

“How do I create a new Azure file share using the SDK?”: The user receives a code snippet demonstrating the initialization of a ShareServiceClient followed by the creation of a share using shareClient.create().
“Show me how to upload a local file to Azure Files in Node.js.”: The user receives an example using fs.createReadStream and the uploadStream method to handle large file uploads efficiently.
“How can I list all files in a specific directory?”: The user receives a code example using the listFilesAndDirectories() async iterator on a ShareDirectoryClient.
“How do I generate a read-only SAS token for a file?”: The user receives a code snippet using generateFileSASQueryParameters with FileSASPermissions set to 'r'.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/azure-storage-file-share-ts/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip azure-storage-file-share-ts.zip -d .agents/skills

Documentation by Microsoft

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=...
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production

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
);

Microsoft Entra Token Credential

import { ShareServiceClient } from "@azure/storage-file-share";
import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const client = new ShareServiceClient(
  `https://${accountName}.file.core.windows.net`,
  credential
);

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)

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

await shareClient.delete();

// Delete if exists
await shareClient.deleteIfExists();

const properties = await shareClient.getProperties();
console.log("Quota:", properties.quota, "GB");
console.log("Last Modified:", properties.lastModified);

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}`;

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 local development; use ManagedIdentityCredential or WorkloadIdentityCredential for production
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	✅	✅

Files

ATTRIBUTION.mdAdded by AutoGineer1000 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md12.5 KiB

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills · .github/plugins/azure-sdk-typescript/skills/azure-storage-file-share-ts · commit 0696600

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download azure-storage-file-share-ts.zip