Upload a blob with JavaScript or TypeScript

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.

Prerequisites

• 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:
  • Put Blob
  • Put Block

Upload data to a block blob

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.

Upload a block blob from a file path

The following example uploads a block blob from a local file path:

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadBlobFromLocalPath(containerClient, blobName, localFilePath){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

TypeScript

async function uploadBlobFromLocalPath(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

Upload a block blob from a stream

The following example uploads a block blob by creating a readable stream and uploading the stream:

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// readableStream: Readable stream, for example, a stream returned from fs.createReadStream()
async function uploadBlobFromReadStream(containerClient, blobName, readableStream) {
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload data to block blob using a readable stream
  await blockBlobClient.uploadStream(readableStream);
}

TypeScript

async function uploadBlobFromReadStream(
  containerClient: ContainerClient,
  blobName: string,
  readStream: fs.ReadStream
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadStream(readStream);
}

Upload a block blob from a buffer

The following example uploads a block blob from a Node.js buffer:

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// buffer: blob contents as a buffer, for example, from fs.readFile()
async function uploadBlobFromBuffer(containerClient, blobName, buffer) {

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

TypeScript

async function uploadBlobFromBuffer(
  containerClient: ContainerClient, blobName: string, buffer: Buffer
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

Upload a block blob from a string

The following example uploads a block blob from a string:

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// fileContentsAsString: blob content
async function uploadBlobFromString(containerClient, blobName, fileContentsAsString){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length);
}

TypeScript

async function uploadBlobFromString(
  containerClient: ContainerClient,
  blobName: string,
  fileContents: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContents, fileContents.length);
}

Upload a block blob with configuration options

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.

Specify data transfer options on upload

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.

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithTransferOptions(containerClient, blobName, localFilePath) {
  
  // Specify data transfer options
  const uploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  } 

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with transfer options
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

TypeScript

async function uploadWithTransferOptions(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify data transfer options
  const uploadOptions: BlockBlobParallelUploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

To learn more about tuning data transfer options, see Performance tuning for uploads and downloads with JavaScript.

Upload a block blob with index tags

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:

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithIndexTags(containerClient, blobName, localFilePath) {
  
  // Specify index tags for blob
  const uploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

TypeScript

async function uploadBlobWithIndexTags(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify index tags for blob
  const uploadOptions: BlockBlobParallelUploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Set a blob's access tier on upload

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:

JavaScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithAccessTier(containerClient, blobName, localFilePath) {
  
  // Specify access tier
  const uploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool',
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob to cool tier
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

TypeScript

async function uploadBlobWithAccessTier(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {

  // Upload blob to 'Cool' access tier
  const uploadOptions: BlockBlobParallelUploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool'
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

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.

Resources

To learn more about uploading blobs using the Azure Blob Storage client library for JavaScript, see the following resources.

REST API operations

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:

• Put Blob (REST API)
• Put Block (REST API)

Code samples

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

Client library resources

• Client library reference documentation
• Client library source code
• Package (npm)

See also

• Manage and find Azure Blob data with blob index tags
• Use blob index tags to manage and find data on Azure Blob Storage

Related content

• This article is part of the Blob Storage developer guide for JavaScript/TypeScript. To learn more, see the full list of developer guide articles at Build your JavaScript/TypeScript app.