React 통합#

@snapkit-studio/react 패키지는 Snapkit의 이미지 최적화 기능을 React 애플리케이션에 원활하게 통합할 수 있도록 제공합니다.

설치#

React 프로젝트에 Snapkit을 설치하세요:

npm install @snapkit-studio/react
# 또는
yarn add @snapkit-studio/react
# 또는
pnpm add @snapkit-studio/react

빠른 시작#

환경 변수 설정#

먼저 환경 변수를 설정하세요:

VITE_SNAPKIT_ORGANIZATION_NAME=your-organization-name
VITE_SNAPKIT_DEFAULT_QUALITY=85
VITE_SNAPKIT_DEFAULT_OPTIMIZE_FORMAT=auto

기본 사용법#

React 애플리케이션에서 Snapkit을 사용하는 가장 간단한 방법:

import { Image } from '@snapkit-studio/react';
 
function MyComponent() {
  return (
    <Image
      src="/project/hero.jpg"
      alt="히어로 이미지"
      width={800}
      height={600}
      priority
      transforms={{ format: 'auto' }}
    />
  );
}

SnapkitProvider 사용 (권장)#

여러 이미지와 중앙화된 설정이 있는 애플리케이션의 경우:

import { SnapkitProvider, Image } from '@snapkit-studio/react';
 
function App() {
  return (
    <SnapkitProvider
      baseUrl="https://snapkit-cdn.snapkit.studio"
      organizationName="your-org"
      defaultQuality={85}
      defaultFormat="auto"
    >
      <YourApplication />
    </SnapkitProvider>
  );
}
 
function YourApplication() {
  return (
    <Image
      src="/hero.jpg"
      alt="히어로 이미지"
      width={800}
      height={600}
    />
  );
}

주요 기능#

자동 포맷 감지#

Snapkit은 브라우저 지원에 따라 최적의 포맷(AVIF, WebP, JPEG)을 자동으로 감지하고 제공합니다:

<Image
  src="/product.jpg"
  alt="제품"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

네트워크 인식 품질 조정#

네트워크 상태에 따른 동적 품질 조정:

<Image
  src="/high-res.jpg"
  alt="고해상도 이미지"
  width={1200}
  height={800}
  transforms={{ quality: 'auto' }}
/>

시각적 변환#

다양한 시각적 효과와 변환을 적용하세요:

// 그레이스케일 효과
<Image
  src="/photo.jpg"
  transforms={{ grayscale: true }}
/>
 
// 블러 효과
<Image
  src="/background.jpg"
  transforms={{ blur: 20 }}
/>
 
// 뒤집기와 회전
<Image
  src="/icon.png"
  transforms={{
    flip: true,
    rotate: 90
  }}
/>

영역 추출#

이미지에서 특정 영역을 추출하세요:

<Image
  src="/large-image.jpg"
  transforms={{
    extract: {
      x: 100,
      y: 100,
      width: 400,
      height: 300
    }
  }}
/>

성능 최적화#

우선순위 로딩#

즉시 로드되어야 하는 above-the-fold 이미지의 경우:

<Image
  src="/hero-banner.jpg"
  priority={true}
  width={1200}
  height={600}
/>

지연 로딩#

초기 페이지 로드를 개선하기 위한 below-the-fold 이미지의 경우:

<Image
  src="/footer-image.jpg"
  loading="lazy"
  width={600}
  height={400}
/>

반응형 이미지#

채우기 모드#

컨테이너를 채워야 하는 이미지의 경우:

<div className="relative w-full h-64 rounded-lg overflow-hidden">
  <Image
    src="/background.jpg"
    fill={true}
    className="object-cover"
    alt="배경"
  />
</div>

반응형 크기 조정#

다양한 화면 크기를 위한 srcset 생성:

<Image
  src="/responsive.jpg"
  width={800}
  height={600}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  transforms={{ format: 'auto' }}
/>

번들 크기 최적화#

최적화된 Import (~9KB)#

번들 크기가 중요한 애플리케이션의 경우:

import { Image } from '@snapkit-studio/react/image';
 
// provider 없이 사용 - props를 통해 설정
<Image
  src="/photo.jpg"
  baseUrl="https://your-cdn.snapkit.studio"
  organizationName="your-org"
  width={400}
  height={300}
/>

전체 번들 (~22KB)#

중앙화된 설정을 위해 provider 패턴을 사용하는 경우:

import { Image, SnapkitProvider } from '@snapkit-studio/react';

고급 설정#

커스텀 로더#

특정 요구사항을 위한 커스텀 이미지 로더 생성:

const customLoader = ({ src, width, quality }) => {
  const params = new URLSearchParams({
    w: width.toString(),
    q: (quality || 75).toString(),
  });
 
  return `https://your-cdn.snapkit.studio/${src}?${params}`;
};
 
<Image
  loader={customLoader}
  src="image.jpg"
  width={400}
  height={300}
/>

TypeScript 지원#

타입 안전한 변환을 지원하는 완전한 TypeScript 지원:

import { Image, type ImageTransforms } from '@snapkit-studio/react';
 
const transforms: ImageTransforms = {
  format: 'webp',
  quality: 90,
  blur: 0,
  grayscale: false,
};
 
<Image
  src="/typed-image.jpg"
  transforms={transforms}
  width={600}
  height={400}
/>

모범 사례#

여러 이미지에 Provider 사용: 애플리케이션에 많은 이미지가 있을 때는 SnapkitProvider를 사용하여 반복적인 설정을 피하세요.
중요한 이미지 최적화: above-the-fold 이미지에는 priority={true}를 사용하여 LCP(Largest Contentful Paint)를 개선하세요.
Below-Fold 이미지 지연 로딩: 즉시 보이지 않는 이미지에는 loading="lazy"를 사용하여 초기 페이지 로드를 개선하세요.
적절한 크기 설정: 레이아웃 이동(CLS)을 방지하기 위해 항상 width와 height를 제공하세요.
자동 포맷 사용: transforms={{ format: 'auto' }}로 Snapkit이 자동으로 최적의 포맷을 선택하도록 하세요.

마이그레이션 가이드#

네이티브 IMG 태그에서#

// 이전
<img
  src="/image.jpg"
  alt="설명"
  width="400"
  height="300"
/>
 
// 이후
<Image
  src="/image.jpg"
  alt="설명"
  width={400}
  height={300}
  transforms={{ format: 'auto' }}
/>

다른 이미지 컴포넌트에서#

대부분의 이미지 컴포넌트는 최소한의 변경으로 직접 교체할 수 있습니다:

// 이전 (다른 라이브러리)
<OptimizedImage
  source="/photo.jpg"
  width={500}
  height={400}
/>
 
// 이후 (Snapkit)
<Image
  src="/photo.jpg"
  width={500}
  height={400}
  transforms={{ format: 'auto' }}
/>

문제 해결#

일반적인 문제들#

이미지가 로드되지 않음: baseUrl과 organizationName이 올바르게 설정되었는지 확인하세요.
TypeScript 오류: 최신 버전의 @snapkit-studio/react가 설치되어 있는지 확인하세요.
레이아웃 이동: 항상 명시적인 width와 height 속성을 제공하세요.
흐릿한 이미지: 이미지를 원본 크기를 넘어서 확대하지 않도록 확인하세요.

브라우저 지원#

AVIF: Chrome 85+, Firefox 93+, Safari 16+
WebP: Chrome 23+, Firefox 65+, Safari 14+
지연 로딩: Chrome 76+, Firefox 75+, Safari 15.4+

주요 기능 요약#

자동 포맷 감지 (AVIF, WebP, JPEG)
Next.js Image 컴포넌트 호환
TypeScript 지원
반응형 이미지 로딩
DPR 기반 최적화
지연 로딩
네트워크 인식 품질 조정