Tutorial: File Uploads | Bootspring Docs

Implement secure file uploads with image processing, storage, and delivery.

What You'll Build#

Presigned URL uploads to S3/R2
Image processing and optimization
File type validation
Progress tracking
CDN delivery

Prerequisites#

Next.js project
AWS S3 or Cloudflare R2 account
Bootspring initialized

Time Required#

Approximately 30 minutes.

Step 1: Set Up Storage#

Option A: AWS S3#

# .env.local
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
AWS_S3_BUCKET=my-app-uploads

Option B: Cloudflare R2#

# .env.local
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_R2_ACCESS_KEY_ID=...
CLOUDFLARE_R2_SECRET_ACCESS_KEY=...
CLOUDFLARE_R2_BUCKET=my-app-uploads
CLOUDFLARE_R2_PUBLIC_URL=https://uploads.yourdomain.com

Step 2: Apply Storage Skill#

bootspring skill apply storage/presigned-urls

Step 3: Install Dependencies#

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner sharp

Step 4: Create Storage Client#

// lib/storage.ts
import {
  S3Client,
  PutObjectCommand,
  GetObjectCommand,
  DeleteObjectCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const isR2 = !!process.env.CLOUDFLARE_ACCOUNT_ID;

const client = new S3Client(
  isR2
    ? {
        region: 'auto',
        endpoint: `https://${process.env.CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com`,
        credentials: {
          accessKeyId: process.env.CLOUDFLARE_R2_ACCESS_KEY_ID!,
          secretAccessKey: process.env.CLOUDFLARE_R2_SECRET_ACCESS_KEY!,
        },
      }
    : {
        region: process.env.AWS_REGION!,
        credentials: {
          accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        },
      }
);

const bucket = isR2
  ? process.env.CLOUDFLARE_R2_BUCKET!
  : process.env.AWS_S3_BUCKET!;

export async function getUploadUrl(
  key: string,
  contentType: string,
  expiresIn = 3600
) {
  const command = new PutObjectCommand({
    Bucket: bucket,
    Key: key,
    ContentType: contentType,
  });

  const url = await getSignedUrl(client, command, { expiresIn });

  return {
    uploadUrl: url,
    key,
    publicUrl: getPublicUrl(key),
  };
}

export async function deleteFile(key: string) {
  const command = new DeleteObjectCommand({
    Bucket: bucket,
    Key: key,
  });

  await client.send(command);
}

export function getPublicUrl(key: string): string {
  if (isR2) {
    return `${process.env.CLOUDFLARE_R2_PUBLIC_URL}/${key}`;
  }
  return `https://${bucket}.s3.${process.env.AWS_REGION}.amazonaws.com/${key}`;
}

// File validation
export const ALLOWED_IMAGE_TYPES = [
  'image/jpeg',
  'image/png',
  'image/gif',
  'image/webp',
];

export const ALLOWED_DOCUMENT_TYPES = [
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
];

export const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

export function validateFile(
  contentType: string,
  size: number,
  allowedTypes: string[]
) {
  if (!allowedTypes.includes(contentType)) {
    throw new Error(`Invalid file type: ${contentType}`);
  }

  if (size > MAX_FILE_SIZE) {
    throw new Error(`File too large: ${size} bytes (max: ${MAX_FILE_SIZE})`);
  }

  return true;
}

Step 5: Create Upload API#

// app/api/uploads/presign/route.ts
import { auth } from '@clerk/nextjs';
import { NextRequest, NextResponse } from 'next/server';
import { nanoid } from 'nanoid';
import {
  getUploadUrl,
  ALLOWED_IMAGE_TYPES,
  ALLOWED_DOCUMENT_TYPES,
  MAX_FILE_SIZE,
  validateFile,
} from '@/lib/storage';

export async function POST(request: NextRequest) {
  const { userId } = auth();

  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { filename, contentType, size, type = 'image' } = await request.json();

  // Validate input
  if (!filename || !contentType || !size) {
    return NextResponse.json(
      { error: 'Missing required fields' },
      { status: 400 }
    );
  }

  // Determine allowed types
  const allowedTypes =
    type === 'document' ? ALLOWED_DOCUMENT_TYPES : ALLOWED_IMAGE_TYPES;

  try {
    validateFile(contentType, size, allowedTypes);
  } catch (error) {
    return NextResponse.json(
      { error: (error as Error).message },
      { status: 400 }
    );
  }

  // Generate unique key
  const extension = filename.split('.').pop();
  const key = `uploads/${userId}/${type}s/${nanoid()}.${extension}`;

  try {
    const { uploadUrl, publicUrl } = await getUploadUrl(key, contentType);

    return NextResponse.json({
      uploadUrl,
      key,
      publicUrl,
    });
  } catch (error) {
    console.error('Failed to generate presigned URL:', error);
    return NextResponse.json(
      { error: 'Failed to generate upload URL' },
      { status: 500 }
    );
  }
}

Step 6: Create Upload Component#

// components/FileUpload.tsx
'use client';

import { useState, useCallback } from 'react';
import { Upload, X, Check, AlertCircle } from 'lucide-react';
import { cn } from '@/lib/utils';

interface FileUploadProps {
  onUpload: (url: string, key: string) => void;
  accept?: string;
  type?: 'image' | 'document';
  maxSize?: number;
  className?: string;
}

type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';

export function FileUpload({
  onUpload,
  accept = 'image/*',
  type = 'image',
  maxSize = 10 * 1024 * 1024,
  className,
}: FileUploadProps) {
  const [status, setStatus] = useState<UploadStatus>('idle');
  const [progress, setProgress] = useState(0);
  const [error, setError] = useState<string | null>(null);
  const [preview, setPreview] = useState<string | null>(null);

  const handleUpload = useCallback(
    async (file: File) => {
      // Validate file size
      if (file.size > maxSize) {
        setError(`File too large. Maximum size is ${maxSize / 1024 / 1024}MB`);
        setStatus('error');
        return;
      }

      setStatus('uploading');
      setProgress(0);
      setError(null);

      // Create preview for images
      if (type === 'image') {
        const reader = new FileReader();
        reader.onload = (e) => setPreview(e.target?.result as string);
        reader.readAsDataURL(file);
      }

      try {
        // Get presigned URL
        const presignResponse = await fetch('/api/uploads/presign', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            filename: file.name,
            contentType: file.type,
            size: file.size,
            type,
          }),
        });

        if (!presignResponse.ok) {
          const data = await presignResponse.json();
          throw new Error(data.error || 'Failed to get upload URL');
        }

        const { uploadUrl, key, publicUrl } = await presignResponse.json();

        // Upload to S3/R2 with progress
        await uploadWithProgress(uploadUrl, file, (progress) => {
          setProgress(progress);
        });

        setStatus('success');
        onUpload(publicUrl, key);
      } catch (err) {
        setError((err as Error).message);
        setStatus('error');
      }
    },
    [maxSize, type, onUpload]
  );

  const handleDrop = useCallback(
    (e: React.DragEvent) => {
      e.preventDefault();
      const file = e.dataTransfer.files[0];
      if (file) handleUpload(file);
    },
    [handleUpload]
  );

  const handleChange = useCallback(
    (e: React.ChangeEvent<HTMLInputElement>) => {
      const file = e.target.files?.[0];
      if (file) handleUpload(file);
    },
    [handleUpload]
  );

  return (
    <div className={cn('relative', className)}>
      <div
        onDrop={handleDrop}
        onDragOver={(e) => e.preventDefault()}
        className={cn(
          'border-2 border-dashed rounded-lg p-8 text-center transition-colors',
          status === 'idle' && 'border-gray-300 hover:border-gray-400',
          status === 'uploading' && 'border-blue-400 bg-blue-50',
          status === 'success' && 'border-green-400 bg-green-50',
          status === 'error' && 'border-red-400 bg-red-50'
        )}
      >
        {status === 'idle' && (
          <>
            <Upload className="mx-auto h-12 w-12 text-gray-400" />
            <p className="mt-4 text-sm text-gray-600">
              Drag and drop or{' '}
              <label className="text-blue-600 hover:text-blue-700 cursor-pointer">
                browse
                <input
                  type="file"
                  accept={accept}
                  onChange={handleChange}
                  className="hidden"
                />
              </label>
            </p>
            <p className="mt-2 text-xs text-gray-500">
              Max size: {maxSize / 1024 / 1024}MB
            </p>
          </>
        )}

        {status === 'uploading' && (
          <>
            {preview && type === 'image' && (
              <img
                src={preview}
                alt="Preview"
                className="mx-auto h-24 w-24 object-cover rounded-lg mb-4"
              />
            )}
            <div className="w-full bg-gray-200 rounded-full h-2">
              <div
                className="bg-blue-600 h-2 rounded-full transition-all duration-300"
                style={{ width: `${progress}%` }}
              />
            </div>
            <p className="mt-2 text-sm text-gray-600">
              Uploading... {progress}%
            </p>
          </>
        )}

        {status === 'success' && (
          <>
            {preview && type === 'image' && (
              <img
                src={preview}
                alt="Uploaded"
                className="mx-auto h-24 w-24 object-cover rounded-lg mb-4"
              />
            )}
            <Check className="mx-auto h-12 w-12 text-green-500" />
            <p className="mt-2 text-sm text-green-600">Upload complete!</p>
          </>
        )}

        {status === 'error' && (
          <>
            <AlertCircle className="mx-auto h-12 w-12 text-red-500" />
            <p className="mt-2 text-sm text-red-600">{error}</p>
            <button
              onClick={() => setStatus('idle')}
              className="mt-4 text-sm text-blue-600 hover:text-blue-700"
            >
              Try again
            </button>
          </>
        )}
      </div>
    </div>
  );
}

async function uploadWithProgress(
  url: string,
  file: File,
  onProgress: (progress: number) => void
): Promise<void> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();

    xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) {
        const progress = Math.round((e.loaded / e.total) * 100);
        onProgress(progress);
      }
    });

    xhr.addEventListener('load', () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        resolve();
      } else {
        reject(new Error(`Upload failed: ${xhr.statusText}`));
      }
    });

    xhr.addEventListener('error', () => {
      reject(new Error('Upload failed'));
    });

    xhr.open('PUT', url);
    xhr.setRequestHeader('Content-Type', file.type);
    xhr.send(file);
  });
}

Step 7: Add Image Processing#

// lib/image-processing.ts
import sharp from 'sharp';

export interface ProcessedImage {
  buffer: Buffer;
  width: number;
  height: number;
  format: string;
}

export async function processImage(
  input: Buffer,
  options: {
    width?: number;
    height?: number;
    format?: 'jpeg' | 'png' | 'webp';
    quality?: number;
  } = {}
): Promise<ProcessedImage> {
  const { width, height, format = 'webp', quality = 80 } = options;

  let pipeline = sharp(input);

  // Resize if dimensions provided
  if (width || height) {
    pipeline = pipeline.resize(width, height, {
      fit: 'inside',
      withoutEnlargement: true,
    });
  }

  // Convert format
  switch (format) {
    case 'jpeg':
      pipeline = pipeline.jpeg({ quality });
      break;
    case 'png':
      pipeline = pipeline.png({ quality });
      break;
    case 'webp':
      pipeline = pipeline.webp({ quality });
      break;
  }

  const buffer = await pipeline.toBuffer();
  const metadata = await sharp(buffer).metadata();

  return {
    buffer,
    width: metadata.width!,
    height: metadata.height!,
    format: metadata.format!,
  };
}

export async function generateThumbnail(
  input: Buffer,
  size: number = 200
): Promise<Buffer> {
  return sharp(input)
    .resize(size, size, {
      fit: 'cover',
      position: 'center',
    })
    .webp({ quality: 80 })
    .toBuffer();
}

export async function extractImageMetadata(input: Buffer) {
  const metadata = await sharp(input).metadata();

  return {
    width: metadata.width,
    height: metadata.height,
    format: metadata.format,
    size: input.length,
    hasAlpha: metadata.hasAlpha,
  };
}

Step 8: Create Avatar Upload Component#

// components/AvatarUpload.tsx
'use client';

import { useState } from 'react';
import { Camera } from 'lucide-react';
import Image from 'next/image';

interface AvatarUploadProps {
  currentAvatar?: string | null;
  onUpload: (url: string) => void;
}

export function AvatarUpload({ currentAvatar, onUpload }: AvatarUploadProps) {
  const [uploading, setUploading] = useState(false);
  const [preview, setPreview] = useState<string | null>(currentAvatar || null);

  const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Validate
    if (!file.type.startsWith('image/')) {
      alert('Please select an image file');
      return;
    }

    if (file.size > 5 * 1024 * 1024) {
      alert('Image must be less than 5MB');
      return;
    }

    // Preview
    const reader = new FileReader();
    reader.onload = (e) => setPreview(e.target?.result as string);
    reader.readAsDataURL(file);

    setUploading(true);

    try {
      // Get presigned URL
      const presignResponse = await fetch('/api/uploads/presign', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          filename: file.name,
          contentType: file.type,
          size: file.size,
          type: 'avatar',
        }),
      });

      const { uploadUrl, publicUrl } = await presignResponse.json();

      // Upload
      await fetch(uploadUrl, {
        method: 'PUT',
        body: file,
        headers: { 'Content-Type': file.type },
      });

      // Update profile
      await fetch('/api/user/profile', {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ avatarUrl: publicUrl }),
      });

      onUpload(publicUrl);
    } catch (error) {
      console.error('Upload failed:', error);
      setPreview(currentAvatar || null);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div className="relative inline-block">
      <div className="h-24 w-24 rounded-full overflow-hidden bg-gray-200">
        {preview ? (
          <Image
            src={preview}
            alt="Avatar"
            width={96}
            height={96}
            className="h-full w-full object-cover"
          />
        ) : (
          <div className="h-full w-full flex items-center justify-center text-gray-400">
            <Camera className="h-8 w-8" />
          </div>
        )}
      </div>

      <label
        className={`
          absolute bottom-0 right-0 h-8 w-8 rounded-full
          bg-blue-600 text-white flex items-center justify-center
          cursor-pointer hover:bg-blue-700 transition-colors
          ${uploading ? 'opacity-50 cursor-not-allowed' : ''}
        `}
      >
        <Camera className="h-4 w-4" />
        <input
          type="file"
          accept="image/*"
          onChange={handleChange}
          disabled={uploading}
          className="hidden"
        />
      </label>

      {uploading && (
        <div className="absolute inset-0 flex items-center justify-center bg-black/50 rounded-full">
          <div className="h-6 w-6 border-2 border-white border-t-transparent rounded-full animate-spin" />
        </div>
      )}
    </div>
  );
}

Step 9: Test Uploads#

Start development server:

npm run dev
Navigate to a page with the upload component
Test:
- File selection works
- Drag and drop works
- Progress updates correctly
- Success state shows
- Error handling works
- File appears in S3/R2

Verification Checklist#

Presigned URLs generate correctly
Upload progress tracks accurately
File validation works
Images display from CDN
Error states handled

What You Learned#

Presigned URL uploads
S3/R2 integration
File validation
Progress tracking
Image processing