How to Build Scalable AWS S3 Storage in 2026 (Next.js)

Introduction

In 2026, modern apps handle terabytes of user data: photos, videos, backups. AWS S3 remains the leader for its infinite scalability, 99.999999999% durability, and optimized costs. This advanced tutorial guides you through building a complete Cloud Storage system with Next.js App Router, including multipart uploads (for files >5GB), presigned URLs (secure access without exposing credentials), versioning, lifecycle policies, and CloudFront CDN integration.

Why it matters: Without this, your apps crash under heavy loads or expose vulnerabilities. We start from an empty project and build a production-ready service with file metadata in a database (Prisma + PostgreSQL). Think of S3 as an infinite ocean where your objects float, indexed by buckets. Result: a scalable REST API handling 10k req/s. Estimated time: 45 min.

Prerequisites

Node.js 20+ and npm/yarn
AWS account with IAM user (S3FullAccess policy)
Next.js 15+ and TypeScript
PostgreSQL database (Docker or Supabase)
Advanced knowledge: async/await, streams, AWS SDK v3

Initialize the Next.js Project

terminal

npx create-next-app@latest cloud-storage-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd cloud-storage-app
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @aws-sdk/lib-storage prisma @prisma/client
npx prisma init --datasource-provider postgresql
npm install -D @types/node

This command creates a Next.js 15 project with App Router, installs the modular AWS SDK v3 (client-s3 for operations, lib-storage for multipart, s3-request-presigner for secure URLs), and Prisma for file metadata. Avoid legacy SDK v2: v3 is 40% faster and tree-shakeable. Pitfall: Forget --app and you'll end up with the outdated Pages Router.

AWS and Prisma Configuration

Create an S3 bucket named mon-app-storage-2026 with versioning enabled and a public read policy (for CDN). Add a lifecycle rule: transition to Glacier after 30 days. Set up IAM: user with s3:PutObject, s3:GetObject, s3:DeleteObject permissions, and bucket CORS policy for POST, PUT, GET from your domain.

Prisma Schema and .env

prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model File {
  id        String   @id @default(cuid())
  key       String   @unique
  bucket    String
  size      Int
  mimeType  String
  metadata  Json?
  uploadedAt DateTime @default(now())
  versionId String?
  userId    String
  @@map("files")
}

This schema stores critical file metadata: key (S3 path), versionId for audits. Json for custom metadata (e.g., photo EXIF). @@map avoids PostgreSQL conflicts. Pitfall: Without size and mimeType, frontend downloads will fail. Run npx prisma db push afterward.

Centralized S3 Service

src/lib/s3.ts

import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { Readable } from 'stream';

const s3Client = new S3Client({
  region: process.env.AWS_REGION!,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

export async function uploadFile(key: string, body: Buffer | Readable, metadata: Record<string, string> = {}) {
  const command = new PutObjectCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
    Body: body,
    ContentType: metadata.mimeType,
    Metadata: metadata,
  });
  return s3Client.send(command);
}

export async function getPresignedUrl(key: string, expiresIn = 3600) {
  const command = new GetObjectCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
  });
  return getSignedUrl(s3Client, command, { expiresIn });
}

export async function deleteFile(key: string) {
  const command = new DeleteObjectCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
  });
  return s3Client.send(command);
}

export async function listFiles(prefix: string) {
  const command = new ListObjectsV2Command({
    Bucket: process.env.S3_BUCKET!,
    Prefix: prefix,
  });
  const { Contents } = await s3Client.send(command);
  return Contents || [];
}

Modular service using SDK v3: supports streams/Buffer for large files. Presigned URLs keep credentials off the frontend. No multipart here (covered next). Pitfall: Always specify ContentType or browsers will sniff MIME types, forcing downloads.

Multipart Uploads for Large Files

For files >100MB, single PUT requests fail (5GB limit but timeouts occur). Multipart breaks them into 5-100MB parts that can be uploaded in parallel and resumed.

Advanced Multipart Upload

src/lib/s3-multipart.ts

import { S3Client, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand, AbortMultipartUploadCommand } from '@aws-sdk/client-s3';
import { Upload } from '@aws-sdk/lib-storage';

const s3Client = new S3Client({ /* same as above */ });

export async function uploadMultipart(key: string, body: Readable, contentType: string, partSize = 10 * 1024 * 1024) {
  const upload = new Upload({
    client: s3Client,
    params: {
      Bucket: process.env.S3_BUCKET!,
      Key: key,
      Body: body,
      ContentType: contentType,
    },
    partSize,
  });

  upload.on('httpUploadProgress', (progress) => {
    console.log({ uploaded: progress.loaded, total: progress.total });
  });

  const result = await upload.done();
  return {
    Location: result.Location,
    ETag: result.ETag,
    VersionId: result.VersionId,
  };
}

export async function abortMultipart(uploadId: string, key: string) {
  const command = new AbortMultipartUploadCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
    UploadId: uploadId,
  });
  await s3Client.send(command);
}

@aws-sdk/lib-storage handles everything: init, parallel parts, complete/abort. 10MB partSize is optimal (min 5MB). Progress hooks for UI feedback. Pitfall: Without abort on failure, 'zombie uploads' rack up costs (billed per part).

API Route: Generate Presigned Upload URL

src/app/api/files/[key]/presign/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { z } from 'zod';

const s3Client = new S3Client({ /* credentials from env */ });

const schema = z.object({
  mimeType: z.string().mimeType(),
  size: z.number().max(5 * 1024 * 1024 * 1024),
});

export async function POST(req: NextRequest, { params }: { params: { key: string } }) {
  try {
    const { mimeType, size } = schema.parse(await req.json());
    const command = new PutObjectCommand({
      Bucket: process.env.S3_BUCKET!,
      Key: params.key,
      ContentType: mimeType,
    });
    const url = await getSignedUrl(s3Client, command, { expiresIn: 300 });
    // TODO: Save metadata to Prisma
    return NextResponse.json({ url, key: params.key });
  } catch (error) {
    return NextResponse.json({ error: 'Validation failed' }, { status: 400 });
  }
}

Dynamic route /api/files/[key]/presign: validates with Zod, generates 5-min PUT presigned URL. Frontend fetches it then PUTs directly to S3. Pitfall: Without Zod, MIME injection exploits are possible. Add Prisma logging here.

API Route: List and Download

src/app/api/files/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { listFiles, getPresignedUrl } from '@/lib/s3';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export async function GET(req: NextRequest) {
  const { searchParams } = new URL(req.url);
  const prefix = searchParams.get('prefix') || '';
  const files = await listFiles(prefix);
  const signedUrls = await Promise.all(
    files.slice(0, 100).map(async (file) => ({
      key: file.Key!,
      size: file.Size,
      url: await getPresignedUrl(file.Key!),
    }))
  );
  return NextResponse.json(signedUrls);
}

export async function DELETE(req: NextRequest) {
  const { key } = await req.json();
  await prisma.file.delete({ where: { key } });
  await deleteFile(key);
  return NextResponse.json({ success: true });
}

GET lists max 100 files (add cursor pagination next), generates signed GET URLs. DELETE syncs Prisma + S3. slice(0,100) prevents DoS. Pitfall: No pagination causes timeouts on full buckets (millions of objects).

CloudFront Integration and Testing

Create a CloudFront distribution on the bucket (use OAC for private access). Test with curl -X POST /api/files/test.jpg/presign -d '{"mimeType":"image/jpeg","size":1024}'. Frontend: useSWR for listing, fetch presign then XMLHttpRequest for PUT.

Best Practices

Always use presigned URLs: No frontend creds, GDPR compliant.
Multipart + Resume: Dynamic partSize (chunkSize = fileSize/10000, min 5MB).
Versioning + Lifecycle: Infinite audits, costs <0.01$/GB/month.
CloudWatch Monitoring: Alerts for >80% request throttling.
KMS Encryption: SSE-KMS for PCI/HIPAA compliance.

Common Errors to Avoid

Hardcoded credentials: Use SSM Parameter Store or Secrets Manager.
No size/MIME validation: Infinite upload DDoS.
Forgotten multipart abort: Surprise bills (0.01$/incomplete part).
List without prefix/pagination: Timeouts >29s on large buckets.

Next Steps

AWS S3 Docs: Developer Guide
Advanced: S3 Select for in-situ JSON/CSV queries.
Multi-cloud: MinIO for on-prem.

Check out our AWS and Cloud training courses.

How to Implement Scalable Cloud Storage with AWS S3 in 2026