| title | Upload a blob with JavaScript or TypeScript |
|---|---|
| titleSuffix | Azure Storage |
| description | Learn how to upload a blob to your Azure Storage account using the JavaScript client library. |
| services | storage |
| author | stevenmatthew |
| ms.author | shaas |
| ms.date | 03/25/2025 |
| ms.service | azure-blob-storage |
| ms.topic | how-to |
| ms.devlang | javascript |
| ms.custom | devx-track-js, devguide-js, devx-track-ts, devguide-ts |
[!INCLUDE storage-dev-guide-selector-upload]
This article shows how to upload a blob using the Azure Storage client library for JavaScript. You can upload data to a block blob from a file path, a stream, a buffer, or a text string. You can also upload blobs with index tags.
- The examples in this article assume you already have a project set up to work with the Azure Blob Storage client library for JavaScript. To learn about setting up your project, including package installation, importing modules, and creating an authorized client object to work with data resources, see Get started with Azure Blob Storage and JavaScript.
- The authorization mechanism must have permissions to perform an upload operation. To learn more, see the authorization guidance for the following REST API operations:
You can use any of the following methods to upload data to a block blob:
- upload (non-parallel uploading method)
- uploadData
- uploadFile (only available in Node.js runtime)
- uploadStream (only available in Node.js runtime)
Each of these methods can be called using a BlockBlobClient object.
Note
The Azure Storage client libraries don't support concurrent writes to the same blob. If your app requires multiple processes writing to the same blob, you should implement a strategy for concurrency control to provide a predictable experience. To learn more about concurrency strategies, see Manage concurrency in Blob Storage.
The following example uploads a block blob from a local file path:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-local-file-path.js" id="Snippet_UploadBlob":::
:::code language="typescript" source="~/azure-storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-from-local-file-path.ts" id="Snippet_UploadBlob" :::
The following example uploads a block blob by creating a readable stream and uploading the stream:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-stream.js" id="Snippet_UploadBlob":::
:::code language="typescript" source="~/azure-storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-from-stream.ts" id="Snippet_UploadBlob" :::
The following example uploads a block blob from a Node.js buffer:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-buffer.js" id="Snippet_UploadBlob":::
:::code language="typescript" source="~/azure_storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-from-buffer.ts" id="Snippet_UploadBlob" :::
The following example uploads a block blob from a string:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-string.js" id="Snippet_UploadBlob":::
:::code language="typescript" source="~/azure_storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-from-string.ts" id="Snippet_UploadBlob" :::
You can define client library configuration options when uploading a blob. These options can be tuned to improve performance, enhance reliability, and optimize costs. The code examples in this section show how to set configuration options using the BlockBlobParallelUploadOptions interface, and how to pass those options as a parameter to an upload method call.
You can configure properties in BlockBlobParallelUploadOptions to improve performance for data transfer operations. The following table lists the properties you can configure, along with a description:
| Property | Description |
|---|---|
blockSize |
The maximum block size to transfer for each request as part of an upload operation. |
concurrency |
The maximum number of parallel requests that are issued at any given time as a part of a single parallel transfer. |
maxSingleShotSize |
If the size of the data is less than or equal to this value, it's uploaded in a single put rather than broken up into chunks. If the data is uploaded in a single shot, the block size is ignored. Default value is 256 MiB. |
The following code example shows how to set values for BlockBlobParallelUploadOptions and include the options as part of an upload method call. The values provided in the samples aren't intended to be a recommendation. To properly tune these values, you need to consider the specific needs of your app.
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-with-transfer-options.js" id="Snippet_UploadBlobTransferOptions":::
:::code language="typescript" source="~/azure_storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-with-transfer-options.ts" id="Snippet_UploadBlobTransferOptions":::
To learn more about tuning data transfer options, see Performance tuning for uploads and downloads with JavaScript.
Blob index tags categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data.
The following example uploads a block blob with index tags set using BlockBlobParallelUploadOptions:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-with-index-tags.js" id="Snippet_UploadBlobIndexTags":::
:::code language="typescript" source="~/azure_storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-with-index-tags.ts" id="Snippet_UploadBlobIndexTags":::
You can set a blob's access tier on upload by using the BlockBlobParallelUploadOptions interface. The following code example shows how to set the access tier when uploading a blob:
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-with-access-tier.js" id="Snippet_UploadAccessTier":::
:::code language="typescript" source="~/azure_storage-snippets/blobs/howto/TypeScript/NodeJS-v12/dev-guide/src/blob-upload-with-access-tier.ts" id="Snippet_UploadAccessTier":::
Setting the access tier is only allowed for block blobs. You can set the access tier for a block blob to Hot, Cool, Cold, or Archive. To set the access tier to Cold, you must use a minimum client library version of 12.13.0.
To learn more about access tiers, see Access tiers overview.
To learn more about uploading blobs using the Azure Blob Storage client library for JavaScript, see the following resources.
The Azure SDK for JavaScript contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar JavaScript paradigms. The client library methods for uploading blobs use the following REST API operations:
View code samples from this article (GitHub):
- Upload from local file path for JavaScript or TypeScript
- Upload from buffer for JavaScript or TypeScript
- Upload from stream for JavaScript or TypeScript
- Upload from string for JavaScript or TypeScript
- Upload with transfer options for JavaScript or TypeScript
- Upload with index tags for JavaScript or TypeScript
- Upload with access tier for JavaScript or TypeScript
[!INCLUDE storage-dev-guide-resources-javascript]
- Manage and find Azure Blob data with blob index tags
- Use blob index tags to manage and find data on Azure Blob Storage
[!INCLUDE storage-dev-guide-next-steps-javascript]