zfb
GitHub リポジトリ

検索したい単語を入力

いつでも検索バーを開ける

概要

zfb の JSX ランタイム、パッケージのサブパス、コンポーネントを一度だけセットアップするモデルを紹介します。

zudo-react が提供するもの

zudo-react は @takazudo/zfb に同梱される JSX ランタイムです。コンポーネントのモデルは明示的でシンプルです。コンポーネント関数はレンダリングされるインスタンスごとに一度実行され、signal が変化する値を保持します。レンダラーはコンポーネントを再実行せずに、バインドされた DOM を更新します。

このランタイムは React や Preact の互換レイヤーではありません。hooks、context、portal、クラスコンポーネント、汎用的なツリーの差分更新はありません。JSX は zudo-react に渡す記述を作りますが、ランタイムが React と同じように動作するわけではありません。

JSX を設定する

zudo-react を含むバージョンの zfb パッケージをインストールします。zfb build と zfb dev は、プロジェクトに tsconfig.json がなくても、ページ、コンポーネント、アイランドの JSX を自動変換と固定の import source @takazudo/zfb/zudo-react でコンパイルします。プロジェクトの tsconfig.json にある jsx と jsxImportSource はこの変換に影響しません。ファイル単位の @jsxImportSource pragma はそのファイルの build 変換を上書きできますが、React や Preact の pragma を指定しても、それらのレンダラーがサポートされるわけではありません。zfb check、エディター、TypeScript によるテストファイルの型検査で同じランタイムの JSX 型を使うには、次の設定を tsconfig.json に追加します。テストランナーの変換設定は、ランナー自身の設定ファイルに指定してください。

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@takazudo/zfb/zudo-react"
  }
}

コンパイラーは本番用ヘルパーを @takazudo/zfb/zudo-react/jsx-runtime から解決します。開発用の変換には @takazudo/zfb/zudo-react/jsx-dev-runtime を使います。どちらもパッケージのサブパスであり、zudo-react は独立したパッケージではありません。

zfb check の TypeScript 検査にはプロジェクトの tsconfig.json が必要です。zfb check --skip-tsc はその検査を省略し、ほかのチェックを実行します。zfb check を参照してください。

ランタイムの値はコアエントリからインポートします。

import { computed, signal } from "@takazudo/zfb/zudo-react";

コンポーネントは一度だけ実行される

セットアップ中に signal を作り、その signal 自体を JSX に渡します。イベントで値を変更すると、次にスケジュールされた flush でテキストのバインディングが更新されます。

import { signal } from "@takazudo/zfb/zudo-react";

function Counter() {
  const count = signal(0);

  return (
    <button on:click={() => { count.value += 1; }}>
      Clicked {count} times
    </button>
  );
}

コンポーネント関数は、このインスタンスをレンダリングするときに一度呼ばれます。その後 count が変わるとテキストの領域が更新されますが、Counter は再実行されません。マウントされた各インスタンスには、それぞれのセットアップとスコープがあります。

signal を渡すと更新されるバインディングができます。JSX を作るときに値を読むと、その時点のスナップショットになります。

<p>{count}</p>
<p>{count.value}</p>

この例では、最初の子はリアクティブです。二番目の子はセットアップ中に読み取った数値のままです。この規則は、コンポーネントの props を通して値を渡す場合にも適用されます。

zfb サイトの外で zudo-react を使う

zudo-react は独立した npm パッケージではありません。@takazudo/zfb の中に含まれているため、zfb サイトではないホスト(別のバンドラーで作るアプリケーション、テストランナー、Node のスクリプトなど)は @takazudo/zfb をインストールし、次の公開サブパスからインポートします。

サブパス提供するもの
@takazudo/zfb/zudo-reactコアのエントリ。signal、computed、h、Fragment、Show、For、ErrorBoundary、batch、flush、getScope
@takazudo/zfb/zudo-react/jsx-runtime本番ビルド用の自動 JSX 変換の参照先
@takazudo/zfb/zudo-react/jsx-dev-runtime開発ビルド用の自動 JSX 変換の参照先
@takazudo/zfb/zudo-react/serverrenderToString、islandRoot、serializeProps
@takazudo/zfb/zudo-react/clienthydrate、mount、parseProps
@takazudo/zfb/zudo-react/testingcreateIslandTest と withIslandTestContext

zfb サイトの中では、zfb build と zfb dev が JSX を変換し、島の境界を登録し、ハイドレーションをスケジュールし、サーバーからクライアントへ props を運びます。外部のホストではこれらの処理は行われないため、ホスト自身が受け持ちます。

  • JSX の変換。 ホスト側の変換を自動ランタイムで設定し、JSX のインポート元に @takazudo/zfb/zudo-react を指定します。別の JSX ランタイムが作った要素は zudo-react の記述ではありません。

  • マウント境界とそのライフサイクル。 ホストはラッパー要素を作って接続し、ラッパーと一致する識別子を渡して @takazudo/zfb/zudo-react/client の mount または hydrate を呼び、null が返った場合に対処し、境界を取り除くときに dispose() または unmount() を呼びます。自分で所有するホストから mount するを参照してください。

  • サーバーレンダリング(使う場合)。 @takazudo/zfb/zudo-react/server の renderToString はどこでも HTML をレンダリングできます。zfb ビルドの外で SDK の <Island> 境界をレンダリングするには、識別子の追加設定が必要です。zfb ビルドの外で Island をレンダリングするを参照してください。

コンポーネントの契約はどこでも同じです。class と on:click 属性を使い、signal はセットアップ中に作り、セットアップ関数は一度だけ実行されます。

次に読むページ

以降のページでは、JSX の記述、リアクティブな更新、スコープ、サーバーレンダリング、ハイドレーション、フォーム、構造を持つ領域を説明します。島のスケジュールと永続化に関する zfb 側の仕組みは、島のガイドを参照してください。

関連ページ

Revision History

作成更新