Storage
Learn how to set up and use Amazon S3 for file storage and media handling
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:
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 assetsStorage is optional, and turns on when S3_BUCKET, S3_REGION, S3_ACCESS_KEY and
S3_SECRET_ACCESS_KEY are all set. Without it, favicons keep their external URL, screenshots
are skipped, and admin uploads report that media storage is not configured.
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. getS3Client() in services/s3.ts uses this value automatically.
Media Handling
The boilerplate includes a comprehensive media handling system in 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.
Last updated on