tavio-player-react

tavio-player-react は、tavio の 3D ビューワーを React アプリケーションに簡単に組み込むためのコンポーネントライブラリです。

tavio-rendererについて

このライブラリは、内部で @openheart/tavio-renderer ライブラリに依存していますが、ライブラリ内にバンドルせずに外部依存の形になっています。

tavio-rendererがworkerやwasmを利用している関係で、コアライブラリをバンドルするとビルドに失敗したため、このような形式を採用しています。

基本的な使い方

1. パッケージのインストール

$ npm install @openheart/tavio-player-react @openheart/tavio-renderer

2. HTTP ヘッダーの設定

tavio-player-react は、3Dの描画を高速化するために内部でSharedArrayBufferを利用します。 デフォルトでは利用がオフになっていますが、快適に動作するために利用を有効化する必要があります。SharedArrayBufferの利用には、特定の HTTP ヘッダーを必要とします。お使いのフレームワークやサーバーの設定で、以下のヘッダーを追加してください。

• Cross-Origin-Opener-Policy: same-origin
• Cross-Origin-Embedder-Policy: require-corp

Next.js をお使いの場合は、next.config.js に以下のように記述します。
詳細は fix-shared-array-buffer-not-defined-nextjs-react を参照。

const nextConfig = {
  async headers() {
    return [
      {
        source: "/:path*",
        headers: [
          {
            key: "Cross-Origin-Opener-Policy",
            value: "same-origin",
          },
          {
            key: "Cross-Origin-Embedder-Policy",
            value: "require-corp",
          },
        ],
      },
    ];
  },
};

module.exports = nextConfig;

3. コンポーネントの利用

上記の設定が完了したら、TavioPlayer コンポーネントをアプリケーションに組み込むことができます。

import { TavioPlayer } from "@openheart/tavio-player-react";

export default function MyPage() {
  return (
    <TavioPlayer
      url="/path/to/your/model.tavio"
      // 必要に応じてカメラパラメータなどを指定
    />
  );
}

開発環境のセットアップ

1. リポジトリをクローンします。

git clone https://github.com/openheart-inc/tavio-player-react.git

2. pnpm を使って依存パッケージをインストールします。

$ pnpm install

環境によってはcorepackでpnpmを有効化する必要があります。

$ corepack enable pnpm

開発

ウォッチモードでビルド

ライブラリをウォッチモードでビルドします。

$ pnpm dev

アイコン生成

svgr/icons にある SVG ファイルから、React コンポーネントを自動生成します。アイコンを追加・変更した際に実行してください。

$ pnpm gen:icons

型チェック

型チェックを実行します。

$ pnpm type-check

ビルド

pnpm build
ライブラリをビルドします。

$ pnpm build

リリース作業

tavio-rendererのアップデート

tavio-player-reactがアップデートされている場合は、package.jsonのpeerDependenciesとdevDependenciesのバージョンをアップデートしてください。

リリースプルリクエストを作成

1. Actions > "Create release pull request" へ移動
2. "Run workflow" ボタンをクリック
3. "Release tag" を入力して "Run workflow" ボタンをクリック

※ Release tagタグはセマンティックバージョンの形式で入力してください。（v 接頭辞は必須） 例: v1.0.0

リリースを実行

1. 作成されたリリースプルリクエストを確認してマージする
2. リリースプルリクエストがマージされたら、自動でnpmレジストリへのリリースが開始されます。