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

# 설치와 진입점

> @edicus/sdk의 세 가지 임포트 경로와 언제 무엇을 쓰는지

`@edicus/sdk`는 브라우저용 패키지입니다. 임포트 경로가 셋이고, 경로마다 실행 환경과 내보내는 것이 다릅니다.

## 설치

<CodeGroup>
  ```sh npm theme={null}
  npm install @edicus/sdk@3.0.0-alpha.2
  ```

  ```sh pnpm theme={null}
  pnpm add @edicus/sdk@3.0.0-alpha.2
  ```

  ```sh yarn theme={null}
  yarn add @edicus/sdk@3.0.0-alpha.2
  ```
</CodeGroup>

알파 기간에는 버전을 정확히 적어 설치하세요. 버전 없이 설치하면 npm의 `latest` 태그가 가리키는 버전을 받습니다.

런타임 의존성이 없습니다. TypeScript strict로 작성돼 있어 타입이 함께 따라옵니다.

<Note>
  **ESM 전용 패키지입니다.** CommonJS 빌드가 없어 `require('@edicus/sdk')`로는 불러올 수 없습니다. `import`를 쓰세요. Node.js로 빌드하거나 테스트한다면 18 이상이 필요합니다(`engines.node >= 18`).
</Note>

## 세 가지 진입점

| 경로 | 환경 | 내보내는 것 |
| - | - | - |
| `@edicus/sdk` | 브라우저 | `createEdicusClient`, `Session` 계열 클래스, action 상수, `SDK_VERSION` |
| `@edicus/sdk/types` | 둘 다 | 편집기 메시지, 띄우기 옵션, VDP 타입과 action 이름 런타임 상수 |
| `@edicus/sdk/legacy` | 브라우저 | `edicusSDK`. v2 호환 표면입니다 |

<Note>
  **서버용 진입점은 없습니다.** 토큰 발급, 프로젝트 조회, 주문 처리는 HTTP 엔드포인트를 직접 호출해서 합니다. [Server API 호출하기](/docs/server/client)를 보세요.
</Note>

### `@edicus/sdk` (브라우저)

편집기, TnView, Preview를 띄웁니다.

```ts theme={null}
import { createEdicusClient } from '@edicus/sdk'

const edicus = createEdicusClient({
  baseUrl: 'https://editor.edicus.io', // 기본값입니다. 생략할 수 있습니다
})
```

`createEdicusClient()`는 `window`나 `document`를 즉시 건드리지 않습니다. SSR 환경에서 모듈을 임포트해도 안전하고, 실제 iframe은 `createProject` 같은 띄우기 메서드를 부르는 시점에만 마운트됩니다.

### `@edicus/sdk/types` (타입)

편집기와 주고받는 메시지의 타입(이벤트와 커맨드 payload, `Envelope`), 띄우기 옵션 타입, VDP 타입을 여기서 가져옵니다. 같은 타입은 `@edicus/sdk`에서도 다시 내보냅니다.

```ts theme={null}
import type { EditorEventMap, SaveDocReport, VariableDataRow, CreateProjectOptions } from '@edicus/sdk/types'
```

이 경로에는 아래의 action 이름 상수 배열 여섯 개가 런타임 값으로 들어 있습니다. `window`나 `document`를 쓰지 않으므로 서버 코드에서 임포트해도 됩니다.

<Warning>
  서버 응답 타입(`Project` 등)은 이 경로에서 빠졌습니다. 서버 요청과 응답의 타입이 필요하면 Server API의 OpenAPI 문서에서 직접 생성하세요.

  ```sh theme={null}
  npx openapi-typescript https://api.edicus.io/v2/openapi.json -o edicus-server-api.d.ts
  ```
</Warning>

action 이름의 런타임 상수 배열도 여기서 재수출합니다. 알려진 action인지 검사할 때 씁니다.

```ts theme={null}
import { EDITOR_EVENT_ACTIONS, EDITOR_COMMAND_ACTIONS } from '@edicus/sdk/types'
```

`EDITOR_EVENT_ACTIONS`, `EDITOR_COMMAND_ACTIONS`, `TNVIEW_EVENT_ACTIONS`, `TNVIEW_COMMAND_ACTIONS`, `PREVIEW_EVENT_ACTIONS`, `PREVIEW_COMMAND_ACTIONS` 여섯 개가 있습니다.

### `@edicus/sdk/legacy` (v2 호환)

v2(`edicus-sdk-v2.js`)와 같은 이름, 같은 콜백 모양을 그대로 제공합니다.

```ts theme={null}
import { edicusSDK } from '@edicus/sdk/legacy'
const editor = edicusSDK.init({})
```

새로 시작하신다면 이 경로 대신 `@edicus/sdk`를 쓰세요. 자세한 내용은 [SDK v2에서 옮기기](/docs/reference/migration-from-v2)에 있습니다.

## `<script>` 태그로 쓰기

번들러 없이 쓰려면 CDN의 IIFE 빌드를 씁니다. 이 빌드는 `@edicus/sdk/legacy`를 `window.edicusSDK`에 붙입니다.

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@edicus/sdk@3.0.0-alpha.2/dist/edicus-sdk.iife.js"></script>
```

지금은 정확한 버전(`@3.0.0-alpha.2`)을 적어 주세요. `@3` 같은 버전 범위는 알파 같은 프리릴리스를 고르지 않으므로, `3.0.0` 정식 버전이 나오기 전에는 파일을 찾지 못합니다. 정식 버전이 나온 뒤에는 major 버전(`@3`)만 고정해서 쓰시기를 권합니다.

## 버전 확인

```ts theme={null}
import { SDK_VERSION } from '@edicus/sdk'
console.log(SDK_VERSION)
```

<Note>
  `@edicus/sdk` v3은 아직 알파(`3.0.0-alpha.2`)입니다. `3.0.0` 정식 발행 전까지 API가 바뀔 수 있습니다.
</Note>

## 패키지에 함께 들어 있는 문서

설치하면 `node_modules/@edicus/sdk/` 안에 한국어 가이드(`docs/*.md`)와 `CHANGELOG.md`, 에이전트와 LLM용 API 지도인 `llms.txt`가 함께 들어옵니다. 웹에 접속하지 않고도 설치한 버전의 API를 확인할 수 있습니다.

## 다음 단계

<Columns cols={2}>
  <Card title="편집기 띄우기" icon="window" href="/docs/sdk/launch">
    띄우기 메서드와 옵션을 봅니다.
  </Card>

  <Card title="세션 API" icon="code" href="/docs/sdk/session">
    이벤트를 받고 커맨드를 보내는 방법을 봅니다.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.