Storage

Sonamu provides an integrated storage system for file uploads and storage. It supports local file system (fs) and AWS S3, and you can easily switch between them based on the environment.

Basic Structure

import path from "path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          /* ... */
        }),
        s3: drivers.s3({
          /* ... */
        }),
      },
    },
  },
  // ...
});

drivers

Defines the storage drivers to use. Two types are supported: "fs" (local file system) and "s3" (AWS S3). Type: Record<DriverKey, () => DriverContract> (DriverKey = "fs" | "s3")

import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          /* ... */
        }), // Local file system
        s3: drivers.s3({
          /* ... */
        }), // AWS S3
      },
    },
  },
});

When saving files, you explicitly specify which driver to use in the saveToDisk(diskName, key) call. To use different drivers per environment, branch at the code level using environment variables.

fs Driver

Stores files on the local file system. Suitable for development environments.

import path from "path";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          location: path.join(import.meta.dirname, "/../public/uploaded"),
          visibility: "public",
          urlBuilder: {
            generateURL(key) {
              return `/api/public/uploaded/${key}`;
            },
            generateSignedURL(key) {
              return `/api/public/uploaded/${key}`;
            },
          },
        }),
      },
    },
  },
});

location

The directory path where files will be stored. Type: string (required)

drivers.fs({
  location: path.join(import.meta.dirname, "/../public/uploaded"),
  // ...
});

Path example:

visibility

Sets the access permissions for files. Type: "public" | "private"

"public": Anyone can access via URL
"private": Only authenticated users can access

drivers.fs({
  location: path.join(import.meta.dirname, "/../public/uploaded"),
  visibility: "public", // Public files
  // ...
});

urlBuilder

Defines functions to generate file URLs.

drivers.fs({
  // ...
  urlBuilder: {
    // Generate regular URL
    generateURL(key) {
      return `/api/public/uploaded/${key}`;
    },

    // Generate signed URL (temporary access)
    generateSignedURL(key, expiresIn) {
      // In fs, usually same as regular URL
      return `/api/public/uploaded/${key}`;
    },
  },
});

generateURL: Generates the public URL for a file.

key: Unique key for the file (e.g., "profile-images/user-123.jpg")
Returns: Accessible URL

generateSignedURL: Generates a temporarily accessible signed URL.

key: Unique key for the file
expiresIn: Expiration time (seconds, optional)
Returns: Temporary URL

s3 Driver

Stores files on AWS S3. Suitable for production environments.

import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        s3: drivers.s3({
          credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
          },
          region: "ap-northeast-2",
          bucket: "my-app-uploads",
          visibility: "private",
        }),
      },
    },
  },
});

credentials

Sets AWS authentication credentials. Type: (required)

credentials: {
  accessKeyId: string;
  secretAccessKey: string;
}

drivers.s3({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
  },
  // ...
});

Always manage AWS credentials via environment variables. Never write them directly in code!

.env:

AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here

region

The AWS region where the S3 bucket is located. Type: string (required)

drivers.s3({
  // ...
  region: "ap-northeast-2", // Seoul region
});

Major regions:

ap-northeast-2 - Seoul
us-east-1 - N. Virginia
us-west-2 - Oregon
eu-west-1 - Ireland
ap-southeast-1 - Singapore

bucket

The S3 bucket name for storing files. Type: string (required)

drivers.s3({
  // ...
  bucket: "my-app-uploads",
});

Using different buckets per environment:

drivers.s3({
  // ...
  bucket: process.env.S3_BUCKET ?? "my-app-dev",
});

visibility

Sets the ACL (Access Control List) for S3 objects. Type: "public" | "private"

drivers.s3({
  // ...
  visibility: "private", // Authentication required
});

"public": Public read allowed (public-read ACL)
"private": Private (private ACL, default)

Practical Examples

Development Environment: fs Only

import path from "path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        fs: drivers.fs({
          location: path.join(import.meta.dirname, "/../public/uploaded"),
          visibility: "public",
          urlBuilder: {
            generateURL(key) {
              return `/api/public/uploaded/${key}`;
            },
            generateSignedURL(key) {
              return `/api/public/uploaded/${key}`;
            },
          },
        }),
      },
    },
  },
  // ...
});

fs + S3 (Environment-based Switching)

import path from "path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

export default defineConfig({
  server: {
    storage: {
      drivers: {
        // Development: Local file system
        fs: drivers.fs({
          location: path.join(import.meta.dirname, "/../public/uploaded"),
          visibility: "public",
          urlBuilder: {
            generateURL(key) {
              return `/api/public/uploaded/${key}`;
            },
            generateSignedURL(key) {
              return `/api/public/uploaded/${key}`;
            },
          },
        }),

        // Production: AWS S3
        s3: drivers.s3({
          credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
          },
          region: process.env.S3_REGION ?? "ap-northeast-2",
          bucket: process.env.S3_BUCKET ?? "my-app-prod",
          visibility: "private",
        }),
      },
    },
  },
  // ...
});

.env.development:

DRIVE_DISK=fs

.env.production:

DRIVE_DISK=s3
S3_REGION=ap-northeast-2
S3_BUCKET=my-app-prod-uploads
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here

DriverKey currently supports only "fs" and "s3". Multiple bucket configurations — such as separating public and private files into different buckets — are not supported at this time.

File Upload Usage

After storage configuration, you can upload files using the @upload decorator and BufferedFile.saveToDisk().

import { BaseModelClass, Sonamu, upload } from "sonamu";
import { type DriverKey } from "sonamu/storage";

export class FileModel extends BaseModelClass {
  @upload()
  static async upload() {
    const ctx = Sonamu.getContext();
    const file = ctx.bufferedFiles[0];
    if (!file) throw new Error("No uploaded file found.");

    // Select driver via environment variable
    const diskName: DriverKey = process.env.DRIVE_DISK === "s3" ? "s3" : "fs";
    const url = await file.saveToDisk(diskName, `uploads/${Date.now()}-${file.filename}`);

    return { url };
  }
}

→ File Upload Guide

S3 Bucket Setup

Before using S3, you need to create and configure a bucket in AWS Console.

1. Create Bucket

# Create bucket with AWS CLI
aws s3 mb s3://my-app-uploads --region ap-northeast-2

2. CORS Configuration

Configure CORS to allow direct uploads from frontend. S3 Console → Bucket → Permissions → CORS configuration:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["https://myapp.com"],
    "ExposeHeaders": ["ETag"]
  }
]

3. IAM Permissions

Sonamu needs appropriate IAM permissions to access S3. Minimum permissions policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:ListBucket"],
      "Resource": ["arn:aws:s3:::my-app-uploads", "arn:aws:s3:::my-app-uploads/*"]
    }
  ]
}

Cautions

1. Environment Variable Security

// ❌ Bad: Credentials written directly in code
drivers.s3({
  credentials: {
    accessKeyId: "AKIAXXXXXXXXXXXXXXXX",
    secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCY...",
  },
});

// ✅ Good: Use environment variables
drivers.s3({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
  },
});

2. Choosing visibility

// Public files (profile images, product images, etc.)
visibility: "public";

// Private files (personal documents, receipts, contracts, etc.)
visibility: "private";

3. File Path Design

// ✅ Good: Systematic path structure
const key = `users/${userId}/profile/${Date.now()}.jpg`;
const key = `documents/${year}/${month}/${documentId}.pdf`;

// ❌ Bad: Flat structure
const key = `${Date.now()}.jpg`;

Next Steps

After completing storage configuration:

file-upload - Implement file upload in API
cache - Cache settings
advanced-features/storage - Advanced storage features

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Basic Structure

drivers

fs Driver

location

visibility

urlBuilder

s3 Driver

credentials

region

bucket

visibility

Practical Examples

Development Environment: fs Only

fs + S3 (Environment-based Switching)

File Upload Usage

S3 Bucket Setup

1. Create Bucket

2. CORS Configuration

3. IAM Permissions

Cautions

1. Environment Variable Security

2. Choosing visibility

3. File Path Design

Next Steps

​Basic Structure

​drivers

​fs Driver

​location

​visibility

​urlBuilder

​s3 Driver

​credentials

​region

​bucket

​visibility

​Practical Examples

​Development Environment: fs Only

​fs + S3 (Environment-based Switching)

​File Upload Usage

​S3 Bucket Setup

​1. Create Bucket

​2. CORS Configuration

​3. IAM Permissions

​Cautions

​1. Environment Variable Security

​2. Choosing visibility

​3. File Path Design

​Next Steps

Basic Structure

drivers

fs Driver

location

visibility

urlBuilder

s3 Driver

credentials

region

bucket

visibility

Practical Examples

Development Environment: fs Only

fs + S3 (Environment-based Switching)

File Upload Usage

S3 Bucket Setup

1. Create Bucket

2. CORS Configuration

3. IAM Permissions

Cautions

1. Environment Variable Security

2. Choosing visibility

3. File Path Design

Next Steps