@fozooni/nestjs-storage

A powerful, driver-based storage module for NestJS with a unified API across 9 cloud drivers and 10 composable decorator disks.

Read the full documentation →

Highlights

• Unified API — One interface (FilesystemContract) for Local, S3, R2, GCS, Azure, MinIO, B2, DigitalOcean Spaces, and Wasabi
• Decorator Stack — Encryption, caching, retries, replication, quotas, versioning, CDN, OpenTelemetry tracing, content-aware routing, and path scoping — all composable at runtime
• NestJS Native — forRoot() / forRootAsync(), @InjectDisk(), interceptors, pipes, health checks, audit logging
• 845+ Tests — 45 test suites, tested on Node 18, 20, 22

Install

npm install @fozooni/nestjs-storage
# or
pnpm add @fozooni/nestjs-storage

Install only the driver SDK(s) you need:

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner  # S3/R2/MinIO/B2/DO/Wasabi
npm install @google-cloud/storage                               # GCS
npm install @azure/storage-blob                                 # Azure

Quick Start

import { Module } from '@nestjs/common';
import { StorageModule } from '@fozooni/nestjs-storage';

@Module({
  imports: [
    StorageModule.forRoot({
      default: 'local',
      disks: {
        local: { driver: 'local', root: './storage' },
        s3: { driver: 's3', bucket: 'my-bucket', region: 'us-east-1', key: '...', secret: '...' },
      },
    }),
  ],
})
export class AppModule {}

import { Injectable } from '@nestjs/common';
import { StorageService } from '@fozooni/nestjs-storage';

@Injectable()
export class FilesService {
  constructor(private storage: StorageService) {}

  async uploadFile(path: string, content: Buffer) {
    await this.storage.put(path, content, { visibility: 'public' });
    return this.storage.url(path);
  }

  async downloadFile(path: string) {
    return this.storage.get(path);
  }
}

Documentation

Full documentation with deep examples for every feature:

https://fozooni.github.io/nestjs-storage/

• Getting Started
• All 9 Drivers
• 10 Decorator Disks
• Services & Advanced Topics
• API Reference

AI / LLM Documentation

This package ships with purpose-built reference files for AI coding tools:

File	Description	Best for
llm.md	Compact quick-reference	Day-to-day coding with Cursor, Copilot
llm-full.md	Complete API surface	Architecture decisions, full context

Usage with AI tools:

• Cursor — Add to .cursorrules or @-mention in chat
• Claude Code — Reference in CLAUDE.md or add as project docs
• Antigravity / Others — Add as context documentation

See the LLM Documentation Guide for detailed setup instructions.

Compatibility

@fozooni/nestjs-storage	NestJS	Node.js
0.x	10 | 11	18, 20, 22

Support

If you find this package useful, please consider giving it a star on GitHub. It helps others discover it and motivates further development!

Contributing

Contributions are welcome! Please see the existing code patterns and ensure all tests pass before submitting a PR.

pnpm install
pnpm test
pnpm lint
pnpm build

License

MIT © Fozooni