Kotlin/JS 시작하기

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

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

브라우저를 대상으로 하는 것 외에도, Kotlin/JS로 다른 환경용으로 컴파일할 수 있어요. 자세한 내용은 실행 환경을 참고하세요.

출처: Get started with Kotlin/JS

본문

IntelliJ IDEA에서 애플리케이션 만들기

IntelliJ IDEA를 사용해 Kotlin/JS 웹 애플리케이션을 만들 수 있어요.

환경 설정하기

IntelliJ IDEA 최신 버전을 다운로드해 설치하세요.
Kotlin Multiplatform IDE 플러그인을 설치합니다(Kotlin Multiplatform Gradle 플러그인과 혼동하지 마세요).

프로젝트 만들기

IntelliJ IDEA에서 File | New | Project from Version Control을 선택하세요.
Kotlin/JS 템플릿 프로젝트의 URL을 입력합니다:

https://github.com/Kotlin/kmp-js-wizard

Clone을 클릭해요.

프로젝트 구성하기

kmp-js-wizard/gradle/libs.versions.toml 파일을 여세요. 프로젝트 의존성의 버전 카탈로그가 들어 있습니다.

Kotlin 버전이 Kotlin/JS를 대상으로 하는 웹 애플리케이션을 만드는 데 필요한 Kotlin Multiplatform Gradle 플러그인 버전과 일치하는지 확인하세요:

[versions]
kotlin = "2.4.20"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }

(libs.versions.toml 파일을 업데이트했다면) Gradle 파일을 동기화하세요. 빌드 파일에 나타나는 Load Gradle Changes 아이콘을 클릭합니다. 또는 Gradle 도구 창의 새로고침 버튼을 클릭해도 돼요.

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

애플리케이션 빌드하고 실행하기

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

웹 애플리케이션이 브라우저에서 자동으로 열려요. 또는 실행이 끝나면 브라우저에서 다음 URL을 열 수도 있습니다:

   http://localhost:8080/

웹 애플리케이션을 볼 수 있어요.

애플리케이션을 처음 실행한 후, IntelliJ IDEA는 상단 막대에 해당 실행 구성(jsMain [js])을 만듭니다.

Ultimate 구독이 있는 IntelliJ IDEA에서는 JS Debugger를 사용해 IDE에서 직접 코드를 디버깅할 수 있어요.

연속 빌드 활성화하기

Gradle은 변경할 때마다 프로젝트를 자동으로 다시 빌드할 수 있어요:

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

이제 애플리케이션을 실행하고 변경을 가하면, Gradle은 프로젝트의 증분 빌드를 자동으로 수행하고, 저장할 때마다(Ctrl + S/Cmd + S) 또는 클래스 파일을 변경할 때마다 브라우저를 핫 리로드해요.

애플리케이션 수정하기

단어에 포함된 글자 수를 세는 기능을 추가하도록 애플리케이션을 수정해 볼게요.

입력 요소(Input element) 추가하기

src/jsMain/kotlin/Main.kt 파일에 확장 함수를 통해 HTML 입력 요소를 추가해 사용자 입력을 읽어 봅시다:

// Replace the Element.appendMessage() function
fun Element.appendInput() {
    val input = document.createElement("input")
    appendChild(input)
}

main()에서 appendInput() 함수를 호출해요. 페이지에 입력 요소가 표시됩니다:

fun main() {
    // Replace document.body!!.appendMessage(message)
    document.body?.appendInput()
}

애플리케이션을 다시 실행해 보세요. 애플리케이션이 이렇게 보입니다.

입력 이벤트 처리 추가하기

appendInput() 함수 안에 리스너를 추가해 입력 값을 읽고 변화에 반응해 봅니다:

// Replace the current appendInput() function
fun Element.appendInput(onChange: (String) -> Unit = {}) {
    val input = document.createElement("input").apply {
        addEventListener("change") { event ->
            onChange(event.target.unsafeCast().value)
        }
    }
    appendChild(input)
}

IDE의 제안을 따라 HTMLInputElement 의존성을 임포트하세요.

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

fun main() {
    // Replace document.body?.appendInput()
    document.body?.appendInput(onChange = { println(it) })
}

출력 요소 추가하기

단락을 만드는 확장 함수를 정의해 출력을 표시할 텍스트 요소를 추가해 봅시다:

 fun Element.appendTextContainer(): Element {
     return document.createElement("p").also(::appendChild)
 }

main()에서 appendTextContainer() 함수를 호출해요. 출력 요소를 만듭니다:

 fun main() {
     // Creates a text container for our output
     // Replace val message = Message(topic = "Kotlin/JS", content = "Hello!")
     val output = document.body?.appendTextContainer()

     // Reads the input value
     document.body?.appendInput(onChange = { println(it) })
 }

입력을 처리해 글자 수 세기

공백을 제거하고 글자 수가 있는 출력을 표시하도록 입력을 처리해 보아요.

main() 함수의 appendInput() 함수에 다음 코드를 추가하세요:

fun main() {
    // Creates a text container for our output
    val output = document.body?.appendTextContainer()

    // Reads the input value
    // Replace the current appendInput() function
    document.body?.appendInput(onChange = { name ->
        name.replace(" ", "").let {
            output?.textContent = "Your name contains ${it.length} letters"
        }
    })
}

위 코드에서:

replace() 함수는 이름에서 빈 공백을 제거해요.
let{} 스코프 함수는 객체 컨텍스트 안에서 함수를 실행합니다.
문자열 템플릿(${it.length})은 달러 기호($)를 접두사로 붙이고 중괄호({})로 감싸 단어의 길이를 문자열에 삽입해요. 반면 it은 람다 파라미터의 기본 이름입니다.

애플리케이션 실행하기

애플리케이션을 실행합니다.
이름을 입력하세요.
Enter를 누르세요.

결과를 볼 수 있어요.

입력을 처리해 고유 글자 수 세기

추가 연습으로, 단어 안의 고유한 글자 수를 계산해 표시하도록 입력을 처리해 볼게요:

src/jsMain/kotlin/Main.kt 파일에 String용 .countDistinctCharacters() 확장 함수를 추가하세요:

fun String.countDistinctCharacters() = lowercase().toList().distinct().count()

위 코드에서:

.lowercase() 함수는 이름을 소문자로 변환해요.
toList() 함수는 입력 문자열을 문자 리스트로 변환합니다.
distinct() 함수는 단어에서 고유한 문자만 선택해요.
count() 함수는 고유한 문자를 셉니다.

main()에서 .countDistinctCharacters() 함수를 호출해요. 이름의 고유한 글자를 셉니다:

 fun main() {
     // Creates a text container for our output
     val output = document.body?.appendTextContainer()

     // Reads the input value
     document.body?.appendInput(onChange = { name ->
         name.replace(" ", "").let {
             // Prints the number of unique letters
             // Replace 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 Multiplatform 프로젝트의 기본 빌드 시스템입니다. Java, Android 등 다른 생태계에서도 흔히 사용돼요.

프로젝트 파일 만들기

Kotlin Gradle 플러그인(KGP)과 호환되는 Gradle 버전을 사용해야 해요. 자세한 내용은 호환성 표를 참고하세요.
파일 탐색기, 명령줄, 또는 원하는 어떤 도구로든 프로젝트용 빈 디렉터리를 만듭니다.
프로젝트 디렉터리 안에 다음 내용으로 build.gradle.kts 파일을 만드세요:

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

repositories {
    mavenCentral()
}

kotlin {
    js {
        // Use browser() for running in a browser or nodejs() for running in Node.js
        browser() 
        binaries.executable()
    }
}

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

repositories {
    mavenCentral()
}

kotlin {
    js {
        // Use browser() for running in a browser or nodejs() for running in Node.js
        browser() 
        binaries.executable()
    }
}

browser()나 nodejs() 같은 다양한 실행 환경을 사용할 수 있어요. 각 환경은 코드가 어디에서 실행되는지 정의하고, Gradle이 프로젝트에서 태스크 이름을 만드는 방식을 결정합니다.

프로젝트 디렉터리 안에 빈 settings.gradle.kts 파일을 만드세요.
프로젝트 디렉터리 안에 src/jsMain/kotlin 디렉터리를 만듭니다.
src/jsMain/kotlin 디렉터리 안에 다음 내용으로 hello.kt 파일을 추가하세요:

fun main() {
    println("Hello, Kotlin/JS!")
}

관례에 따라 모든 소스는 src/<target name>[Main|Test]/kotlin 디렉터리에 위치해요:

Main은 소스 코드의 위치입니다.
Test는 테스트의 위치예요.
<target name>은 대상 플랫폼에 해당합니다(여기서는 js).

브라우저 환경용

브라우저 환경에서 작업한다면 다음 단계를 따르세요. nodejs 환경에서 작업한다면 "프로젝트 빌드하고 실행하기" 섹션으로 이동하세요.

프로젝트 디렉터리 안에 src/jsMain/resources 디렉터리를 만듭니다.
src/jsMain/resources 디렉터리 안에 다음 내용으로 index.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> 자리 표시자를 프로젝트 디렉터리의 이름으로 바꾸세요.

프로젝트 빌드하고 실행하기

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

# For browser
gradle jsBrowserDevelopmentRun

# OR

# For Node.js
gradle jsNodeDevelopmentRun

브라우저 환경을 사용한다면, 브라우저가 index.html 파일을 열고 브라우저 콘솔에 "Hello, Kotlin/JS!"를 출력하는 것을 볼 수 있어요. 콘솔은 Ctrl + Shift + J/Cmd + Option + J 명령으로 열 수 있습니다.

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 빌드 시스템에 대해 더 읽어 보아요.

Kotlin/JS 시작하기