# Storage Overview

> File storage abstraction for local filesystem and S3-compatible storage.

*Canonical: https://makerkit.dev/docs/nextjs-drizzle/storage/overview*

---

The `@kit/storage` package provides a unified storage abstraction layer built on [unstorage](https://unstorage.unjs.io/). It offers a consistent API for file operations across different storage providers.

The checked-in runtime currently wires two providers: local filesystem storage for development and S3-compatible storage for production-style setups.

## Features

- Upload files with metadata (content type, cache control)
- Download files as Buffer
- Delete files and prefixes
- List files by prefix
- Generate public URLs
- Support for filesystem and S3-compatible providers

## Supported Providers

The kit supports the following providers:

- **Filesystem** - Local development (default)
- **S3** - AWS S3, or S3-compatible storage (R2, Blackblaze, etc.)

Unstorage supports a wide range of providers, you can find the complete list [here](https://unstorage.unjs.io/drivers).

## Quick Start

### Get Storage Instance

```typescript
import 'server-only';

import { getStorageService } from '@kit/storage';

const storage = await getStorageService();
```

### Upload a File

Upload through the storage service directly:

```typescript
import { getStorageService } from '@kit/storage';

const storage = await getStorageService();

await storage.setItemRaw('uploads/image.png', buffer);
```

### Download a File

To download a file, you can use the `downloadFile` helper function.

```typescript
import { getStorageService } from '@kit/storage';

const storage = await getStorageService();
const data = await storage.getItemRaw('uploads/image.png');
```

### Delete Files

To delete a file, you can use the `deleteFile` helper function.

```typescript
import { getStorageService } from '@kit/storage';

const storage = await getStorageService();

// Delete single file
await storage.removeItem('uploads/image.png');
```

## Topics

1. **[Configuration](./configuration)** - Environment variables and provider setup
2. **[Usage](./usage)** - Upload, download, delete operations
3. **[Providers](./providers)** - Set up filesystem or S3-compatible storage
4. **[Bucket Access](./bucket-access)** - Access control for storage buckets
5. **[API Reference](./api-reference)** - Types and function signatures

## Important Notes

- **Server-only** - Storage operations must run on the server
- **Provider selection** - Set `STORAGE_PROVIDER` environment variable
- **Development default** - Uses local filesystem (`./public/storage.dev`)
- **Production** - Configure a cloud provider

This storage system is part of the [Next.js Drizzle SaaS Kit](/drizzle).

---

**Next:** [Configuration](./configuration)