react-fine-grained-signals 0.1.0 → 0.1.1

package/README.ja.md

@@ -13,13 +13,73 @@
 ## インストール
 
 ```sh
-# 公開予定のパッケージ名です。まだnpmには公開していません。
 pnpm add react-fine-grained-signals alien-signals
 ```
 
 `alien-signals` はpeer dependencyなので、上のように併せてinstallしてください。
 
-`useSignals()` を自動挿入するオプションのbuild pluginは別途installします。[描画最適化](docs/rendering-optimization.ja.md)を参照してください。
+## セットアップ
+
+プリミティブとフックは、installした時点で動作します。buildツールやコンパイラの設定は不要です。
+
+```tsx
+import { useSignal, useSignals } from "react-fine-grained-signals";
+
+function Counter() {
+  useSignals();
+  const count = useSignal(0);
+
+  return <button onClick={() => count.value++}>{count.value}</button>;
+}
+```
+
+以下の2つの最適化は任意であり、互いに独立しています。どちらもinstall後に別途設定するもので、上記のフックを使うだけなら不要です。
+
+### JSXランタイム — DOMへの直接バインディング
+
+ネイティブホスト要素の子要素として使われたsignalが、周囲のコンポーネントを再レンダーせずに、そのDOMノードだけを更新できるようになります。
+
+ファイル単位で有効にするには、先頭行にpragmaを書きます。他のファイルはReactのJSXランタイムのままになるため、アプリの一部だけで直接バインディングを使いたい場合はこちらを選んでください。[`examples/react-router`](examples/react-router)がこの構成です。
+
+```tsx
+/** @jsxImportSource react-fine-grained-signals */
+```
+
+プロジェクト全体で有効にする場合は `tsconfig.json` に設定します。
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react-fine-grained-signals"
+  }
+}
+```
+
+Viteはこの2つを `tsconfig.json` から読むため、`vite.config.ts` 側にJSXの設定は不要です。既定の変換でも `@vitejs/plugin-react` を使う場合でも同じです。
+
+このランタイムが対象とするのはネイティブ要素と、意図的に絞ったpropsだけです。Reactコンポーネントのpropsや子要素に渡したsignalはアンラップされません。許可リスト全体と、JSXをBabelで変換するツールチェーン（`tsconfig.json` を読みません）については[JSXのsignal子要素とhost binding](docs/jsx-bindings.ja.md)を参照してください。
+
+### ビルドplugin — `useSignals()` の自動挿入
+
+追跡境界をbuild時に挿入するため、コンポーネント側で `useSignals()` を手書きする必要がなくなります。別packageなので個別にinstallします。
+
+```sh
+pnpm add -D unplugin-react-fine-grained-signals
+```
+
+そのうえで、bundlerに応じたentry point（`/vite`、`/rollup`、`/webpack`、`/rspack`、`/esbuild`）をbuild設定に追加します。
+
+```ts
+// vite.config.ts
+import signals from "unplugin-react-fine-grained-signals/vite";
+
+export default defineConfig({
+  plugins: [signals({ mode: "auto" })],
+});
+```
+
+オプションの詳細と、フックを手書きする場合との使い分けについては[描画最適化](docs/rendering-optimization.ja.md)を参照してください。
 
 ## 開発
 

package/README.md

@@ -13,13 +13,88 @@ See [`docs/README.md`](docs/README.md) for guides on using the library, design i
 ## Installation
 
 ```sh
-# Planned package name — it is not published to npm yet.
 pnpm add react-fine-grained-signals alien-signals
 ```
 
 `alien-signals` is a peer dependency, so install it alongside this package.
 
-The optional build plugin for automatic `useSignals()` insertion is installed separately — see [Rendering optimization](docs/rendering-optimization.md).
+## Setup
+
+The primitives and hooks work as soon as the package is installed — no build
+or compiler configuration is involved:
+
+```tsx
+import { useSignal, useSignals } from "react-fine-grained-signals";
+
+function Counter() {
+  useSignals();
+  const count = useSignal(0);
+
+  return <button onClick={() => count.value++}>{count.value}</button>;
+}
+```
+
+The two optimizations below are opt-in and independent of each other. Both are
+configured after installing, and neither is needed to use the hooks above.
+
+### JSX runtime — direct DOM bindings
+
+Lets a signal used as the child of a native host element update that DOM node
+on its own, without re-rendering the component around it.
+
+Opt in one file at a time with a pragma on the first line. Every other file
+keeps React's JSX runtime, so this is the form to reach for when only part of
+an app needs the direct bindings — it is how
+[`examples/react-router`](examples/react-router) is set up:
+
+```tsx
+/** @jsxImportSource react-fine-grained-signals */
+```
+
+Or opt the whole project in through `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react-fine-grained-signals"
+  }
+}
+```
+
+Vite reads both of those from `tsconfig.json` — with its default transform and
+with `@vitejs/plugin-react` alike — so `vite.config.ts` needs no JSX
+configuration of its own.
+
+The runtime covers native elements only, and a deliberately narrow set of
+props. Signals passed to a React component's props or children are not
+unwrapped. See [JSX signal children and host bindings](docs/jsx-bindings.md)
+for the full allow-list, and for toolchains that transform JSX through Babel,
+which do not read `tsconfig.json`.
+
+### Build plugin — automatic `useSignals()`
+
+Inserts the tracking boundary during the build, so components no longer call
+`useSignals()` by hand. It is a separate package:
+
+```sh
+pnpm add -D unplugin-react-fine-grained-signals
+```
+
+It then needs a bundler entry point — `/vite`, `/rollup`, `/webpack`,
+`/rspack`, or `/esbuild` — added to the build configuration:
+
+```ts
+// vite.config.ts
+import signals from "unplugin-react-fine-grained-signals/vite";
+
+export default defineConfig({
+  plugins: [signals({ mode: "auto" })],
+});
+```
+
+See [Rendering optimization](docs/rendering-optimization.md) for the options
+and for the trade-offs against calling the hook by hand.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-fine-grained-signals",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Fine-grained signal rendering for React 19, built on alien-signals.",
   "license": "MIT",
   "author": "akazawa",