Storage

Dirstarter uses Amazon S3 for file storage and media handling, providing a reliable and scalable solution for storing images, screenshots, and other media files.

Amazon S3

Amazon S3 is a cloud storage service that offers:

High availability and durability
Global distribution
Pay-per-use pricing
Built-in CDN integration
Fine-grained access control
Versioning and lifecycle management

Setup

Create an AWS account

Go to aws.amazon.com and create an account.

Create a new S3 bucket:

Navigate to the S3 service

Create a new bucket with the following options:

Pick globally unique bucket name (e.g., your-project-name)
Select a region close to your target audience
Disable "Block all public access" (very important if you want files to be publicly accessible)
Bucket versioning: Optional, enables version control for files

Click "Create bucket"

Add a bucket policy to allow public access. Go to the Permissions tab and add the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-project-name/*"
    }
  ]
}

Create an IAM user with S3 access:

Navigate to the IAM service

Create a new policy:

Select S3 as the service
Add permissions: GetObject, PutObject, DeleteObject, ListBucket
Limit the resources to your bucket: arn:aws:s3:::your-project-name/*

Example policy:

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

Create a new IAM user:

Select "Programmatic access"
Attach the policy you created

Save the Access Key ID and Secret Access Key

Add the following environment variables:

.env

S3_BUCKET=your-project-name
S3_REGION=your-region
S3_ACCESS_KEY=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_ENDPOINT=https://your-endpoint.com # Optional, for S3-compatible providers
S3_PUBLIC_URL=https://your-cdn.com # Optional, custom public URL for assets

S3-Compatible Alternatives

While Amazon S3 is our recommended choice, you can use any S3-compatible storage service. Here are some popular alternatives:

When using a non-AWS S3 provider, set the S3_ENDPOINT environment variable in your .env file to the correct endpoint URL. The S3 client in services/s3.ts uses this value automatically.

Media Handling

The boilerplate includes a comprehensive media handling system in lib/media.ts:

lib/media.ts

export async function uploadToS3Storage(file: Buffer, key: string) {
  // Auto-detects file type and appends extension
  // Uploads to S3 using multipart upload
  // Returns the public URL with cache-busting parameter
}

Server-side uploads

Form fields, the rich-text editor, favicons, and screenshots all upload through the Next.js server via lib/media.ts. The browser never writes directly to the bucket, so no CORS policy is required.

The public REST API does not accept file uploads. When creating or updating records via the API, provide publicly accessible URLs for faviconUrl and screenshotUrl.

Documentation