# react-head-safe
[](https://www.npmjs.com/package/react-head-safe)
[](https://www.npmjs.com/package/react-head-safe)
[](https://codecov.io/gh/umsungjun/react-head-safe)
[English](README.md) | [한국어](README.ko.md)
**클라이언트 사이드 렌더링(CSR) 애플리케이션을 위한 가벼운 React head 매니저입니다.**
중복 없이 document title, meta 태그, Open Graph 태그, SEO 메타데이터를 안전하게 관리합니다. React SPA, Vite, Create React App 프로젝트에 완벽합니다.
## 중요: CSR 애플리케이션에서의 SEO
CSR 앱은 클라이언트에서 JavaScript를 실행하기 때문에, 검색 엔진 크롤러와 소셜 미디어 봇이 JavaScript를 실행하지 못할 수 있습니다. 이 경우 **동적으로 주입된 메타 태그가 인식되지 않을 수 있습니다.**
최적의 SEO를 위해 `index.html`에 항상 기본 메타 태그를 설정하세요:
```html
My App
```
`react-head-safe`는 JavaScript가 실행될 때 **이 기본값을 런타임에 덮어씁니다.** 이 두 단계 접근 방식은 다음을 보장합니다:
1. **JS를 실행하지 않는 크롤러**는 `index.html`의 기본 메타 태그를 인식
2. **JS를 실행하는 크롤러** (예: Googlebot)와 **사용자**는 `react-head-safe`가 설정한 페이지별 메타 태그를 인식
## 왜 react-head-safe인가요?
React에서 document head 요소를 관리하기 위한 가볍고 CSR에 최적화된 대안입니다. 다음과 같은 요구사항이 있는 간단한 클라이언트 사이드 렌더링 애플리케이션에 완벽합니다:
- **명시적 중복 방지** - 새로운 태그를 추가하기 전에 항상 기존 메타 태그를 제거합니다
- **간단함** - 복잡한 설정 없이 props만 전달하는 단일 컴포넌트
- **성능** - 페인트 전 동기적 DOM 업데이트를 위해 `useLayoutEffect` 사용
- **타입 안전성** - TypeScript로 작성되어 완전한 타입 정의 제공
## 주요 기능
- ✅ **중복 태그 없음** - 새 태그를 만들기 전에 기존 메타 태그 제거
- ✅ **TypeScript 지원** - TypeScript로 완전한 타입 안전성 제공
- ✅ **경량** - React 외에 의존성 제로
- ✅ **CSR 최적화** - 동기적 DOM 업데이트를 위해 `useLayoutEffect` 사용
- ✅ **Open Graph 지원** - 소셜 미디어 메타 태그 기본 지원
- ✅ **Twitter Card 지원** - Open Graph 태그 설정 시 Twitter 태그 자동 생성
- ✅ **간단한 API** - props만 전달하면 되는 복잡하지 않은 설정
## 설치
npm, yarn 또는 pnpm으로 설치:
```bash
npm install react-head-safe
# 또는
yarn add react-head-safe
# 또는
pnpm add react-head-safe
```
의존성 제로 (React는 peer dependency입니다).
## 빠른 시작
React 페이지에서 `ReactHeadSafe` 컴포넌트를 import하여 사용하세요:
```tsx
import { ReactHeadSafe } from 'react-head-safe';
function MyPage() {
return (
<>