# ogpeek

> URL 한 줄로 OG 카드가 어떻게 보이는지 즉시 확인하고 OGP 스펙 위반을 잡아냅니다.

HTML: https://minjun.kim/ogpeek/ko

**어느 페이지든 오픈그래프 메타태그를 바로 들여다봅니다**

URL 하나만 넣으면 렌더링될 카드, 선언된 모든 메타 태그, OGP 스펙 위반 사항을 한 번에 보여 줍니다.

예시: [ogp.me](https://minjun.kim/ogpeek/ko/inspect?url=ogp.me) · [github.com/minjun0219/ogpeek](https://minjun.kim/ogpeek/ko/inspect?url=github.com%2Fminjun0219%2Fogpeek) · [nextjs.org](https://minjun.kim/ogpeek/ko/inspect?url=nextjs.org)

## 동작 방식

URL 하나가 세 단계를 거칩니다. 이 사이트의 Workers, 여러분의 Node 서버, 브라우저 확장 프로그램에서 같은 엔진이 동작합니다.

```
URL → fetch → parse → validate → preview
```

1. **가져오기** (`ogpeek/fetch`): 타임아웃과 응답 크기 한도 안에서 리디렉션을 한 단계씩 따라갑니다. 매 요청 직전에 guard 훅이 실행되므로, 어떤 호스트에 접근할지는 호출하는 쪽이 결정합니다.
2. **파싱** (`parse()`): 실제 웹의 어수선한 마크업에서 정규화된 오픈그래프 트리를 만듭니다. og:image:width 같은 구조화 속성은 부모 속성에 붙고, 파비콘·JSON-LD·theme-color도 함께 추출합니다.
3. **검증** (`result.warnings`): 필수 태그 누락, 상대 URL, 중복 선언 같은 흔한 OGP 스펙 위반을 에러·경고·안내로 나눠 알려 줍니다.

## 검증 항목

모든 경고에는 고정된 코드와 심각도가 붙어 있어, 직접 만든 도구에서도 그대로 걸러 쓸 수 있습니다.

- 에러 `OG_TITLE_MISSING`: og:title이 없습니다
- 에러 `OG_TYPE_MISSING`: og:type이 없습니다
- 에러 `OG_IMAGE_MISSING`: og:image가 없습니다
- 에러 `OG_URL_MISSING`: og:url이 없습니다
- 경고 `OG_TITLE_TOO_LONG`: og:title이 60자를 넘습니다 — 카카오톡에서 잘립니다
- 경고 `OG_URL_MISMATCH`: og:url의 호스트·경로가 실제 요청 URL과 다릅니다
- 경고 `OG_TYPE_UNKNOWN`: og:type 값이 OGP 스펙 목록에 없습니다
- 경고 `URL_NOT_ABSOLUTE`: URL 속성 값이 절대 URL이 아닙니다
- 경고 `DUPLICATE_SINGLETON`: 한 번만 선언해야 하는 속성이 여러 번 선언되었습니다
- 경고 `ORPHAN_STRUCTURED_PROPERTY`: 구조화 속성이 부모 속성 없이 나타났습니다
- 경고 `INVALID_DIMENSION`: width·height 값을 정수로 해석할 수 없습니다
- 경고 `JSONLD_PARSE_ERROR`: JSON-LD 블록을 JSON으로 파싱할 수 없습니다
- 안내 `MISSING_PREFIX_ATTR`: `<html prefix>`가 선언되지 않았습니다

## 패키지

이 사이트를 이루는 엔진과 React 컴포넌트를 npm에서 바로 설치할 수 있습니다.

### ogpeek

ogpeek은 임의의 URL에서 OpenGraph 메타태그를 파싱·페치·검증합니다. 페처는 타임아웃과 응답 크기 한도 안에서 리디렉션을 추적하고, 파서는 실제 웹의 어수선한 마크업을 잘 허용하며, 검증기는 흔한 OGP 스펙 위반을 잡아냅니다. 외부 의존성은 하나뿐이며 Node와 엣지 런타임에서 동일하게 동작합니다.

```sh
npm install ogpeek
```

#### Quick start

```ts
import { parse } from "ogpeek";
import { fetchHtml } from "ogpeek/fetch";

const { html, finalUrl } = await fetchHtml(url);
const result = parse(html, { url: finalUrl });

result.ogp.title; // normalized Open Graph tree
result.warnings; // [{ code, severity, message }]
```

[npm에서 보기](https://www.npmjs.com/package/ogpeek) · [README](https://github.com/minjun0219/ogpeek/tree/main/packages/ogpeek#readme)

### @ogpeek/react

React에서 결과를 렌더링한다면, 이 사이트가 쓰는 Result, Preview, ValidationPanel, RedirectFlow, TagTable 컴포넌트를 그대로 가져다 쓸 수 있습니다.

```sh
npm install @ogpeek/react
```

[npm에서 보기](https://www.npmjs.com/package/@ogpeek/react) · [README](https://github.com/minjun0219/ogpeek/tree/main/packages/ogpeek-react#readme)

## 브라우저 확장 프로그램

Chrome · MV3

이 사이트는 Cloudflare Workers에서 페이지를 가져오기 때문에 VPN 뒤나 사내망 페이지에는 닿지 않습니다. 확장 프로그램은 같은 엔진을 브라우저 안에서 실행하므로, 요청이 서버가 아니라 내 컴퓨터에서 나갑니다.

- 현재 탭의 실제 DOM을 바로 검사합니다 — 추가 요청 없이, 로그인 상태 그대로
- 다른 URL은 브라우저 자체의 네트워크 스택으로 가져옵니다
- 북마크하고 공유할 수 있는 전체 화면 보기를 제공합니다

[설치 안내](https://github.com/minjun0219/ogpeek/blob/main/packages/ogpeek-extension/README.ko.md)

---

[GitHub](https://github.com/minjun0219/ogpeek) · [MIT License](https://github.com/minjun0219/ogpeek/blob/main/LICENSE) · [llms.txt](https://minjun.kim/ogpeek/llms.txt)
