PotLid · PotLid · Aug 19, 2026 · Aug 19, 2026 · Aug 19, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -36,3 +36,36 @@ jobs:
           name: playwright-report
           path: playwright-report/
           retention-days: 7
+
+  build-demo:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            demo/package-lock.json
+
+      # demo/tsconfig.json type-checks ../src/index.tsx directly (dogfooding
+      # the real source). That file lives outside demo/, so its bare
+      # `import 'react'` resolves starting from its own location — the repo
+      # root — not from demo/node_modules. Without the root install, tsc
+      # can't find 'react' at all when checking that file.
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Install demo dependencies
+        working-directory: demo
+        run: npm ci
+
+      - name: Type-check demo
+        working-directory: demo
+        run: npx tsc --noEmit -p tsconfig.json
+
+      - name: Build demo
+        working-directory: demo
+        run: npm run build
diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
@@ -0,0 +1,55 @@
+name: Deploy demo to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'demo/**'
+      - 'src/**'
+      - '.github/workflows/deploy-pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: demo/package-lock.json
+
+      - name: Install demo dependencies
+        working-directory: demo
+        run: npm ci
+
+      - name: Build demo
+        working-directory: demo
+        run: npm run build
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: demo/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -56,6 +56,9 @@ e2e/dist/
 playwright-report/
 test-results/
 
+# demo site build output
+demo/dist/
+
 # ignore composer vendor directory
 /vendor
 

diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 
 A React wrapper around the Daum/Kakao Postcode widget for searching Korean addresses and postal codes.
 
+**[Live demo & full docs →](https://potlid.github.io/react-kakao-postcode/)**
+
 ### Installation
 
 React-Kakao-Postcode requires React >=16.8.0 (hooks support) and React-Dom >=16.8.0
@@ -108,6 +110,8 @@ MIT ©PotLid
 
 Daum/Kakao 우편번호(주소 검색) 위젯을 감싼 React 컴포넌트입니다. [postcode.map.kakao.com/guide#usage](https://postcode.map.kakao.com/guide#usage)에 문서화된 옵션·콜백·메서드를 빠짐없이 지원합니다.
 
+**[라이브 데모 및 전체 문서 →](https://potlid.github.io/react-kakao-postcode/)**
+
 ### 설치
 
 React >=16.8.0 (Hooks 지원 버전), React-DOM >=16.8.0 이 필요합니다.

diff --git a/demo/index.html b/demo/index.html
@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="react-kakao-postcode — a React wrapper around the Daum/Kakao Postcode widget. Live demo and full API documentation." />
+    <title>react-kakao-postcode</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📮</text></svg>" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>