Kotlin/JS 시작하기

이 튜토리얼에서는 Kotlin/JavaScript(Kotlin/JS)를 사용하여 브라우저용 웹 애플리케이션을 만드는 방법을 보여줍니다. 앱을 만들려면 워크플로에 가장 적합한 도구를 선택하세요:

IntelliJ IDEA: 버전 관리 시스템에서 프로젝트 템플릿을 클론하고 IntelliJ IDEA에서 작업합니다.
Gradle 빌드 시스템: 프로젝트의 설정이 내부적으로 어떻게 작동하는지 더 잘 이해하기 위해 프로젝트의 빌드 파일을 수동으로 생성합니다.

Kotlin/JS를 사용하면 브라우저 외에도 다른 환경을 타겟으로 컴파일할 수 있습니다. 자세한 내용은 실행 환경(Execution environments)을 참고하세요.

IntelliJ IDEA에서 애플리케이션 생성

Kotlin/JS 웹 애플리케이션을 만들려면 IntelliJ IDEA의 Community 또는 Ultimate 에디션을 사용할 수 있습니다.

환경 설정

최신 버전의 IntelliJ IDEA를 다운로드하고 설치합니다.
Kotlin 멀티플랫폼 IDE 플러그인을 설치합니다(Kotlin 멀티플랫폼 Gradle 플러그인과 혼동하지 마세요).

프로젝트 생성

IntelliJ IDEA에서 File | New | Project from Version Control을 선택합니다.
Kotlin/JS 템플릿 프로젝트의 URL을 입력합니다:
text
```
https://github.com/Kotlin/kmp-js-wizard
```
Clone을 클릭합니다.

프로젝트 구성

kmp-js-wizard/gradle/libs.versions.toml 파일을 엽니다. 이 파일에는 프로젝트 의존성에 대한 버전 카탈로그가 포함되어 있습니다.
Kotlin 버전이 Kotlin/JS를 타겟으로 하는 웹 애플리케이션을 만드는 데 필요한 Kotlin 멀티플랫폼 Gradle 플러그인의 버전과 일치하는지 확인합니다:
text
```
[versions]
kotlin = "2.3.0"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
```
Gradle 파일을 동기화합니다(libs.versions.toml 파일을 업데이트한 경우). 빌드 파일에 나타나는 Load Gradle Changes 아이콘을 클릭합니다.
또는 Gradle 도구 창에서 새로고침 버튼을 클릭합니다.

멀티플랫폼 프로젝트를 위한 Gradle 구성에 대한 자세한 내용은 멀티플랫폼 Gradle DSL 레퍼런스를 참고하세요.

애플리케이션 빌드 및 실행

src/jsMain/kotlin/Main.kt 파일을 엽니다.
- src/jsMain/kotlin/ 디렉터리에는 프로젝트의 JavaScript 타겟을 위한 주요 Kotlin 소스 파일이 들어 있습니다.
- Main.kt 파일에는 kotlinx.browser API를 사용하여 브라우저 페이지에 "Hello, Kotlin/JS!"를 렌더링하는 코드가 포함되어 있습니다.
main() 함수에 있는 Run 아이콘을 클릭하여 코드를 실행합니다.

웹 애플리케이션이 브라우저에서 자동으로 열립니다. 또는 실행이 완료된 후 브라우저에서 다음 URL을 직접 열 수 있습니다:

text

   http://localhost:8080/

웹 애플리케이션을 확인할 수 있습니다:

애플리케이션 출력

애플리케이션을 처음 실행한 후, IntelliJ IDEA는 상단 바에 해당 실행 구성(jsMain [js])을 생성합니다:

Gradle 실행 구성

IntelliJ IDEA Ultimate에서는 JS 디버거(JS Debugger)를 사용하여 IDE에서 직접 코드를 디버깅할 수 있습니다.

연속 빌드(Continuous build) 활성화

Gradle은 변경 사항이 생길 때마다 프로젝트를 자동으로 다시 빌드할 수 있습니다:

실행 구성 목록에서 jsMain [js]를 선택하고 More Actions | Edit을 클릭합니다.
Run/Debug Configurations 대화 상자의 Run 필드에 jsBrowserDevelopmentRun --continuous를 입력합니다.
OK를 클릭합니다.

이제 애플리케이션을 실행하고 변경 사항을 만들면, Gradle은 프로젝트에 대해 증분 빌드(incremental builds)를 자동으로 수행하며 파일을 저장(/)하거나 클래스 파일을 변경할 때마다 브라우저를 핫 리로드(hot-reload)합니다.

애플리케이션 수정

단어의 글자 수를 세는 기능을 추가하도록 애플리케이션을 수정해 보겠습니다.

input 요소 추가

src/jsMain/kotlin/Main.kt 파일에서, 사용자 입력을 읽기 위해 확장 함수(extension function)를 통해 HTML input 요소를 추가합니다:

kotlin

// Element.appendMessage() 함수를 대체합니다
fun Element.appendInput() {
    val input = document.createElement("input")
    appendChild(input)
}

main()에서 appendInput() 함수를 호출합니다. 그러면 페이지에 input 요소가 표시됩니다:

kotlin

fun main() {
    // document.body!!.appendMessage(message)를 대체합니다
    document.body?.appendInput()
}

애플리케이션을 다시 실행합니다.
애플리케이션은 다음과 같이 보입니다:

입력 이벤트 핸들링 추가

appendInput() 함수 내부에 리스너를 추가하여 입력 값을 읽고 변경 사항에 반응하도록 합니다:

kotlin

// 현재의 appendInput() 함수를 대체합니다
fun Element.appendInput(onChange: (String) -> Unit = {}) {
    val input = document.createElement("input").apply {
        addEventListener("change") { event ->
            onChange(event.target.unsafeCast<HTMLInputElement>().value)
        }
    }
    appendChild(input)
}

IDE의 제안에 따라 HTMLInputElement 의존성을 임포트합니다.

main()에서 onChange 콜백을 호출합니다. 이 콜백은 입력 값을 읽고 처리합니다:

kotlin

fun main() {
    // document.body?.appendInput()을 대체합니다
    document.body?.appendInput(onChange = { println(it) })
}

출력 요소 추가

단락(paragraph)을 생성하는 확장 함수를 정의하여 출력을 표시할 텍스트 요소를 추가합니다:
kotlin
```
 fun Element.appendTextContainer(): Element {
     return document.createElement("p").also(::appendChild)
 }
```

main()에서 appendTextContainer() 함수를 호출합니다. 출력을 위한 요소가 생성됩니다:

kotlin

 fun main() {
     // 출력을 위한 텍스트 컨테이너를 생성합니다
     // val message = Message(topic = "Kotlin/JS", content = "Hello!")를 대체합니다
     val output = document.body?.appendTextContainer()

     // 입력 값을 읽습니다
     document.body?.appendInput(onChange = { println(it) })
 }

입력을 처리하여 글자 수 세기

공백을 제거하고 글자 수와 함께 출력을 표시하도록 입력을 처리합니다.

main() 함수 내의 appendInput() 호출 부분에 다음 코드를 추가합니다:

kotlin

fun main() {
    // 출력을 위한 텍스트 컨테이너를 생성합니다
    val output = document.body?.appendTextContainer()

    // 입력 값을 읽습니다
    // 현재의 appendInput() 함수 호출을 대체합니다
    document.body?.appendInput(onChange = { name ->
        name.replace(" ", "").let {
            output?.textContent = "Your name contains ${it.length} letters"
        }
    })
}

위의 코드 설명:

replace() 함수는 이름에서 공백을 제거합니다.
let{} 범위 함수(scope function)는 객체 컨텍스트 내에서 함수를 실행합니다.
문자열 템플릿(string template) (${it.length})은 달러 기호($)를 접두사로 붙이고 중괄호({})로 감싸서 문자열 내에 단어의 길이를 삽입합니다. 여기서 it은 람다 파라미터(lambda parameter)의 기본 이름입니다.

애플리케이션 실행

애플리케이션을 실행합니다.
이름을 입력합니다.
를 누릅니다.

결과를 확인할 수 있습니다:

애플리케이션 출력

입력을 처리하여 중복되지 않는 글자 수 세기

추가 연습으로, 입력을 처리하여 단어에서 중복되지 않는(unique) 글자의 수를 계산하고 표시해 보겠습니다:

src/jsMain/kotlin/Main.kt 파일에서 String에 대한 .countDistinctCharacters() 확장 함수를 추가합니다:
kotlin
```
fun String.countDistinctCharacters() = lowercase().toList().distinct().count()
```
위의 코드 설명:
- .lowercase() 함수는 이름을 소문자로 변환합니다.
- toList() 함수는 입력 문자열을 문자 리스트로 변환합니다.
- distinct() 함수는 단어에서 중복되지 않는 문자들만 선택합니다.
- count() 함수는 중복되지 않는 문자의 개수를 셉니다.

main()에서 .countDistinctCharacters() 함수를 호출합니다. 이름에서 중복되지 않는 글자 수를 셉니다:

kotlin

 fun main() {
     // 출력을 위한 텍스트 컨테이너를 생성합니다
     val output = document.body?.appendTextContainer()

     // 입력 값을 읽습니다
     document.body?.appendInput(onChange = { name ->
         name.replace(" ", "").let {
             // 중복되지 않는 글자 수를 출력합니다
             // output?.textContent = "Your name contains ${it.length} letters"를 대체합니다
             output?.textContent = "Your name contains ${it.countDistinctCharacters()} unique letters"
         }
     })
}

애플리케이션을 실행하고 이름을 입력하는 단계를 따릅니다.

결과를 확인할 수 있습니다:

애플리케이션 출력

Gradle을 사용하여 애플리케이션 생성

이 섹션에서는 Gradle을 사용하여 Kotlin/JS 애플리케이션을 수동으로 만드는 방법을 배울 수 있습니다.

Gradle은 Kotlin/JS 및 Kotlin 멀티플랫폼 프로젝트의 기본 빌드 시스템입니다. 또한 Java, Android 및 기타 생태계에서도 흔히 사용됩니다.

프로젝트 파일 생성

Kotlin Gradle 플러그인(KGP)과 호환되는 Gradle 버전을 사용하고 있는지 확인하세요. 자세한 내용은 호환성 테이블을 참고하세요.
파일 탐색기, 커맨드 라인 또는 선호하는 도구를 사용하여 프로젝트를 위한 빈 디렉터리를 만듭니다.

프로젝트 디렉터리 안에 다음 내용으로 build.gradle.kts 파일을 생성합니다:

KotlinGroovy

kotlin

// build.gradle.kts
plugins {
    kotlin("multiplatform") version "2.3.0"
}

repositories {
    mavenCentral()
}

kotlin {
    js {
        // 브라우저에서 실행하려면 browser()를, Node.js에서 실행하려면 nodejs()를 사용하세요
        browser() 
        binaries.executable()
    }
}

groovy

// build.gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.3.0'
}

repositories {
    mavenCentral()
}

kotlin {
    js {
        // 브라우저에서 실행하려면 browser()를, Node.js에서 실행하려면 nodejs()를 사용하세요
        browser() 
        binaries.executable()
    }
}

browser() 또는 nodejs()와 같은 다양한 실행 환경을 사용할 수 있습니다. 각 환경은 코드가 실행되는 위치를 정의하고 Gradle이 프로젝트에서 태스크 이름을 생성하는 방식을 결정합니다.

프로젝트 디렉터리 안에 빈 settings.gradle.kts 파일을 생성합니다.
프로젝트 디렉터리 안에 src/jsMain/kotlin 디렉터리를 생성합니다.
src/jsMain/kotlin 디렉터리 안에 다음 내용으로 hello.kt 파일을 추가합니다:
kotlin
```
fun main() {
    println("Hello, Kotlin/JS!")
}
```
관례에 따라 모든 소스는 src/<target name>[Main|Test]/kotlin 디렉터리에 위치합니다:
- Main은 소스 코드가 위치하는 곳입니다.
- Test는 테스트가 위치하는 곳입니다.
- <target name>은 타겟 플랫폼에 해당합니다(이 경우 js).

browser 환경인 경우

browser 환경에서 작업하는 경우 다음 단계를 따르세요. nodejs 환경에서 작업하는 경우 프로젝트 빌드 및 실행 섹션으로 이동하세요.

프로젝트 디렉터리 안에 src/jsMain/resources 디렉터리를 생성합니다.

src/jsMain/resources 디렉터리 안에 다음 내용으로 index.html 파일을 생성합니다:

html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Application title</title>
</head>
<body>
    <script src="$NAME_OF_YOUR_PROJECT_DIRECTORY.js"></script>
</body>
</html>

<$NAME_OF_YOUR_PROJECT_DIRECTORY> 플레이스홀더를 프로젝트 디렉터리의 이름으로 바꿉니다.

프로젝트 빌드 및 실행

프로젝트를 빌드하려면 루트 프로젝트 디렉터리에서 다음 명령을 실행합니다:

bash

# 브라우저의 경우
gradle jsBrowserDevelopmentRun

# 또는

# Node.js의 경우
gradle jsNodeDevelopmentRun

browser 환경을 사용 중이라면 브라우저가 index.html 파일을 열고 브라우저 콘솔에 "Hello, Kotlin/JS!"를 출력하는 것을 볼 수 있습니다. 콘솔은 / 명령어로 열 수 있습니다.

애플리케이션 출력

nodejs 환경을 사용 중이라면 터미널에 "Hello, Kotlin/JS!"가 출력되는 것을 볼 수 있습니다.

애플리케이션 출력

IDE에서 프로젝트 열기

Gradle을 지원하는 모든 IDE에서 프로젝트를 열 수 있습니다.

IntelliJ IDEA를 사용하는 경우:

File | Open을 선택합니다.
프로젝트 디렉터리를 찾습니다.
Open을 클릭합니다.

IntelliJ IDEA는 해당 프로젝트가 Kotlin/JS 프로젝트인지 자동으로 감지합니다. 프로젝트에 문제가 발생하면 IntelliJ IDEA는 Build 창에 오류 메시지를 표시합니다.

다음 단계는?

Kotlin/JS 프로젝트 설정
Kotlin/JS 애플리케이션 디버깅 방법 알아보기
Kotlin/JS로 테스트 작성 및 실행 방법 알아보기
실제 Kotlin/JS 프로젝트를 위한 Gradle 빌드 스크립트 작성 방법 알아보기
Gradle 빌드 시스템에 대해 더 읽어보기

Dokka 실행

출력 형식

검색

연산 및 연산자

Kotlin/JS 시작하기 ​

IntelliJ IDEA에서 애플리케이션 생성 ​

환경 설정 ​

프로젝트 생성 ​

프로젝트 구성 ​

애플리케이션 빌드 및 실행 ​

연속 빌드(Continuous build) 활성화 ​

애플리케이션 수정 ​

input 요소 추가 ​

입력 이벤트 핸들링 추가 ​

출력 요소 추가 ​

입력을 처리하여 글자 수 세기 ​

애플리케이션 실행 ​

입력을 처리하여 중복되지 않는 글자 수 세기 ​

Gradle을 사용하여 애플리케이션 생성 ​

프로젝트 파일 생성 ​

프로젝트 빌드 및 실행 ​

IDE에서 프로젝트 열기 ​

다음 단계는? ​

Kotlin/JS 시작하기

IntelliJ IDEA에서 애플리케이션 생성

환경 설정

프로젝트 생성

프로젝트 구성

애플리케이션 빌드 및 실행

연속 빌드(Continuous build) 활성화

애플리케이션 수정

input 요소 추가

입력 이벤트 핸들링 추가

출력 요소 추가

입력을 처리하여 글자 수 세기

애플리케이션 실행

입력을 처리하여 중복되지 않는 글자 수 세기

Gradle을 사용하여 애플리케이션 생성

프로젝트 파일 생성

프로젝트 빌드 및 실행

IDE에서 프로젝트 열기

다음 단계는?