# Storage Configuration

> Configure storage providers and environment variables.

*Canonical: https://makerkit.dev/docs/tanstack-drizzle/storage/configuration*

---

The storage package uses environment variables to configure the storage provider and connection settings.

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `STORAGE_PROVIDER` | Provider name (`fs`, `s3`, `r2`, `azure`, `gcs`) | `fs` |
| `STORAGE_BASE_URL` | Base URL for public file access | Provider-specific |

## Provider Selection

Set the `STORAGE_PROVIDER` variable in your `.env` file. By default, we support `fs` for local development, or `s3` for AWS S3 or any S3-compatible provider.

```bash
# Local filesystem (development)
STORAGE_PROVIDER=fs

# AWS S3 (or any S3-compatible provider)
STORAGE_PROVIDER=s3
```

## Development Configuration

For local development, the filesystem driver is used by default:

```bash
# .env.local
STORAGE_PROVIDER=fs
STORAGE_BASE_URL=storage.dev
```

Files are stored in `./public/storage.dev` and accessible via HTTP at `/storage.dev/*`.

**Note:** The filesystem driver is only available in non-production environments (`NODE_ENV !== 'production'`).

## Production Configuration

For production, configure a cloud provider. Example for S3:

```bash
# .env.production
STORAGE_PROVIDER=s3
STORAGE_BASE_URL=https://my-bucket.s3.us-east-1.amazonaws.com

# AWS S3 or any S3-compatible provider credentials
STORAGE_S3_ACCESS_KEY_ID=your-access-key
STORAGE_S3_SECRET_ACCESS_KEY=your-secret-key
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=my-bucket
```

## Base URL Configuration

The `STORAGE_BASE_URL` is used to generate public URLs for uploaded files:

```typescript
// If STORAGE_BASE_URL=https://cdn.example.com
// And file key is: uploads/image.png
// Generated URL: https://cdn.example.com/uploads/image.png
```

For S3 with a custom domain or CDN:

```bash
STORAGE_BASE_URL=https://cdn.example.com
```

For S3 bucket URL:

```bash
STORAGE_BASE_URL=https://my-bucket.s3.us-east-1.amazonaws.com
```

## Registry Pattern

The package uses a registry pattern to manage providers. Providers are lazily loaded and cached.

Since we only create an S3-compatible provider (which should cover the vast majority of storage providers, such as R2, Blackblaze, S3, etc.), it's up to you to define another one should you need to. To do so, is's very easy:

1. **Find Driver**: First, find a Driver you want to use at [Unstorage](https://unstorage.unjs.io/drivers)
2. Create a registry implementation

For example, we want to use [Netlify Blob](https://unstorage.unjs.io/drivers/netlify):

```typescript {% title="packages/storage/src/registry.ts" %}
// Register a custom provider in the registry file
storageRegistry.register('netlify-blob', async () => {
  const { createStorage } = await import("unstorage");

  const { default: netlifyBlobsDriver } = 
    await import("unstorage/drivers/netlify-blobs");

  const storage = createStorage({
    driver: netlifyBlobsDriver({
      name: "blob-store-name",
    }),
  });
});
```

Then, you can set the `STORAGE_PROVIDER` environment variable to `netlify-blob`:
```bash
STORAGE_PROVIDER=netlify-blob
```

And you can use the storage service as usual:

```typescript
const storage = await getStorageService();
```

**Note:** This service returns an instance of the [Unstorage API](https://unstorage.unjs.io/guide), so you can use the complete API reference there.

---

**Next:** [Usage](./usage)