@renatorodrigues/cacheiro-store-s3

S3 store for @renatorodrigues/cacheiro. Stores Nx cache artifacts in an AWS S3 bucket (or any S3-compatible storage: MinIO, LocalStack, DigitalOcean Spaces, Cloudflare R2).

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

Usage

import { S3Store } from '@renatorodrigues/cacheiro-store-s3';

const store = new S3Store({
  bucket: 'my-nx-cache',
  region: 'us-east-1',
});

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 S3StoreConfig } from '@renatorodrigues/cacheiro-store-s3';
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 S3Store(raw as unknown as S3StoreConfig);

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
bucket	string	Yes	S3 bucket name.
region	string	Yes	AWS region (e.g. us-east-1).
endpoint	string	No	Custom S3-compatible endpoint URL (MinIO, LocalStack, etc.).
accessKeyId	string	No	AWS access key ID. Falls back to the AWS credential chain (AWS_ACCESS_KEY_ID env var, AWS_PROFILE, IAM role, etc.) when omitted.
secretAccessKey	string	No	AWS secret access key. Falls back to the AWS credential chain (AWS_SECRET_ACCESS_KEY env var, IAM role, etc.) when omitted.
forcePathStyle	boolean	No	Use path-style URLs instead of virtual-hosted. Required for most S3-compatible storage. Default: false.
prefix	string	No	Key prefix for all cache entries. Useful when sharing a bucket across projects.
encryptionKey	string	No	Client-side AES-256-CBC encryption key. When set, artifacts are encrypted before upload.
ssoProfile	string	No	AWS SSO profile name. Falls back to the AWS_PROFILE env var when omitted.
disableChecksum	boolean	No	Disable AWS response checksum validation. Default: false.
serverSideEncryption	boolean	No	Enable S3 SSE-S3 (AES256) server-side encryption. Ignored when encryptionKey is set. Default: false.

See Environment variables reference for conventional env var names.

Encryption

Two mutually exclusive modes are supported:

encryptionKey	serverSideEncryption	Behavior
set	false	Client-side AES-256-CBC. Bytes encrypted locally before upload.
unset	true	S3 SSE-S3. AWS encrypts at rest with managed keys.
set	true	Warns and uses client-side only.
unset	false	No encryption (relies on bucket policies and TLS in transit).

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 S3 plugin (which truncated/repeated the key), so buckets encrypted with the upstream plugin are not interoperable.

Environment variables reference

Variable	Config field
S3_BUCKET	bucket
S3_REGION	region
S3_ENDPOINT	endpoint
AWS_ACCESS_KEY_ID	accessKeyId
AWS_SECRET_ACCESS_KEY	secretAccessKey
AWS_PROFILE	ssoProfile
S3_FORCE_PATH_STYLE	forcePathStyle
S3_PREFIX	prefix
S3_ENCRYPTION_KEY	encryptionKey
S3_DISABLE_CHECKSUM	disableChecksum
S3_SERVER_SIDE_ENCRYPTION	serverSideEncryption