---
title: "VPE 2.0 React 사용 준비"
slug: "vpe-v2-react-spec"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-v2-react-spec"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VPE 2.0 React 사용 준비

Classic/VPC 환경에서 이용 가능합니다.

## 지원 환경

VPE 플레이어는 재생 환경을 구분하기 위해 `platform` 값을 설정해야 합니다. 플랫폼 값은 아래 두 가지입니다.

- `pub`: 민간 클라우드 환경
- `gov`: 공공 클라우드 환경

## 예제

### React 예제

`platform`은 `VpePlayer` 컴포넌트의 props로 전달합니다.

```
"use client";

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export default function PlayerPage() {
    return (
        <VpePlayer
            accessKey="YOUR_ACCESS_KEY"
            platform="pub"
            hls={Hls}
            dashjs={dashjs}
            options={{
                playlist: [
                    {
                        file: "https://CDN_DOMAIN/example_video_01.mp4",
                        poster: "https://CDN_DOMAIN/example_video_01.png",
                    },
                ],
            }}
        />
    );
}
```

### UMD 예제

UMD 환경에서는 `platform` props를 사용하지 않습니다. 민간/공공은 CDN 스크립트 엔드포인트로 구분합니다.

민간

```
<script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key={YOUR_ACCESS_KEY}"></script>
```

공공

```
<script src="https://player.vpe.gov-ntruss.com/v2/ncplayer.js?access_key={YOUR_ACCESS_KEY}"></script>
```

```
<script>
    const player = new ncplayer("player", {
        playlist: [
            { file: "https://CDN_DOMAIN/example_video_01.mp4" },
        ],
    });
</script>
```

## 패키지 설치

React, Next.js 프로젝트에서 `npm` 또는 `pnpm`으로 VPE SDK를 설치합니다.

`npm`을 사용하는 경우:

```
npm i @sgrsoft/vpe-react-sdk
```

`pnpm`을 사용하는 경우:

```
pnpm add @sgrsoft/vpe-react-sdk
```

## 피어 디펜던시

스트리밍 프로토콜에 따라 필요한 라이브러리를 추가로 설치합니다. 번들에 포함되지 않으므로 필요한 프로토콜만 선택적으로 설치하면 됩니다.

| 프로토콜 | 패키지 | 설명 |
| --- | --- | --- |
| HLS | hls.js | HLS 스트리밍 재생 (필수) |
| DASH | dashjs | DASH 스트리밍 재생 (선택) |

```
# HLS 스트리밍 (필수)
npm i hls.js

# DASH 스트리밍 (선택)
npm i dashjs
```

## Next.js 설정

Next.js에서 사용할 때는 `"use client"` 지시어가 필요합니다. VPE 컴포넌트는 브라우저 API를 사용하므로 클라이언트 컴포넌트로 렌더링해야 합니다.

```
"use client";

import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export default function PlayerPage() {
    return (
        <div style={{ maxWidth: "800px", margin: "0 auto" }}>
            <VpePlayer
                hls={Hls}
                accessKey="YOUR_ACCESS_KEY"
                options={{
                    playlist: [{
                        file: "https://example.com/video/master.m3u8",
                    }],
                    autostart: true,
                    muted: true,
                    aspectRatio: "16/9",
                }}
            />
        </div>
    );
}
```

## DASH 스트리밍 사용

DASH 프로토콜을 사용하려면 `dashjs`를 동적 import로 로드하여 전달합니다.

```
"use client";

import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";
import { useEffect, useState } from "react";

export default function PlayerPage() {
    const [dashjs, setDashjs] = useState(null);

    useEffect(() => {
        import("dashjs").then((mod) => {
            setDashjs(mod.default ?? mod);
        });
    }, []);

    return (
        <VpePlayer
            hls={Hls}
            dashjs={dashjs}
            accessKey="YOUR_ACCESS_KEY"
            options={{
                playlist: [{
                    file: "<https://example.com/video/stream.mpd>",
                }],
            }}
        />
    );
}
```

## LLM 기반 코드 생성

VPE 플레이어 설정을 빠르게 시작하기 위한 가이드입니다. `llms.txt`를 프롬프트로 제공하면 AI가 Next.js 기반 예제 코드를 생성합니다.

### 개념

`llms.txt`는 VPE 플레이어의 핵심 사용 규칙을 담은 요약 문서입니다. 이를 LLM에 먼저 읽히면 코드 생성 시 필수 옵션과 권장 구성을 누락하지 않도록 도와줍니다.

### LLM 선택

사용 중인 LLM(예: ChatGPT, Claude, Copilot, Cursor 등)에 아래 프롬프트를 그대로 붙여넣습니다.

### 프롬프트 입력

```
https://developer.vpe.naverncp.com/llms.txt 읽고 React 예제 코드 생성해줘
```

### 가이드

- 응답 코드에서 `accessKey`, `playlist` URL은 프로젝트 환경에 맞게 교체합니다.
- HLS를 사용할 경우, `hls.js` 주입이 필요한지 확인합니다.
- 결과가 길 경우, “필요한 부분만 요약해줘”라고 추가로 요청할 수 있습니다.