本文へ移動
rdlabo.devdocs

開発とリリース

開発

公開エントリーポイントはsrc/index.tsとsrc/ionic.tsで、共通の契約はsrc/types.tsに定義します。実装は責務別に分かれています。

  • src/native/: ブリッジ通信、ネイティブセッション、起動、リソースURL。
  • src/projection/: 画像の受け渡し、投影の所有権、イベント、スタイル。
  • src/dom/: ジオメトリ、スクロール、表示状態、オーバーレイ連携。

npm run buildはsrc/native/bootstrap.tsを共通のWebViewランタイムruntime/native-ui-engine.jsへバンドルします。Androidはこのファイルをアセットとして直接パッケージ化します。SwiftPMはターゲットディレクトリ内にリソースを必要とするため、ビルド時にios/Sources/WebViewNativeUIEngine/Resourcesへもコピーします。ネイティブ側の利用者がNode.jsを必要としないよう、両方の生成ファイルをコミットします。編集するのはTypeScriptソースであり、生成ファイルではありません。CIは再生成を確認し、npmとMavenのアーカイブに含まれるランタイムを検証します。

ブラウザーテストもtests/配下でこの分類に対応しています。tests/cordova/には実際のネイティブ利用側の検証用構成があります。

CIと同じNode.js 24を使います。このリポジトリで実行します。

npm ci
npm run build
npm run lint
npx playwright install chromium
npm test
xcodebuild -scheme WebViewNativeUIEngine -destination 'platform=iOS Simulator,id=<booted simulator UUID>' test

lintは厳密なTypeScriptチェック、標準のESLint・TypeScript推奨ルール、src向けの型情報を使うPromiseチェックを組み合わせます。スクリプトとテストは構文レベルのlintを適用し、フォーマットはPrettierが担当します。npm run formatはフォーマットのみを適用します。ブリッジのペイロードとテストダブルには明示的なanyを使用できますが、本番の境界での検証は引き続き必要です。明示的なvoidはバックグラウンド処理を示しますが、Promiseの拒否を処理するものではありません。AndroidはCIで警告をエラーとして扱うlintReleaseを使い、SwiftはiOSシミュレーターでコンパイル・テストします。

Engineは利用側とは独立してバージョン管理します。公開順はネイティブのMavenアーティファクト → npmのEngineで、利用側は別途更新します。npmのリリースでは、公開前に対応するPOMとAARがMaven Centralに存在することを確認します。ビルドやテストのコマンドは公開を行いません。テストは通常のDOM、小数値・RTLのジオメトリ、古いACK、画像の所有権、ネイティブWKWebViewのスクロール追従を扱います。Ionic・SDKの組み込みは利用側のテストが担当します。

CI専用のセットアップ、パッケージ化コマンド、GitHubの出力は.github/workflows/に定義します。スクリプトにはランタイムビルド、再利用可能な利用側・パッケージの検証、テスト済みの公開ロジック（Centralの状態処理とnpmアーティファクト比較）を置きます。

Mavenへの公開

Native UI Engine Maven Releaseワークフローは、正確なEngineパッケージのバージョンを指定してmain上で手動実行します。そのコミットは、先にNative UI EngineのCIを通過している必要があります。AAR、ソースアーカイブ、生成されたKotlin APIドキュメント、Mavenメタデータへ署名し、1回アップロードして、CentralがPUBLISHINGまたはPUBLISHEDを返したら完了します。デプロイIDと状態の変化は実行サマリーに記録します。PUBLISHINGは検証を通過してCentralが公開を受け付けたことを意味し、アーティファクトがすでにダウンロード可能であることは保証しません。このワークフローは配信完了を待ちません。npmリリースには引き続き、対応するPOMとAARがMaven Centralで利用可能であることが必要です。既存の座標は上書きしません。アップロードがタイムアウトした場合は、追加操作の前にCentralに記録されたデプロイを確認してください。

リポジトリのActionsシークレットにCENTRAL_USERNAME、CENTRAL_PASSWORD（Centralのユーザートークン）、MAVEN_SIGNING_KEY（ASCII-armored形式の秘密鍵）、MAVEN_SIGNING_PASSWORDを設定します。署名の公開鍵はCentralから参照できる必要があります。GitHubシークレットのスコープはこのリポジトリです。

ローカルでのパッケージ化検証には、JDK 21、Android SDK 36、GnuPGを使ってpython3 scripts/native-ui-engine-release/verify.pyを実行します。使い捨ての鍵を作成し、署名とチェックサムを検証して、アップロードせずにテスト用ZIPを削除します。公開時には必ずクリーンな出力から実際の署名鍵を使って再ビルドします。プレリリースを含め、対応するnpmリリースより先にMavenアーティファクトを公開してください。

メンテナー向けリリース設定

このリポジトリは、ionic-theme-ios27 b218d8bでマージされたEngine実装を出発点としています。抽出時にはマージ済み実装を維持し、Cordovaホスト対応はこのリポジトリで開発しています。名称変更後のパッケージはバージョン0.0.1から始まります。npm、SwiftPM、Mavenで同じバージョンを公開し、旧パッケージの座標を再利用しないでください。

npm組織webview-native-uiとMaven Central名前空間io.github.webview-native-uiは登録済みです。webview-native-ui/engineのワークフローrelease.ymlに対するnpm trusted publishingを維持し、このリポジトリに上記Mavenシークレットを設定します。ソースファイルを移動しても認証情報はコピーされません。

  1. mainで次のバージョンとリリースノートを準備し、npm run releaseで標準のvX.Y.ZタグとGitHubリリースを作成します。Mavenがダウンロード可能になるまで、GitHubリリースはドラフトのままにします。
  2. そのmainコミットがCIを通過したら、正確なパッケージバージョンを指定してnative-ui-engine-release.ymlを実行します。
  3. CentralのPUBLISHINGはアップロードが受け付けられた状態であり、ダウンロード準備完了ではありません。POMとAARが利用可能になったら、準備したGitHubリリースを公開します。release.ymlはタグ、パッケージバージョン、CI、Mavenアーティファクトを検証してからnpmへ公開します（プレリリースはnext、それ以外はlatest）。

ビルドやテストのコマンドはパッケージを公開しません。既存のnpm・Mavenバージョンを上書きすることはありません。

既存タグのリリース検証を再実行するには、そのタグを指定してrelease.ymlを実行します。元のタグ付きコミットをチェックし、既存パッケージの内容が一致する場合に限ってnpm公開をスキップします。タグは変更しないでください。リリースツールはCIと同じ、Node.js 24に同梱されたnpmを使います。

GitHubでこのページを編集