@renatorodrigues/cacheiro-store-azure

Azure Blob Storage store for @renatorodrigues/cacheiro. Stores Nx cache artifacts in an Azure Blob Storage container.

Also available as a prebuilt Docker image: cacheiro-instants-azure, part of Cacheiro Instants.

Usage

import { AzureStore } from '@renatorodrigues/cacheiro-store-azure';

const store = new AzureStore({
  container: 'my-nx-cache',
  accountName: 'myazurestorageaccount',
});

await store.mount();

Config validation

This package exports a JSON Schema (draft-07) and a TypeScript type for the config shape. Use them to validate and cast a raw config object before constructing the store — the example below uses AJV, but any JSON Schema validator works:

import { configSchema, type AzureStoreConfig } from '@renatorodrigues/cacheiro-store-azure';
import { Ajv } from 'ajv';

const validate = new Ajv({ allErrors: true }).compile(configSchema);

// example — error handling is up to your runner
if (!validate(raw)) throw new Error('invalid store config');
const store = new AzureStore(raw as unknown as AzureStoreConfig);

Development

npm run watch        # tsc --watch (hot rebuild)
npm run build        # compile TypeScript
npm test             # vitest run
npm run test:watch
npm run lint
npm run fmt

Config

Field	Type	Required	Description
container	string	Yes	Azure Blob Storage container name.
accountName	string	No	Azure Storage account name. Used to construct the blob endpoint URL.
connectionString	string	No	Full Azure Blob Storage connection string. Overrides accountName if provided.
prefix	string	No	Key prefix for all cache entries. Useful when sharing a container across projects.
encryptionKey	string	No	Client-side AES-256-CBC encryption key. When set, artifacts are encrypted before upload.
encryptionScope	string	No	Azure encryption scope name. When set, blobs are written under this scope (typically backed by a customer-managed key in Key Vault). Reads are transparent.

See Environment variables reference for conventional env var names.

Authentication

Two mutually exclusive modes are supported:

Mode	Setup
Connection string	Set connectionString. Uses BlobServiceClient.fromConnectionString.
Default Azure Credential	Set accountName. The SDK chains env vars, managed identity, Azure CLI, etc.

When both are set, connectionString wins.

Encryption

Azure encrypts every blob at rest by default with Microsoft-managed keys — this baseline cannot be turned off. Two optional layers stack on top:

encryptionKey	encryptionScope	Behavior
unset	unset	Service-managed keys (or account-wide CMK if configured on the storage account).
unset	set	Server-side encryption uses the named scope's key (typically a Key Vault CMK).
set	unset	Client-side AES-256-CBC on top of service-managed encryption.
set	set	Client-side AES-256-CBC on top of scope-keyed server-side encryption.

encryptionScope is write-time only — Azure tracks which scope each blob was written with and decrypts transparently on read. Use scopes when one storage account holds artifacts under multiple keys (per tenant, per environment). For a single account-wide key, configure CMK on the storage account in the Azure portal and leave encryptionScope unset.

Client-side keys are stretched with scrypt (fixed salt, default cost) to a 32-byte AES key. The IV is randomly generated per write and prepended to the ciphertext: [16-byte IV][ciphertext]. This KDF differs from the deprecated official Nx Azure plugin (which used a different scheme), so containers encrypted with the upstream plugin are not interoperable.

Environment variables reference

Variable	Config field
AZURE_CONTAINER	container
AZURE_ACCOUNT_NAME	accountName
AZURE_STORAGE_CONNECTION_STRING	connectionString
AZURE_PREFIX	prefix
AZURE_ENCRYPTION_KEY	encryptionKey
AZURE_ENCRYPTION_SCOPE	encryptionScope