umsungjun · umsungjun · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/README.ko.md b/README.ko.md
@@ -10,6 +10,38 @@
 
 중복 없이 document title, meta 태그, Open Graph 태그, SEO 메타데이터를 안전하게 관리합니다. React SPA, Vite, Create React App 프로젝트에 완벽합니다.
 
+## 중요: CSR 애플리케이션에서의 SEO
+
+CSR 앱은 클라이언트에서 JavaScript를 실행하기 때문에, 검색 엔진 크롤러와 소셜 미디어 봇이 JavaScript를 실행하지 못할 수 있습니다. 이 경우 **동적으로 주입된 메타 태그가 인식되지 않을 수 있습니다.**
+
+최적의 SEO를 위해 `index.html`에 항상 기본 메타 태그를 설정하세요:
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+  <head>
+    <!-- JavaScript를 실행하지 않는 크롤러를 위한 기본 메타 태그 -->
+    <title>My App</title>
+    <meta name="description" content="앱에 대한 기본 설명입니다." />
+    <meta property="og:title" content="My App" />
+    <meta property="og:description" content="앱에 대한 기본 설명입니다." />
+    <meta property="og:image" content="https://example.com/default-image.jpg" />
+    <meta property="og:url" content="https://example.com" />
+    <meta property="og:type" content="website" />
+    <link rel="canonical" href="https://example.com" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+`react-head-safe`는 JavaScript가 실행될 때 **이 기본값을 런타임에 덮어씁니다.** 이 두 단계 접근 방식은 다음을 보장합니다:
+
+1. **JS를 실행하지 않는 크롤러**는 `index.html`의 기본 메타 태그를 인식
+2. **JS를 실행하는 크롤러** (예: Googlebot)와 **사용자**는 `react-head-safe`가 설정한 페이지별 메타 태그를 인식
+
 ## 왜 react-head-safe인가요?
 
 React에서 document head 요소를 관리하기 위한 가볍고 CSR에 최적화된 대안입니다. 다음과 같은 요구사항이 있는 간단한 클라이언트 사이드 렌더링 애플리케이션에 완벽합니다:

diff --git a/README.md b/README.md
@@ -10,6 +10,38 @@
 
 Safely manage document title, meta tags, Open Graph tags, and SEO metadata without duplicates. Perfect for React SPAs, Vite, and Create React App projects.
 
+## Important: SEO in CSR Applications
+
+Since CSR apps run JavaScript on the client side, search engine crawlers and social media bots may not execute your JavaScript. This means **dynamically injected meta tags might not be recognized**.
+
+For optimal SEO, always set default meta tags directly in your `index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <!-- Default meta tags for crawlers that don't execute JavaScript -->
+    <title>My App</title>
+    <meta name="description" content="Default description for your app." />
+    <meta property="og:title" content="My App" />
+    <meta property="og:description" content="Default description for your app." />
+    <meta property="og:image" content="https://example.com/default-image.jpg" />
+    <meta property="og:url" content="https://example.com" />
+    <meta property="og:type" content="website" />
+    <link rel="canonical" href="https://example.com" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+`react-head-safe` will **override these defaults at runtime** when JavaScript executes, allowing page-specific meta tags for each route. This two-layer approach ensures:
+
+1. **Crawlers without JS execution** see meaningful default meta tags from `index.html`
+2. **Crawlers with JS execution** (e.g., Googlebot) and **users** see page-specific meta tags set by `react-head-safe`
+
 ## Why react-head-safe?
 
 A lightweight, CSR-focused alternative for managing document head elements in React. Perfect for simple client-side rendered applications that need:

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-head-safe",
-  "version": "1.5.0",
+  "version": "1.6.0-0",
   "description": "A lightweight React head manager for CSR apps. Safely manage document title, meta tags, Open Graph, and SEO metadata without duplicates. TypeScript support included.",
   "author": "umsungjun",
   "license": "MIT",

diff --git a/vite.config.ts b/vite.config.ts
@@ -23,6 +23,7 @@ export default defineConfig({
   plugins: [
     dts({
       include: ['src/**/*.ts', 'src/**/*.tsx'],
+      exclude: ['src/test/**'],
       outDir: 'dist',
     }),
   ],