@nathapp/nestjs-storage

A unified storage abstraction for NestJS applications supporting multiple cloud providers and local storage.

Supported Providers

• Local Storage (FileSystem)
• AWS S3 (and compatible services)
• Aliyun OSS
• Google Drive
• Dropbox
• Azure Blob Storage (New)
• Google Cloud Storage (GCS) (New)
• NFS (Network File System)

Installation

npm install @nathapp/nestjs-storage

For specific providers, install the peer dependencies:

# Azure Blob Storage
npm install @azure/storage-blob

# Google Cloud Storage
npm install @google-cloud/storage

# AWS S3
npm install aws-sdk

# Aliyun OSS
npm install ali-oss

# Google Drive
npm install googleapis

Configuration

Azure Blob Storage

import { Module } from '@nestjs/common';
import { StorageModule, Provider } from '@nathapp/nestjs-storage';

@Module({
  imports: [
    StorageModule.forRoot({
      default: 'azure',
      disks: {
        azure: {
          provider: Provider.AZURE_BLOB,
          options: {
            connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
            containerName: 'my-container',
          },
        },
      },
    }),
  ],
})
export class AppModule {}

Google Cloud Storage (GCS)

import { Module } from '@nestjs/common';
import { StorageModule, Provider } from '@nathapp/nestjs-storage';

@Module({
  imports: [
    StorageModule.forRoot({
      default: 'gcs',
      disks: {
        gcs: {
          provider: Provider.GCS,
          options: {
            bucketName: 'my-bucket',
            projectId: 'my-project-id',
            keyFilename: 'path/to/keyfile.json',
          },
        },
      },
    }),
  ],
})
export class AppModule {}

S3 Compatible Providers

You can use the S3 provider to connect to any S3-compatible storage service by configuring the endpoint.

| Provider | Endpoint Pattern | Notes | |----------|-----------------|-------| | MinIO | http://minio:9000 | Self-hosted, set s3ForcePathStyle: true | | DigitalOcean Spaces | https://{region}.digitaloceanspaces.com | Region: nyc3, sfo3, etc. | | Backblaze B2 | https://s3.{region}.backblazeb2.com | Region: us-west-002, etc. | | Wasabi | https://s3.{region}.wasabisys.com | No egress fees | | Tencent COS | https://cos.{region}.myqcloud.com | Region: ap-guangzhou, etc. | | Supabase Storage | https://{project}.supabase.co/storage/v1/s3 | Needs S3 protocol enabled | | Cloudflare R2 | https://{accountid}.r2.cloudflarestorage.com | Use Provider.R2 or S3 |

Provider Capability Matrix

Which provider supports which methods:

| Capability | Local | S3 | OSS | GDrive | Azure | GCS | |---|---|---|---|---|---|---| | readFile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | writeFile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | deleteFile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | getSignedUrl | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | | clientUpload | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | | preprocessImage | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |

Breaking Changes in 3.0.0

• Standardized Async: All providers now use async/await and return standard Promises.
• Capability Checks: Optional methods (preprocessImage, getClientUploadCredential) are removed from BaseStorage abstract class. Use capability interfaces (ISignedUrlCapable, IStreamCapable, etc.) to check for support.

import { BaseStorage } from '@nathapp/nestjs-storage';

if (BaseStorage.supportsSignedUrl(storage)) {
  const url = await storage.getSignedUrl('file.jpg');
}