Snapkit Logo

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 { Image, SnapkitProvider } from "@snapkit-studio/react";
 
function App() {
  return (
    <SnapkitProvider baseUrl="https://cdn.snapkit.studio/snapkit" 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 h-64 w-full overflow-hidden rounded-lg">
  <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} />;

모범 사례#

  1. 여러 이미지에 Provider 사용: 애플리케이션에 많은 이미지가 있을 때는 SnapkitProvider를 사용하여 반복적인 설정을 피하세요.

  2. 중요한 이미지 최적화: above-the-fold 이미지에는 priority={true}를 사용하여 LCP(Largest Contentful Paint)를 개선하세요.

  3. Below-Fold 이미지 지연 로딩: 즉시 보이지 않는 이미지에는 loading="lazy"를 사용하여 초기 페이지 로드를 개선하세요.

  4. 적절한 크기 설정: 레이아웃 이동(CLS)을 방지하기 위해 항상 width와 height를 제공하세요.

  5. 자동 포맷 사용: 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' }}
/>

문제 해결#

일반적인 문제들#

  1. 이미지가 로드되지 않음: baseUrl과 organizationName이 올바르게 설정되었는지 확인하세요.

  2. TypeScript 오류: 최신 버전의 @snapkit-studio/react가 설치되어 있는지 확인하세요.

  3. 레이아웃 이동: 항상 명시적인 width와 height 속성을 제공하세요.

  4. 흐릿한 이미지: 이미지를 원본 크기를 넘어서 확대하지 않도록 확인하세요.

브라우저 지원#

  • 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 기반 최적화
  • 지연 로딩
  • 네트워크 인식 품질 조정

리소스#