Next.js 파일 업로드의 최적 솔루션, UploadThing의 모든 것

2025-01-12 21:27:16

uploaduploadthingnextjsjavascript

UploadThing: Next.js에 최적화된 파일 업로드 솔루션

UploadThing은 Next.js 개발자들이 파일 업로드를 더욱 안전하고 효율적으로 처리할 수 있도록 돕는 오픈 소스 솔루션입니다. 타입 안전성과 파일 검증, 변환 등의 기능을 제공하며, 인기 있는 프레임워크와의 직접적인 통합을 지원합니다.

UploadThing의 기술적 개요

UploadThing은 크게 세 가지 주요 구성 요소로 나뉩니다:

서버 사이드 파일 라우터
클라이언트 사이드 구성 요소와 훅
타입 안전 API 엔드포인트

서버 사이드 파일 라우터

UploadThing의 서버 구성은 createUploadthing을 통해 이루어집니다. 이 헬퍼를 사용해 파일 업로드를 위한 엔드포인트를 생성할 수 있습니다. 예를 들어, app/api/uploadthing/core.ts에 파일 라우터를 설정합니다.

import { createUploadthing, type FileRouter } from "uploadthing/server";

const f = createUploadthing();

export const uploadRouter = {
  profilePicture: f(["image"])
    .middleware(({ req }) => auth(req))
    .onUploadComplete((data) => console.log("file", data)),
  // 추가적인 라우터 설정...
} satisfies FileRouter;

클라이언트 사이드 구성 요소와 훅

클라이언트에서 UploadThing을 활용하여 파일 업로드를 쉽게 처리할 수 있도록 다양한 구성 요소와 훅을 제공합니다. 설치는 npm install uploadthing @uploadthing/react 명령으로 시작할 수 있습니다.

타입 안전 API 엔드포인트

타입 안전성을 보장하기 위해 UploadThing은 업로드된 파일 데이터 타입을 명확히 정의합니다. 이는 코드의 안정성과 유지보수성을 높이며, 개발자가 오류를 쉽게 파악하도록 돕습니다.

UploadThing 설치 및 기본 설정

UploadThing을 설치하고 기본 설정하는 방법을 알아봅시다. 우선, 필요한 패키지를 설치해야 합니다.

npm install uploadthing @uploadthing/react

그 다음, 서버 측에 파일 라우터를 구성합니다. 이 라우터는 클라이언트에 제공할 파일 업로드의 엔드포인트를 정의합니다.

업로드 라우터의 구성

UploadThing의 파일 라우터는 두 가지 요소로 구성됩니다: 파일 유형(FileType)과 라우터 옵션. 각 파일 유형은 특정 MIME 타입으로 정의되며, 업로드 가능한 파일의 종류 및 개수를 설정할 수 있습니다.

라우트 옵션

라우트 옵션은 업로드 라우터의 동작을 결정하는 설정들입니다. 예를 들어, awaitServerData 옵션은 서버의 데이터 처리가 완료될 때까지 클라이언트가 기다리게 할 수 있습니다.

const uploadRouter = {
  withServerData: f(
    { image: { maxFileSize: "2MB" } },
    { awaitServerData: true }
  )
    .middleware(({ req }) => ({ userId: "123" }))
    .onUploadComplete(async ({ metadata }) => {
      const result = await processImage(metadata);
      return { processedUrl: result.url };
    }),
}

라우터 메소드

UploadThing의 라우터 메소드는 다양한 업로드 전후 처리 기능을 제공합니다.

input

이 메소드는 사용자의 입력을 검증합니다. 예를 들어, 파일과 함께 전송된 추가 데이터를 특정 스키마에 맞추어 검증할 수 있습니다.

f(["image"])
  .input(z.object({
    title: z.string().min(1).max(100),
    tags: z.array(z.string()),
    isPublic: z.boolean()
  }))

middleware

미들웨어는 인증과 메타데이터 태깅을 처리합니다. 사용자의 인증 여부를 확인하고, 업로드 과정에 필요한 데이터를 준비하는 역할을 합니다.

f(["image"])
  .middleware(async ({ req, res }) => {
    const user = await currentUser();
    if (!user) throw new UploadThingError("Authentication required");
    // 추가 인증 로직...
  })

onUploadError

업로드 과정에서 에러가 발생했을 때 호출되는 핸들러입니다. 에러 로그를 처리하거나 실패한 업로드를 정리하는 데 사용할 수 있습니다.

f(["image"])
  .onUploadError(async ({ error, fileKey }) => {
    await logger.error("Upload failed", {
      error: error.message,
      fileKey,
      code: error.code
    });
  })

onUploadComplete

업로드가 성공적으로 완료된 후 호출되는 최종 핸들러입니다. 이 메소드에서 업로드된 파일을 처리하고 후속 작업을 수행할 수 있습니다.

f(["image"])
  .onUploadComplete(async ({ metadata, file }) => {
    await db.files.create({
      data: {
        userId: metadata.userId,
        fileName: file.name,
        // 추가 데이터베이스 로직...
      }
    });
  })

결론

UploadThing은 Next.js 애플리케이션에서 파일 업로드를 안전하게 처리할 수 있는 강력하면서도 유연한 솔루션입니다. 개발자는 이를 통해 파일 업로드를 더욱 쉽게 구현하고, 엔드포인트의 안전성을 높일 수 있습니다.

R_11