Swift / Kotlin 타입 생성

Swift 또는 Kotlin으로 작성한 순수 네이티브 WebView 호스트에서는 TypeScript contract를 직접 import할 수 없습니다. webview-bridge-kit-gen은 contract에서 메시지 이름과 payload / response 타입을 읽어 네이티브 코드를 생성합니다.

생성 결과에는 DTO뿐 아니라 BridgeHandlers, 런타임 binding, 타입 안전한 event 함수가 포함됩니다. 플랫폼별 연결은 Swift 사용법과 Kotlin 사용법을 참고하세요.

준비

생성기는 TypeScript 컴파일러 API를 사용합니다. typescript는 선택적 peer dependency이므로, 생성기를 실행할 프로젝트에 직접 설치하세요.

npm install webview-bridge-kit
npm install --save-dev typescript

contract는 기본적으로 contract라는 이름으로 export되어야 합니다.

// bridge-contract.ts
import { command, defineContract, event, request } from 'webview-bridge-kit';
import { z } from 'zod';

export const contract = defineContract({
  KAKAO_LOGIN: request({
    response: z.object({
      accessToken: z.string(),
      expiresIn: z.number().optional(),
    }),
  }),
  SEND_LOGS: command({ payload: z.object({ lines: z.array(z.string()) }) }),
  OPEN_CAMERA: command(),
  PHOTO_TAKEN: event({
    payload: z.object({
      uri: z.string(),
      meta: z.object({ width: z.number(), height: z.number() }),
    }),
  }),
});

스키마 라이브러리의 런타임 객체를 분석하는 방식이 아닙니다. TypeScript가 __req, __res, __payload phantom 필드에 추론한 타입을 읽으므로, parse(value): T 형태를 만족하는 어떤 스키마도 사용할 수 있습니다.

Swift 생성

npx webview-bridge-kit-gen \
  --contract ./bridge-contract.ts \
  --lang swift \
  --out ./ios/BridgeTypes.swift

--out을 생략하면 결과를 표준 출력으로 보냅니다. 생성 결과에는 종류별 메시지 이름 enum, Codable struct, handler protocol과 binding이 포함됩니다.

enum BridgeRequestName: String, Codable {
    case KAKAO_LOGIN
}

struct KakaoLoginResponse: Codable {
    let accessToken: String
    let expiresIn: Double?
}

Kotlin 생성

npx webview-bridge-kit-gen \
  --contract ./bridge-contract.ts \
  --lang kotlin \
  --package com.example.bridge \
  --out ./android/BridgeTypes.kt

--package의 기본값은 generated입니다. 데이터 타입과 handler binding은 Android 런타임의 kotlinx.serialization 설정을 사용합니다.

enum class BridgeRequestName {
    KAKAO_LOGIN
}

@Serializable
data class KakaoLoginResponse(
    val accessToken: String,
    val expiresIn: Double? = null
)

옵션

옵션	필수	설명
--contract <file.ts>	O	contract가 있는 TypeScript 파일
--lang <swift|kotlin>	O	생성할 언어
--out <file>	X	출력 파일. 생략하면 표준 출력
--export <name>	X	contract export 이름. 기본값 contract
--package <name>	X	Kotlin package. 기본값 generated

다른 이름으로 export했다면 --export로 지정합니다.

npx webview-bridge-kit-gen --contract ./bridge-contract.ts --export appBridge --lang swift

타입 매핑과 제한

TypeScript	Swift	Kotlin
string	String	String
number	Double	Double
boolean	Bool	Boolean
T[]	[T]	List<T>
object	별도 Codable struct	별도 @Serializable data class
optional 필드	T?	T? = null

JSON에는 정수와 실수를 구분하는 별도 타입이 없으므로 TypeScript number는 항상 Double로 생성됩니다. union, Date, bigint, tuple 등 안전하게 매핑할 수 없는 타입을 만나면 잘못된 코드를 만드는 대신 에러로 중단합니다.

nullable/optional 객체 필드는 네이티브 nullable 타입으로 생성됩니다. nullable 배열 원소와 Swift/Kotlin에서 안전하지 않은 메시지·필드 식별자는 명시적 에러로 중단합니다.

자동 생성 파일로 관리하세요

contract가 바뀔 때마다 생성기를 다시 실행하도록 빌드 스크립트나 CI에 명령을 넣는 편이 안전합니다. 생성 파일에는 직접 수정하지 말라는 헤더가 포함됩니다.