Storage Configuration

Configure storage providers and environment variables.

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.

# 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:

# .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:

# .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:

// 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:

STORAGE_BASE_URL=https://cdn.example.com

For S3 bucket URL:

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:

Find Driver: First, find a Driver you want to use at Unstorage
Create a registry implementation

For example, we want to use Netlify Blob:

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:

STORAGE_PROVIDER=netlify-blob

And you can use the storage service as usual:

const storage = await getStorageService();

Note: This service returns an instance of the Unstorage API, so you can use the complete API reference there.

Next: Usage