# Typescript 개발 가이드

### ⭐ 타입스크립트 개발 시 주의할 점

타입스크립트로 개발 시 **App, Map, Player, Widget** 키워드 앞에 **Script** 키워드를 붙여야 합니다.

```jsx
// 자바스크립트 개발 시
App.sayToAll("Hello World!");

// 타입스크립트 개발 시
ScriptApp.sayToAll("Hello World!");
```

### 1. **node.js 설치**

{% hint style="info" %}
<https://nodejs.org/ko/> 링크로 이동해 node.js를 설치합니다.

안정적인 버전인 LTS 버전으로 설치하는 것을 추천드립니다.
{% endhint %}

<figure><img src="/files/uGQyYd5d9Z3qoedSfwmI" alt=""><figcaption></figcaption></figure>

### 2. **프로젝트 폴더 만들기**

CLI를 통해 ZEP Script 프로젝트를 개발하기 위한 샘플 프로젝트를 다운로드 받을 수 있습니다.

CLI는 MacOS의 경우 터미널, Windows의 경우 Windows PowerShell 또는 Windows 11부터 제공되는 터미널 환경에서 실행하실 수 있습니다.

> **Windows에서 PowerShell 실행하기**
>
> 폴더를 생성하고 싶은 곳 빈 공간에 **Shift + 오른쪽클릭**을 해서
>
> **`여기에 PowerShell 창 열기`** 또는 **`여기서 명령창 열기`** 메뉴를 누르면
>
> ![](/files/ZnoVd0w8a9LQgkLqC82S)
>
> 다음과 같이 **Windows PowerShell** 또는 **명령 프롬프트** 창이 실행됩니다.
>
> <img src="/files/kUhZya6Goyd3D1fLIxAc" alt="" data-size="original">

다음과 같이 프로젝트 폴더를 생성하기 위한 명령어를 입력합니다.

<mark style="color:purple;">**`npx zep-script init {폴더 이름} --npm`**</mark>

<pre class="language-bash"><code class="lang-bash"><strong>npx zep-script@latest init MyZepApp --npm
</strong></code></pre>

<div align="left"><figure><img src="/files/dLpnQXTPhs3yLIvXsLV5" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/aA5S8xYcENgZDYQEKaPy" alt=""><figcaption></figcaption></figure></div>

위와 같이 <mark style="color:green;">`Project {폴더 이름} initialized successfully`</mark> 메시지가 출력 되었다면,

이제 타입스크립트로 **ZEP Script**를 개발할 수 있는 환경이 준비 된 것 입니다.

### 3. 폴더 구조 살펴보기

생성된 프로젝트 폴더로 이동하면 다음과 같이 파일들이 있는 것을 볼 수 있습니다.

여러 기능을 모듈로 나누고 싶다면, `src` 폴더내부에 파일을 추가해 확장할 수 있습니다.\
예: `playerUtils.ts`, `eventHandlers.ts` 등

**res** 폴더는 ‘**resources**’의 약자로, 앱에 필요한 이미지나 html 파일 등을 넣는 폴더입니다.

<div align="left"><figure><img src="/files/AMmKIwE3bbucaKxNh5wr" alt=""><figcaption></figcaption></figure></div>

여기서 생성된 **main.ts** 파일은 앱 로직을 작성하는 메인 파일입니다.

**main.ts** 에는 다음과 같이 샘플 코드가 적혀있습니다. 해당 코드를 참고하여 개발을 하시면 됩니다.

<div align="left"><figure><img src="/files/WbAw5oQE9cEvjhdZFxxR" alt=""><figcaption></figcaption></figure></div>

### 4. **빌드하기**

**ZEP Script**는 자바스크립트가 아닌 언어로 실행 할 수 없기 때문에 타입스크립트를 자바스크립트로 변환하는 빌드 과정을 거쳐야 합니다.

**main.ts** 파일이 있는 폴더에서 명령 창을 열어 다음과 같이 빌드를 위한 명령어를 입력합니다.

```powershell
npm run build 또는 npx zep-script build
```

<div align="left"><figure><img src="/files/dcsmNNGIRMxm9fX0TRFS" alt=""><figcaption></figcaption></figure></div>

빌드 완료 시 `res` 폴더에 `main.js` 파일이 생성됩니다.

<div align="left"><figure><img src="/files/VaABWnTgaMc1kKYLa652" alt=""><figcaption></figcaption></figure></div>

**5. 압축 파일 만들기**

ZEP Script로 만든 앱을 배포하려면 main.js 파일과 앱에서 사용 할 이미지, html 파일 등을 함께 압축한 **.zip** 파일을 준비해야 합니다.

**main.ts** 파일이 있는 폴더에서 명령 창을 열어서 다음과 같이 압축 파일을 만들기 위한 명령어를 입력합니다.

```powershell
npm run archive 또는 npx zep-script archive
```

<figure><img src="/files/ANh5r3Oteu2JKxe6SHlh" alt=""><figcaption></figcaption></figure>

압축 과정이 성공했다면 다음과 같이 폴더에 압축 파일이 생긴 것을 확인 할 수 있습니다.

<div align="left"><figure><img src="/files/GndpA1lxeQAI5hZBqogB" alt=""><figcaption></figcaption></figure></div>

압축 파일을 만드는 것을 마지막으로, 앱을 배포할 준비가 끝났습니다.

### 6. 프로젝트 배포하기

1. **홈페이지에서 배포하기**

위에서 만든 압축(ZIP) 파일을 홈페이지에서 업로드 하는 방식으로 앱을 배포할 수 있습니다.

[<mark style="color:purple;">ZEP Script 배포 가이드</mark>](/creator/dev-guide/zep-script.md) 페이지를 참고해서 앱을 배포해보세요!

&#x20; &#x20;

&#x20; **2. 명령어(CLI)로 배포하기**

CLI를 사용해 위에서 만든 압축(ZIP) 파일을 배포할 수 있습니다.

프로젝트 폴더에서 <mark style="color:purple;">`zep-script.json`</mark> 파일을 열어 업로드 될 앱을 설정합니다.

( zep-script.json 파일이 없다면 생성해주세요 )

<div align="left"><figure><img src="/files/o3QjYcqcs8K0VwI06gyy" alt=""><figcaption></figcaption></figure></div>

```json
{
    "appId": "Zjkgoj",  // app ID
    "name": "Template", // app 이름
    "description": "Template application" , // app 설명
    "type": "normal" // app 타입 ( "normal" or "minigame" or "sidebar" )
}
```

⭐ appID: 업로드할 앱의 ID를 입력합니다

* 기존 앱을 변경하시려면 <https://zep.us/me/apps/>에 접속해서 업로드할 앱을 선택 후 주소창에 apps/뒤에 붙는 값을 입력하시면 됩니다.(아래 예시 이미지에서 **Zjkoj**입니다)

<figure><img src="/files/0sZ4BDaG4aAJ1ecBP59Z" alt=""><figcaption></figcaption></figure>

설정이 끝났으면 프로젝트 폴더 경로에서 PowerShell 을 실행 한 뒤, 다음과 같이 배포를 하기 위한 명령어를 입력합니다.

```powershell
npm run deploy 또는 npx zep-script publish
```

<div align="left"><figure><img src="/files/da2IEllLknZb4VeyRMdu" alt=""><figcaption></figcaption></figure></div>

다음과 같이 email을 입력하는 부분이 나오면 배포 할 앱을 소유하고 있는 계정의 email을 입력합니다.

<div align="left"><figure><img src="/files/5d3DpVNog9MmNsoSKM2t" alt=""><figcaption></figcaption></figure></div>

**Sending login code to your email..**&#xC774;라는 메시지가 나오면 위에서 입력한 이메일의 메일 함에서 인증 코드를 확인한 뒤 입력해주면 배포가 시작됩니다.

<figure><img src="/files/5siwfPxNZfN8XTvN7D9v" alt=""><figcaption><p>메일 인증 예시</p></figcaption></figure>

다음 그림과 같이 **Publishing…** 텍스트 좌측에 초록색 체크 표시가 생기면 배포가 완료된 것 입니다.

<div align="left"><figure><img src="/files/9nbR80b7YiYqKrQaNslx" alt=""><figcaption></figcaption></figure></div>

[**나의 앱**](https://zep.us/me/apps) 페이지에서 **zep-script.json** 에 작성한 내용대로 앱이 배포된 것을 확인 할 수 있습니다.

<div align="left"><figure><img src="/files/NMB3EB4MaeuVOXIC5QGT" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
**배포에 실패하는 경우 아래의 단계를 따라 재시도 해보세요.**

**npx 명령어를 사용하는 경우**

1. 터미널에서 "`npm i zep-script@latest -g` "명령을 실행하여 SDK 패키지를 최신화
2. root 폴더에서 "`.zscsession"`  파일 삭제
3. "npx zep-script publish" 명령어로 배포 시도

**npm 명령어를 사용하는 경우**

1. package.json 파일의 "zep-script" 버전이 최신이 아니라면 최신 버전으로 업데이트
   1. `npm i zep-script@latest` 명령어 실행
2. root 폴더에서 "`.zscsession"`  파일 삭제
3. "npm run deploy" 명령어로 배포 시도
   {% endhint %}

라이브러리 관련하여 보다 자세한 내용은 아래 github 레포지토리 내용을 참고해주세요.

[zep-script-sdk/packages/zep-script-cli at main · zep-us/zep-script-sdk](https://github.com/zep-us/zep-script-sdk/tree/main/packages/zep-script-cli)

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-kr.zep.us/creator/dev-guide/typescript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.