S3 Upload Handler

---
name: s3-upload-handler
description: Handle S3 file uploads including UI components, client-side logic, and server-side processing
tools: Read, Write, Edit
model: inherit
---

# S3 Upload Handler Skill

This skill provides methods to handle file uploads to AWS S3 using pre-built UI components, custom client-side logic, or server-side processing.

## Capabilities

1.  **UI Component**: Ready-to-use `S3Uploader` for drag-and-drop or button uploads.
2.  **Client SDK**: `ClientS3Uploader` class for custom upload interfaces.
3.  **Server Utilities**: `uploadFromServer` for backend file processing and uploading.

## Usage Patterns

### 1. Standard UI Component (Recommended)

Use the `S3Uploader` component for most user-facing upload needs.

```tsx
import { S3Uploader } from "@/components/ui/s3-uploader/s3-uploader";

// Usage in a form or page
<S3Uploader
  presignedRouteProvider="/api/app/your-upload-route" // API route to get signed URL
  variant="dropzone" // or "button"
  maxFiles={5}
  accept="image/*" // or specific extensions like ".pdf,.doc"
  onUpload={async (fileUrls) => {
    console.log("Files uploaded:", fileUrls);
    // Handle success (e.g., update form state)
  }}
/>
```

### 2. Custom Client-Side Upload

Use `ClientS3Uploader` when you need full control over the UI (e.g., hidden inputs, custom buttons).

```tsx
import { ClientS3Uploader } from "@/lib/s3/clientS3Uploader";

// Initialize
const uploader = new ClientS3Uploader({
  presignedRouteProvider: "/api/app/your-upload-route"
});

// Upload a file
const url = await uploader.uploadFile(fileObject);
```

### 3. Server-Side Upload

Use `uploadFromServer` in API routes or Server Actions for processing files (resizing, generating PDFs) before storage.

```typescript
import uploadFromServer from "@/lib/s3/uploadFromServer";

// In a server context (API route/Action)
const url = await uploadFromServer({
  file: base64String, // File content as base64
  path: "uploads/users/avatar.jpg", // Destination path in bucket
  contentType: "image/jpeg" // MIME type
});
```

## Environment Configuration

Ensure `.env.local` has the necessary AWS credentials:

```env
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"
AWS_REGION="us-east-1"
AWS_S3_BUCKET_NAME="your-bucket-name"
```

## API Route Example (for Presigned URLs)

You typically need an API route to generate presigned URLs for the client uploader.

```typescript
// src/app/api/app/upload-input-images/route.ts
import { createPresignedPost } from "@aws-sdk/s3-presigned-post";
import { S3Client } from "@aws-sdk/client-s3";
import { v4 as uuidv4 } from "uuid";

export async function POST(request: Request) {
  const { fileName, fileType } = await request.json();
  const client = new S3Client({ region: process.env.AWS_REGION });

  const { url, fields } = await createPresignedPost(client, {
    Bucket: process.env.AWS_S3_BUCKET_NAME!,
    Key: `uploads/${uuidv4()}-${fileName}`,
    Conditions: [
      ["content-length-range", 0, 10485760], // up to 10 MB
      ["starts-with", "$Content-Type", fileType],
    ],
    Fields: {
      acl: "public-read",
      "Content-Type": fileType,
    },
    Expires: 600, // Seconds before the presigned post expires. 3600 by default.
  });

  return Response.json({ url, fields });
}
```

Refer to [reference.md](reference.md) for more details.