# @storyshelf/storage-azure

> Store StoryShelf artifacts in Azure Blob Storage.

Source: https://storyshelf.js.org/packages/storage-azure/

`@storyshelf/storage-azure` stores StoryShelf blobs in an **Azure Blob Storage** container. It persists the same artifacts as the other storage adapters — captured screenshots, diff overlays, and uploaded Storybook archives.

## Install

```sh
npm i @storyshelf/storage-azure
```

[![JSR](https://jsr.io/badges/@storyshelf/storage-azure)](https://jsr.io/@storyshelf/storage-azure) [![JSR Score](https://jsr.io/badges/@storyshelf/storage-azure/score)](https://jsr.io/@storyshelf/storage-azure)

- [npm package](https://www.npmjs.com/package/@storyshelf/storage-azure) — install tarballs and version history.
- [JSR package](https://jsr.io/@storyshelf/storage-azure) — TypeScript-first registry page.
- [Public API reference](https://storyshelf.js.org/reference/storage-azure/) — generated docs for every export; start here to learn the API. (The same reference is on [JSR](https://jsr.io/@storyshelf/storage-azure/doc).)
- [Source on GitHub](https://github.com/GuptaSiddhant/storyshelf/tree/main/packages/storage-azure) — package directory on `main`.

## Configure

```ts
import { createAzureStorage } from "@storyshelf/storage-azure";
import { createShelfApp } from "@storyshelf/app";

// Via connection string (recommended for local / Azurite)
const storage = createAzureStorage({
  container: "storyshelf",
  prefix: "storyshelf", // optional
  connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
});

// Via account name + key
const storage2 = createAzureStorage({
  container: "storyshelf",
  accountName: "myaccount",
  accountKey: process.env.AZURE_STORAGE_KEY,
  accountUrl: "https://myaccount.blob.core.windows.net", // optional, derived from accountName if omitted
});

const app = createShelfApp({ database, storage });
```

Inject a pre-configured client (tests / custom credential rotation):

```ts
import { BlobServiceClient } from "@azure/storage-blob";

const service = BlobServiceClient.fromConnectionString(connStr);
const containerClient = service.getContainerClient("storyshelf");
const storage = createAzureStorage({ container: "storyshelf", client: containerClient });
```

Azurite (local emulator):

```ts
const storage = createAzureStorage({
  container: "storyshelf",
  connectionString:
    "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;",
});
```

### `AzureStorageOptions`

```ts
interface AzureStorageOptions {
  container: string; // required container name
  prefix?: string; // optional blob prefix, defaults to ""
  client?: ContainerClient; // optional pre-configured container client
  connectionString?: string; // optional Azure connection string
  accountName?: string; // optional storage account name
  accountKey?: string; // optional storage account key
  accountUrl?: string; // optional blob service URL (e.g. https://myaccount.blob.core.windows.net)
  sasToken?: string; // optional SAS token (without leading ? OK)
}
```

Options at a glance:

| Option                       | Required | Notes                                                  |
| ---------------------------- | -------- | ------------------------------------------------------ |
| `container`                  | yes      | Blob container name                                    |
| `prefix`                     | no       | Key prefix applied to every object                     |
| `client`                     | no       | Pre-built `ContainerClient`; skips client construction |
| `connectionString`           | no\*     | Storage connection string                              |
| `accountName` / `accountKey` | no\*     | Explicit credentials pair                              |
| `accountUrl` / `sasToken`    | no\*     | URL + SAS form (emulator, fine-grained SAS)            |

`*` At least one auth form is needed unless `client` is supplied.

### `createAzureStorage(options: AzureStorageOptions): StorageAdapter`

Creates a `StorageAdapter` backed by the configured Azure container. The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`, `readStream`, `writeStream`).

### `azureKey(prefix: string, path: string): string`

Helper that joins a storage prefix with a relative path into a blob name.

## When to use it

Choose Azure Blob Storage for Azure deploys — Container Apps, AKS, or Functions — especially paired with [db-postgres](../db-postgres/). It is a drop-in replacement for [local storage](../storage-local/) and [S3 storage](../storage-s3/); for Google Cloud see [storage-gcs](../storage-gcs/).