지원되는 버전과 구성

이 페이지에서는 Kotlin/Wasm으로 효율적으로 개발하기 위한 WebAssembly 제안(proposal)과 지원 브라우저, 그리고 구성 권장 사항에 대한 세부 내용을 제공합니다.

출처: Supported versions and configuration

본문

브라우저 버전

Kotlin/Wasm은 가비지 컬렉션(WasmGC)과 예외 처리 같은 최신 WebAssembly 제안에 의존해, WebAssembly 내부에 개선 사항과 새로운 기능을 도입합니다.

이 기능들이 제대로 작동하도록 최신 제안을 지원하는 환경을 갖추세요. 브라우저 버전이 새로운 WasmGC를 기본적으로 지원하는지, 아니면 환경을 변경해야 하는지 확인해 봅니다.

Chrome

버전 119 이상: 기본적으로 작동해요.
이전 버전:

📝 참고 이전 브라우저에서 애플리케이션을 실행하려면 1.9.20보다 이전 버전의 Kotlin이 필요합니다.
1. 브라우저에서 chrome://flags/#enable-webassembly-garbage-collection으로 이동하세요.
2. WebAssembly Garbage Collection을 활성화해요.
3. 브라우저를 다시 시작합니다.

Chromium 기반

Edge, Brave, Opera, Samsung Internet 같은 Chromium 기반 브라우저를 포함합니다.

버전 119 이상: 기본적으로 작동해요.
이전 버전:

📝 참고 이전 브라우저에서 애플리케이션을 실행하려면 1.9.20보다 이전 버전의 Kotlin이 필요합니다. --js-flags=--experimental-wasm-gc 명령줄 인자를 붙여 애플리케이션을 실행하세요.

Firefox

버전 120 이상: 기본적으로 작동해요.
버전 119:
1. 브라우저에서 about:config로 이동하세요.
2. javascript.options.wasm_gc 옵션을 활성화해요.
3. 페이지를 새로고침합니다.

Safari/WebKit

버전 18.2 이상: 기본적으로 작동해요.
이전 버전: 지원하지 않습니다.

📝 참고 Safari 18.2는 iOS 18.2, iPadOS 18.2, visionOS 2.2, macOS 15.2, macOS Sonoma, macOS Ventura에서 사용할 수 있어요. iOS와 iPadOS에서는 Safari 18.2가 운영체제에 포함되어 배포됩니다. 사용하려면 기기를 18.2 이상 버전으로 업데이트하세요. 자세한 내용은 Safari 릴리스 노트를 참고하세요.

Wasm 제안 지원

Kotlin/Wasm 개선은 WebAssembly 제안을 기반으로 해요. 여기서는 WebAssembly의 가비지 컬렉션과 (이전 버전) 예외 처리 제안에 대한 지원 세부 내용을 확인할 수 있습니다.

가비지 컬렉션 제안

Kotlin 1.9.20부터 Kotlin 툴체인은 최신 버전의 Wasm 가비지 컬렉션(WasmGC) 제안을 사용해요.

이 때문에 Wasm 프로젝트를 최신 버전의 Kotlin으로 업데이트할 것을 강력히 권장합니다. 또한 Wasm 환경과 함께 최신 버전의 브라우저를 사용하는 것도 권장해요.

예외 처리 제안

Kotlin 툴체인은 예외 처리 제안의 이전 방식과 새로운 방식 양쪽을 모두 지원합니다. 덕분에 Kotlin이 만든 Wasm 이진 파일을 더 넓은 범위의 환경에서 실행할 수 있어요.

wasmJs 타깃은 기본적으로 이전 방식의 예외 처리 제안을 사용합니다. wasmJs 타깃에서 새로운 예외 처리 제안을 활성화하려면 -Xwasm-use-new-exception-proposal 컴파일러 옵션을 사용하세요.

반대로 wasmWasi 타깃은 기본적으로 새로운 제안을 사용해, 최신 WebAssembly 런타임과 더 잘 호환됩니다. 이전 방식으로 전환하려면 -Xwasm-use-new-exception-proposal=false 컴파일러 옵션을 사용하세요.

wasmWasi 타깃에서는 새로운 예외 처리 제안을 채택해도 안전해요. 이 환경을 대상으로 하는 애플리케이션은 보통 덜 다양한 런타임 환경(종종 특정 단일 VM에서 실행)에서 실행되는데, 일반적으로 사용자가 제어할 수 있어서 호환성 문제의 위험이 줄어듭니다.

💡 팁 프로젝트 설정, 의존성 사용, 그 외 작업에 대해 자세히 알아보려면 Kotlin/Wasm 예제를 참고하세요.

기본 import 사용하기

Kotlin/Wasm 코드를 JavaScript로 import하는 방식은 기본 export에서 이름 있는 export(named exports)로 전환되었어요.

여전히 기본 import를 사용하고 싶다면, 새 JavaScript 래퍼 모듈을 생성하세요. 다음 내용으로 .mjs 파일을 만들어 볼게요:

// 메인 .mjs 파일의 경로를 지정
import * as moduleExports from "./wasm-test.mjs";

export { moduleExports as default };

새 .mjs 파일을 resources 폴더에 두면, 빌드 과정에서 자동으로 메인 .mjs 파일 옆에 놓입니다.

.mjs 파일을 사용자 지정 위치에 둘 수도 있어요. 이 경우 메인 .mjs 파일 옆으로 수동으로 옮기거나, import 문의 경로를 그 위치에 맞게 조정해야 합니다.

Kotlin/Wasm 증분 컴파일

Kotlin/Wasm 타깃은 증분 컴파일을 지원해요. 컴파일러가 최근 변경 사항에 영향을 받은 파일만 다시 컴파일할 수 있게 해주므로, 컴파일 시간을 줄이는 데 도움이 됩니다.

Wasm 타깃의 증분 컴파일은 기본적으로 활성화되어 있어요. 비활성화하려면 프로젝트의 local.properties나 gradle.properties 파일에 다음 줄을 추가하세요:

kotlin.incremental.wasm=false

정규화된 클래스 이름의 진단

Kotlin/Wasm에서는 컴파일러가 애플리케이션 크기가 커지는 것을 피하기 위해, 생성된 이진 파일에 클래스의 정규화된 이름(FQN, fully qualified name)을 기본적으로 저장하지 않습니다.

이 때문에 Kotlin/Wasm 프로젝트에서 KClass::qualifiedName 프로퍼티를 호출하면, 정규화된 이름 기능을 명시적으로 활성화하지 않는 한 컴파일러가 오류를 보고해요.

이 진단은 기본적으로 활성화되어 있어서 오류가 자동으로 보고됩니다. 진단을 비활성화하고 Kotlin/Wasm에서 qualifiedName을 허용하려면, build.gradle.kts 파일에 다음 옵션을 추가해 모든 클래스의 정규화된 이름을 저장하도록 컴파일러에 지시하세요:

// build.gradle.kts
kotlin {
   wasmJs {
       ...
       compilerOptions {
           freeCompilerArgs.add("-Xwasm-kclass-fqn")
       }
   }
}

이 옵션을 활성화하면 애플리케이션 크기가 커진다는 점을 기억해 두세요.

정규화된 이름

Kotlin/Wasm 타깃에서는 추가 설정 없이 정규화된 이름(FQN)을 런타임에 사용할 수 있어요. 즉, KClass.qualifiedName 프로퍼티가 기본적으로 활성화되어 있습니다.

FQN을 사용하면 JVM에서 Wasm 타깃으로의 코드 이식성이 좋아지고, 전체 정규화된 이름을 표시해 런타임 오류를 더 유익하게 만듭니다.

배열 범위를 벗어난 접근과 트랩

Kotlin/Wasm에서 범위를 벗어난 인덱스로 배열에 접근하면 일반적인 Kotlin 예외 대신 WebAssembly 트랩(trap)이 발생해요. 트랩은 현재 실행 스택을 즉시 중단시킵니다.

JavaScript 환경에서 실행할 때 이 트랩들은 WebAssembly.RuntimeError로 나타나며, JavaScript 쪽에서 잡을 수 있어요.

Kotlin/Wasm 환경에서 이런 트랩을 피하려면, 실행 파일을 링크할 때 명령줄에서 다음 컴파일러 옵션을 사용할 수 있어요:

-Xwasm-enable-array-range-checks

또는 Gradle 빌드 파일의 compilerOptions {} 블록에 추가하세요:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xwasm-enable-array-range-checks")
    }
}

이 컴파일러 옵션을 활성화하면 트랩 대신 IndexOutOfBoundsException이 던져집니다.

자세한 내용을 확인하고 피드백을 남기려면 이 YouTrack 이슈를 참고하세요.

실험적 애너테이션

Kotlin/Wasm은 일반적인 WebAssembly 상호운용을 위한 여러 실험적 애너테이션을 제공합니다.

@WasmImport와 @WasmExport는 각각 Kotlin/Wasm 모듈 밖에서 정의된 함수를 호출하게 해 주고, Kotlin 함수를 호스트나 다른 Wasm 모듈에 노출하게 해 줍니다.

이 메커니즘은 아직 발전 중이기 때문에 모든 애너테이션이 실험적으로 표시되어 있어요. 사용하려면 명시적으로 옵트인해야 하며, 설계나 동작이 향후 Kotlin 버전에서 바뀔 수 있습니다.

디버깅 중 다시 로드

최신 브라우저에서 애플리케이션을 디버깅하는 것은 추가 설정 없이 바로 작동해요. 개발용 Gradle 태스크(*DevRun)를 실행하면 Kotlin이 자동으로 소스 파일을 브라우저에 제공합니다.

하지만 기본적으로 소스를 제공하면 Kotlin 컴파일과 번들링이 완료되기 전에 브라우저에서 애플리케이션이 반복해서 다시 로드될 수 있어요. 해결 방법으로 webpack 구성을 조정해 Kotlin 소스 파일을 무시하고, 제공되는 정적 파일에 대한 watching을 비활성화하세요. 프로젝트 루트의 webpack.config.d 디렉터리에 다음 내용의 .js 파일을 추가합니다:

config.watchOptions = config.watchOptions || {
    ignored: ["**/*.kt", "**/node_modules"]
}

if (config.devServer) {
    config.devServer.static = config.devServer.static.map(file => {
        if (typeof file === "string") {
            return {
                directory: file,
                watch: false,
            }
        } else {
            return file
        }
    })
}

지원되는 버전과 구성