Azure Storage File Share Ts

1---
2name: azure-storage-file-share-ts
3description: |
4  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".
5package: "@azure/storage-file-share"
6---
7 
8# @azure/storage-file-share (TypeScript/JavaScript)
9 
10SDK for Azure File Share operations — SMB file shares, directories, and file operations.
11 
12## Installation
13 
14```bash
15npm install @azure/storage-file-share @azure/identity
16```
17 
18**Current Version**: 12.x  
19**Node.js**: >= 18.0.0
20 
21## Environment Variables
22 
23```bash
24AZURE_STORAGE_ACCOUNT_NAME=<account-name>
25AZURE_STORAGE_ACCOUNT_KEY=<account-key>
26# OR connection string
27AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
28```
29 
30## Authentication
31 
32### Connection String (Simplest)
33 
34```typescript
35import { ShareServiceClient } from "@azure/storage-file-share";
36 
37const client = ShareServiceClient.fromConnectionString(
38  process.env.AZURE_STORAGE_CONNECTION_STRING!
39);
40```
41 
42### StorageSharedKeyCredential (Node.js only)
43 
44```typescript
45import { ShareServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-share";
46 
47const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
48const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY!;
49 
50const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
51const client = new ShareServiceClient(
52  `https://${accountName}.file.core.windows.net`,
53  sharedKeyCredential
54);
55```
56 
57### DefaultAzureCredential
58 
59```typescript
60import { ShareServiceClient } from "@azure/storage-file-share";
61import { DefaultAzureCredential } from "@azure/identity";
62 
63const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
64const client = new ShareServiceClient(
65  `https://${accountName}.file.core.windows.net`,
66  new DefaultAzureCredential()
67);
68```
69 
70### SAS Token
71 
72```typescript
73import { ShareServiceClient } from "@azure/storage-file-share";
74 
75const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
76const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN!;
77 
78const client = new ShareServiceClient(
79  `https://${accountName}.file.core.windows.net${sasToken}`
80);
81```
82 
83## Client Hierarchy
84 
85```
86ShareServiceClient (account level)
87└── ShareClient (share level)
88    └── ShareDirectoryClient (directory level)
89        └── ShareFileClient (file level)
90```
91 
92## Share Operations
93 
94### Create Share
95 
96```typescript
97const shareClient = client.getShareClient("my-share");
98await shareClient.create();
99 
100// Create with quota (in GB)
101await shareClient.create({ quota: 100 });
102```
103 
104### List Shares
105 
106```typescript
107for await (const share of client.listShares()) {
108  console.log(share.name, share.properties.quota);
109}
110 
111// With prefix filter
112for await (const share of client.listShares({ prefix: "logs-" })) {
113  console.log(share.name);
114}
115```
116 
117### Delete Share
118 
119```typescript
120await shareClient.delete();
121 
122// Delete if exists
123await shareClient.deleteIfExists();
124```
125 
126### Get Share Properties
127 
128```typescript
129const properties = await shareClient.getProperties();
130console.log("Quota:", properties.quota, "GB");
131console.log("Last Modified:", properties.lastModified);
132```
133 
134### Set Share Quota
135 
136```typescript
137await shareClient.setQuota(200); // 200 GB
138```
139 
140## Directory Operations
141 
142### Create Directory
143 
144```typescript
145const directoryClient = shareClient.getDirectoryClient("my-directory");
146await directoryClient.create();
147 
148// Create nested directory
149const nestedDir = shareClient.getDirectoryClient("parent/child/grandchild");
150await nestedDir.create();
151```
152 
153### List Directories and Files
154 
155```typescript
156const directoryClient = shareClient.getDirectoryClient("my-directory");
157 
158for await (const item of directoryClient.listFilesAndDirectories()) {
159  if (item.kind === "directory") {
160    console.log(`[DIR] ${item.name}`);
161  } else {
162    console.log(`[FILE] ${item.name} (${item.properties.contentLength} bytes)`);
163  }
164}
165```
166 
167### Delete Directory
168 
169```typescript
170await directoryClient.delete();
171 
172// Delete if exists
173await directoryClient.deleteIfExists();
174```
175 
176### Check if Directory Exists
177 
178```typescript
179const exists = await directoryClient.exists();
180if (!exists) {
181  await directoryClient.create();
182}
183```
184 
185## File Operations
186 
187### Upload File (Simple)
188 
189```typescript
190const fileClient = shareClient
191  .getDirectoryClient("my-directory")
192  .getFileClient("my-file.txt");
193 
194// Upload string
195const content = "Hello, World!";
196await fileClient.create(content.length);
197await fileClient.uploadRange(content, 0, content.length);
198```
199 
200### Upload File (Node.js - from local file)
201 
202```typescript
203import * as fs from "fs";
204import * as path from "path";
205 
206const fileClient = shareClient.rootDirectoryClient.getFileClient("uploaded.txt");
207const localFilePath = "/path/to/local/file.txt";
208const fileSize = fs.statSync(localFilePath).size;
209 
210await fileClient.create(fileSize);
211await fileClient.uploadFile(localFilePath);
212```
213 
214### Upload File (Buffer)
215 
216```typescript
217const buffer = Buffer.from("Hello, Azure Files!");
218const fileClient = shareClient.rootDirectoryClient.getFileClient("buffer-file.txt");
219 
220await fileClient.create(buffer.length);
221await fileClient.uploadRange(buffer, 0, buffer.length);
222```
223 
224### Upload File (Stream)
225 
226```typescript
227import * as fs from "fs";
228 
229const fileClient = shareClient.rootDirectoryClient.getFileClient("streamed.txt");
230const readStream = fs.createReadStream("/path/to/local/file.txt");
231const fileSize = fs.statSync("/path/to/local/file.txt").size;
232 
233await fileClient.create(fileSize);
234await fileClient.uploadStream(readStream, fileSize, 4 * 1024 * 1024, 4); // 4MB buffer, 4 concurrency
235```
236 
237### Download File
238 
239```typescript
240const fileClient = shareClient
241  .getDirectoryClient("my-directory")
242  .getFileClient("my-file.txt");
243 
244const downloadResponse = await fileClient.download();
245 
246// Read as string
247const chunks: Buffer[] = [];
248for await (const chunk of downloadResponse.readableStreamBody!) {
249  chunks.push(Buffer.from(chunk));
250}
251const content = Buffer.concat(chunks).toString("utf-8");
252```
253 
254### Download to File (Node.js)
255 
256```typescript
257const fileClient = shareClient.rootDirectoryClient.getFileClient("my-file.txt");
258await fileClient.downloadToFile("/path/to/local/destination.txt");
259```
260 
261### Download to Buffer (Node.js)
262 
263```typescript
264const fileClient = shareClient.rootDirectoryClient.getFileClient("my-file.txt");
265const buffer = await fileClient.downloadToBuffer();
266console.log(buffer.toString());
267```
268 
269### Delete File
270 
271```typescript
272const fileClient = shareClient.rootDirectoryClient.getFileClient("my-file.txt");
273await fileClient.delete();
274 
275// Delete if exists
276await fileClient.deleteIfExists();
277```
278 
279### Copy File
280 
281```typescript
282const sourceUrl = "https://account.file.core.windows.net/share/source.txt";
283const destFileClient = shareClient.rootDirectoryClient.getFileClient("destination.txt");
284 
285// Start copy operation
286const copyPoller = await destFileClient.startCopyFromURL(sourceUrl);
287await copyPoller.pollUntilDone();
288```
289 
290## File Properties & Metadata
291 
292### Get File Properties
293 
294```typescript
295const fileClient = shareClient.rootDirectoryClient.getFileClient("my-file.txt");
296const properties = await fileClient.getProperties();
297 
298console.log("Content-Length:", properties.contentLength);
299console.log("Content-Type:", properties.contentType);
300console.log("Last Modified:", properties.lastModified);
301console.log("ETag:", properties.etag);
302```
303 
304### Set Metadata
305 
306```typescript
307await fileClient.setMetadata({
308  author: "John Doe",
309  category: "documents",
310});
311```
312 
313### Set HTTP Headers
314 
315```typescript
316await fileClient.setHttpHeaders({
317  fileContentType: "text/plain",
318  fileCacheControl: "max-age=3600",
319  fileContentDisposition: "attachment; filename=download.txt",
320});
321```
322 
323## Range Operations
324 
325### Upload Range
326 
327```typescript
328const data = Buffer.from("partial content");
329await fileClient.uploadRange(data, 100, data.length); // Write at offset 100
330```
331 
332### Download Range
333 
334```typescript
335const downloadResponse = await fileClient.download(100, 50); // offset 100, length 50
336```
337 
338### Clear Range
339 
340```typescript
341await fileClient.clearRange(0, 100); // Clear first 100 bytes
342```
343 
344## Snapshot Operations
345 
346### Create Snapshot
347 
348```typescript
349const snapshotResponse = await shareClient.createSnapshot();
350console.log("Snapshot:", snapshotResponse.snapshot);
351```
352 
353### Access Snapshot
354 
355```typescript
356const snapshotShareClient = shareClient.withSnapshot(snapshotResponse.snapshot!);
357const snapshotFileClient = snapshotShareClient.rootDirectoryClient.getFileClient("file.txt");
358const content = await snapshotFileClient.downloadToBuffer();
359```
360 
361### Delete Snapshot
362 
363```typescript
364await shareClient.delete({ deleteSnapshots: "include" });
365```
366 
367## SAS Token Generation (Node.js only)
368 
369### Generate File SAS
370 
371```typescript
372import {
373  generateFileSASQueryParameters,
374  FileSASPermissions,
375  StorageSharedKeyCredential,
376} from "@azure/storage-file-share";
377 
378const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
379 
380const sasToken = generateFileSASQueryParameters(
381  {
382    shareName: "my-share",
383    filePath: "my-directory/my-file.txt",
384    permissions: FileSASPermissions.parse("r"), // read only
385    expiresOn: new Date(Date.now() + 3600 * 1000), // 1 hour
386  },
387  sharedKeyCredential
388).toString();
389 
390const sasUrl = `https://${accountName}.file.core.windows.net/my-share/my-directory/my-file.txt?${sasToken}`;
391```
392 
393### Generate Share SAS
394 
395```typescript
396import { ShareSASPermissions, generateFileSASQueryParameters } from "@azure/storage-file-share";
397 
398const sasToken = generateFileSASQueryParameters(
399  {
400    shareName: "my-share",
401    permissions: ShareSASPermissions.parse("rcwdl"), // read, create, write, delete, list
402    expiresOn: new Date(Date.now() + 24 * 3600 * 1000), // 24 hours
403  },
404  sharedKeyCredential
405).toString();
406```
407 
408## Error Handling
409 
410```typescript
411import { RestError } from "@azure/storage-file-share";
412 
413try {
414  await shareClient.create();
415} catch (error) {
416  if (error instanceof RestError) {
417    switch (error.statusCode) {
418      case 404:
419        console.log("Share not found");
420        break;
421      case 409:
422        console.log("Share already exists");
423        break;
424      case 403:
425        console.log("Access denied");
426        break;
427      default:
428        console.error(`Storage error ${error.statusCode}: ${error.message}`);
429    }
430  }
431  throw error;
432}
433```
434 
435## TypeScript Types Reference
436 
437```typescript
438import {
439  // Clients
440  ShareServiceClient,
441  ShareClient,
442  ShareDirectoryClient,
443  ShareFileClient,
444 
445  // Authentication
446  StorageSharedKeyCredential,
447  AnonymousCredential,
448 
449  // SAS
450  FileSASPermissions,
451  ShareSASPermissions,
452  AccountSASPermissions,
453  AccountSASServices,
454  AccountSASResourceTypes,
455  generateFileSASQueryParameters,
456  generateAccountSASQueryParameters,
457 
458  // Options & Responses
459  ShareCreateResponse,
460  FileDownloadResponseModel,
461  DirectoryItem,
462  FileItem,
463  ShareProperties,
464  FileProperties,
465 
466  // Errors
467  RestError,
468} from "@azure/storage-file-share";
469```
470 
471## Best Practices
472 
4731. **Use connection strings for simplicity** — Easiest setup for development
4742. **Use DefaultAzureCredential for production** — Enable managed identity in Azure
4753. **Set quotas on shares** — Prevent unexpected storage costs
4764. **Use streaming for large files** — `uploadStream`/`downloadToFile` for files > 256MB
4775. **Use ranges for partial updates** — More efficient than full file replacement
4786. **Create snapshots before major changes** — Point-in-time recovery
4797. **Handle errors gracefully** — Check `RestError.statusCode` for specific handling
4808. **Use `*IfExists` methods** — For idempotent operations
481 
482## Platform Differences
483 
484| Feature | Node.js | Browser |
485|---------|---------|---------|
486| `StorageSharedKeyCredential` | ✅ | ❌ |
487| `uploadFile()` | ✅ | ❌ |
488| `uploadStream()` | ✅ | ❌ |
489| `downloadToFile()` | ✅ | ❌ |
490| `downloadToBuffer()` | ✅ | ❌ |
491| SAS generation | ✅ | ❌ |
492| DefaultAzureCredential | ✅ | ❌ |
493| Anonymous/SAS access | ✅ | ✅ |
494