ImportKit 사용 방법: 10분 안에 React 앱에 CSV/Excel 가져오기 추가

Source: Dev.to

번역할 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. (코드 블록, URL 및 마크다운 형식은 그대로 유지됩니다.)

개요

CSV 가져오기 기능을 처음부터 구축하려면 몇 주가 걸립니다—파일 파싱, 열 매핑 UI, 검증 로직, 오류 처리, 그리고 Excel 지원까지 필요합니다. ImportKit은 이 모든 기능을 드롭‑인 React 컴포넌트 형태로 제공하므로 오후에 바로 통합할 수 있습니다.

이 가이드는 일반적인 시나리오를 다룹니다: 사용자가 CRM 애플리케이션에 연락처 목록을 가져오도록 하는 방법.

사전 요구 사항

필요한 것:

• React 18.x 또는 React 19.x 애플리케이션 (Next.js 포함)
• ImportKit 계정 – 여기에서 가입하세요
• 약 10 분

ImportKit은 React 18 및 React 19를 피어 의존성으로 나열하므로 최신 React 설정과 함께 작동합니다.

단계 1: 패키지 설치

ImportKit은 npm에 @importkit/react 로 게시되어 있습니다. 이 패키지는 MIT 라이선스를 사용하며 TypeScript 타입 정의를 포함합니다.

npm install @importkit/react

이 라이브러리는 tsup을 통해 ESM/CJS 이중 빌드를 제공하므로 최신 및 레거시 번들러 모두에서 작동합니다.

Step 2: Get Your API Key

1. ImportKit 대시보드에 로그인합니다.
2. API Keys → Generate New Key 로 이동합니다.

위젯은 인증 및 사용량 추적을 위해 API 키가 필요합니다. 키는 사용자별로 범위가 지정되며 대시보드에서 취소할 수 있습니다.

• Free tier – 월 500행 (Supabase pg_cron을 통해 매월 1일 자동 리셋).
• Starter – 월 5 000행.
• Pro – 월 50 000행.
• Enterprise – 무제한 행.

단계 3: 데이터 스키마 정의

ImportKit은 기대하는 데이터를 설명하기 위해 필드 구성을 사용합니다. 연락처 가져오기를 위해 다음과 같이 정의할 수 있습니다:

const contactFields = [
  {
    name: 'email',
    label: 'Email Address',
    type: 'email',
    required: true,
  },
  {
    name: 'firstName',
    label: 'First Name',
    type: 'text',
    required: true,
  },
  {
    name: 'lastName',
    label: 'Last Name',
    type: 'text',
    required: false,
  },
  {
    name: 'status',
    label: 'Status',
    type: 'enum',
    enum: {
      values: ['Active', 'Inactive', 'Pending'],
      hints: ['enabled,live', 'disabled,off', 'waiting,review'],
    },
  },
  {
    name: 'age',
    label: 'Age',
    type: 'number',
    validate: [
      {
        type: 'min',
        value: 0,
        message: 'Age must be positive',
      },
    ],
  },
];

필드 유형

ImportKit은 text, email, number, date, 및 enum을 지원합니다. 각 유형은 다음과 같은 사용자 정의 검증 규칙을 가질 수 있습니다:

• 이메일 형식 검사
• 숫자 범위 (min, max)
• 문자열 길이 제한 (minLength, maxLength)
• 정규식 패턴

enum 유형은 여섯 단계 매칭 연쇄(정확히 일치, 대소문자 구분 없음, 고객 학습, 전역 학습, 개발자 힌트, AI 의미)를 사용하여 복잡한 원본 값을 자동으로 매핑합니다.

단계 4: 위젯을 컴포넌트에 추가하기

import { ImportWidget } from '@importkit/react';

function ContactImportPage() {
  const handleComplete = (data: any[]) => {
    console.log('Imported contacts:', data);
    // Send to your API
    fetch('/api/contacts/bulk', {
      method: 'POST',
      body: JSON.stringify(data),
      headers: { 'Content-Type': 'application/json' },
    });
  };

  return (
    <>
      {/* ImportWidget goes here */}
      <ImportWidget
        fields={contactFields}
        apiKey="YOUR_API_KEY"
        onComplete={handleComplete}
      />
    </>
  );
}

위젯은 모든 작업을 처리합니다:

• 드래그 앤 드롭 파일 업로드
• CSV 및 Excel 파일 파싱 (.csv, .xlsx, .xls)
• 컬럼 매핑 UI
• 유효성 검사 및 오류 수정
• 다단계 가이드 인터페이스

Step 5: Let AI Handle Column Mapping

파일이 업로드되면 ImportKit은 CSV 헤더와 대상 필드를 /api/suggest-mapping 으로 전송합니다. 이 엔드포인트는 OpenAI gpt‑4o‑mini(temperature = 0)를 호출하고 신뢰도 점수가 포함된 구조화된 JSON 응답을 받습니다.

AI 서비스가 사용 불가능한 경우, 위젯은 빠른 서브스트링 매칭으로 대체되어 가져오기가 계속 작동하도록 합니다.

예시 매핑 (CSV 열: “E‑mail”, “First”, “Last”, “Account Status”):

사용자는 언제든지 제안을 수동으로 재정의할 수 있습니다.

Step 6: 가져오기 전 검증

ImportKit은 각 행을 실시간으로 검증하여 미리보기 단계에서 인라인 오류를 표시합니다. 사용자는 다음 중 하나를 선택할 수 있습니다:

• 검증을 통과한 행만 가져오기, 또는
• 진행하기 전에 UI에서 직접 오류를 수정하기.

지원되는 검증 규칙은 다음과 같습니다:

• 이메일 형식
• 숫자 범위 (min, max)
• 문자열 길이 (minLength, maxLength)
• 정규식 패턴
• 열거형 값 매칭
• 필수 필드 강제 적용

이러한 사전 검증은 잘못된 데이터가 시스템에 들어가는 것을 방지하고 지원 티켓을 감소시킵니다.

옵션: 재사용 가능한 구성을 위한 템플릿 사용

여러 가져오기 시나리오(예: 연락처, 제품, 주문)가 있거나 파워 유저가 직접 가져오기를 관리하도록 하려면, 필드 구성을 템플릿으로 저장하고 동적으로 로드할 수 있습니다:

import { ImportWidget, loadTemplate } from '@importkit/react';

const template = await loadTemplate('contacts');

템플릿은 데이터베이스나 CDN에 저장할 수 있어, 프로젝트 전반에 걸쳐 가져오기 정의 라이브러리를 손쉽게 유지 관리할 수 있습니다.

그게 전부입니다!

몇 분만 설정하면 ImportKit은 강력한 CSV/Excel 가져오기, AI‑지원 열 매핑, 그리고 포괄적인 검증을 제공하며—모두 세련된 React 컴포넌트에 포함됩니다. 즐거운 가져오기 되세요!

ImportKit – 빠른 참고 가이드

1. 저장된 가져오기 구성 불러오기

템플릿은 Supabase의 import_templates 테이블에 저장되며 위젯의 templateId prop을 통해 로드됩니다:

이를 통해 사용자와 세션 간에 일관된 가져오기를 제공하고 구현 시간을 단축할 수 있습니다. 비기술 사용자도 대시보드 CRUD UI를 통해 가져오기 구성을 관리할 수 있습니다.

2. 선택 사항: 외관 맞춤화

ImportKit은 브랜드에 맞게 전체 테마를 지원합니다. 색상, 테두리, 글꼴을 커스터마이징하고 “Powered by ImportKit” 브랜딩을 숨길 수 있습니다:

showBranding을 false로 설정하면 화이트라벨 경험을 위해 푸터가 제거됩니다.

3. 선택 사항: 웹훅 전송 설정

Note: 웹훅은 Pro 또는 Enterprise 티어에서 사용할 수 있습니다.

1. 대시보드에서 웹훅 URL을 구성합니다.
2. ImportKit은 각 가져오기가 완료된 후 POST 요청으로 가져오기 데이터를 엔드포인트에 전송합니다.

헤더

• X-ImportKit-Signature: 요청 본문의 HMAC‑SHA256 서명.
• 비밀키는 crypto.randomBytes(32)를 통해 생성됩니다.

재시도 정책

• 지수 백오프(1 초 → 4 초)로 최대 3회 시도.
• 시도당 10초 제한시간.

페이로드 예시

{
  "event": "import.completed",
  "importId": "uuid",
  "rowCount": 150,
  "templateName": "Contact Import",
  "timestamp": "2024-01-28T10:30:00Z"
}

모든 재시도가 실패하면 실패가 로그에 기록되지만 가져오기 응답을 차단하지 않습니다. 웹훅은 사용자 입장에서 fire‑and‑forget 방식으로 동작합니다.

4. 내부에서 일어나는 일

모든 인증은 요청 본문의 API 키를 통해 수행되며 쿠키는 사용되지 않습니다.

5. ImportKit 사용 시점 vs. 직접 구현 시점

위젯의 소스 코드는 MIT 라이선스로 제공되며 **github.com/gthorr/importkit**에서 확인할 수 있습니다. 대시보드와 백엔드는 호스팅 서비스의 일부입니다.

6. 추가 자료

• GitHub 저장소:
• 공식 문서:

구현 관련 질문은 GitHub에 이슈를 열거나 문서를 참고하여 더 깊은 통합 세부 정보를 확인하세요.