Setup & Configuration

To use AWS S3 for file storage, you need to configure environment variables validated by @t3-oss/env-nextjs. The S3 client in lib/amazon/s3.ts handles all file operations.

Required Environment Variables

Plainform requires five S3-related environment variables:

AWS_ACCESS_KEY_ID="your-access-key-id"
AWS_SECRET_ACCESS_KEY="your-secret-access-key"
AWS_S3_ENDPOINT="https://your-bucket.s3.region.amazonaws.com"
AWS_S3_REGION="us-east-1"
AWS_S3_BUCKET="your-bucket-name"

These are validated in env.ts:

export const env = createEnv({
  server: {
    AWS_ACCESS_KEY_ID: z.string().min(5),
    AWS_SECRET_ACCESS_KEY: z.string().min(5),
    AWS_S3_ENDPOINT: z.string().min(5),
    AWS_S3_REGION: z.string().min(5),
    AWS_S3_BUCKET: z.string().min(5),
    // ... other variables
  },
});

Setup Steps

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

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

AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
AWS_S3_ENDPOINT="https://myapp-storage.s3.us-east-1.amazonaws.com"
AWS_S3_REGION="us-east-1"
AWS_S3_BUCKET="myapp-storage"

npm run dev

S3 Client Configuration

The S3 client is pre-configured in lib/amazon/s3.ts:

import { S3Client } from '@aws-sdk/client-s3';
import { env } from '@/env';

export const s3 = new S3Client({
  region: env.AWS_S3_REGION,
  credentials: {
    accessKeyId: env.AWS_ACCESS_KEY_ID,
    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
  },
});

No additional configuration needed - the client is ready to use.

CORS Configuration (Optional)

If uploading files from the browser, configure CORS on your S3 bucket:

1. Go to your bucket in AWS Console
2. Navigate to Permissions → CORS
3. Add CORS configuration:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["http://localhost:3000", "https://yourdomain.com"],
    "ExposeHeaders": ["ETag"]
  }
]

Security Best Practices

• Use IAM roles in production instead of access keys (for EC2, Lambda, etc.)
• Rotate access keys regularly (every 90 days recommended)
• Limit permissions to only what's needed (principle of least privilege)
• Enable bucket versioning to protect against accidental deletions
• Use signed URLs for temporary access instead of public buckets
• Monitor access with AWS CloudTrail and S3 access logs

Next Steps

• Usage & Integration - Upload and retrieve files
• Troubleshooting - Resolve common issues
• AWS S3 Getting Started - AWS documentation