document-factory

文書形式ごとに最適化されたReactコンポーネントで資料を作成し、ブラウザで軽量にプレビューするためのツールです。

現在は、HTML資料のReact Server Componentプレビューに対応しています。

必要な環境

• Node.js 20.19以降、または22.12以降
• npm

インストール

公開済みのリリースをnpmレジストリからインストールします。

npm install --global document-factory

現在はnpmレジストリへ未公開のため、利用者向けリリースはまだ提供されていません。

資料を作成する

Document Root内の .tsx が、拡張子を除いた相対パスと同じURLで公開されます。

documents/
├── .components/
│   └── DocumentLayout.tsx
└── reports/
    └── test-result.tsx

documents/reports/test-result.tsx:

import { DocumentLayout } from "../.components/DocumentLayout";

async function loadResult() {
  return { passed: 42, failed: 0 };
}

export default async function TestResult() {
  const result = await loadResult();

  return (
    <DocumentLayout title="テスト結果報告">
      <p>成功: {result.passed}</p>
      <p>失敗: {result.failed}</p>
    </DocumentLayout>
  );
}

ドットで始まるディレクトリはURLへ公開されないため、共通コンポーネントの配置に利用できます。資料は通常のReactの仕組みに則って分割・再利用でき、Server Component内で非同期にデータを読み込めます。

プレビューする

Document Rootへ移動して起動します。

cd documents
document-factory serve

別の場所からDocument Rootを指定することもできます。

document-factory serve ./documents

上記の例は、次のURLで表示できます。

http://127.0.0.1:3000/reports/test-result

トップページには、公開されている資料がファイルエクスプローラ形式で表示されます。ディレクトリは資料より先に、各グループ内は名前の自然順に並びます。ディレクトリは初期状態で閉じており、クリックしたときに直下の項目を読み込んで展開します。

http://127.0.0.1:3000/

利用可能なオプション:

document-factory serve [document-root] --host 127.0.0.1 --port 3000

• --root <path>: Document Root。位置引数の代わりに指定可能。
• --host <host>: 待ち受けるホスト。既定値は 127.0.0.1。
• --port <port>: 待ち受けるポート。既定値は 3000。

存在しない資料はHTTP 404、TSXの評価またはレンダリングに失敗した資料はHTTP 500を返します。エラーの詳細はサーバーのコンソールへ出力されます。

セルフホスト

ネットワーク内のユーザーへ公開する場合は、Node.js環境へパッケージと資料を配置して次のように起動します。

document-factory serve /srv/documents --host 0.0.0.0 --port 3000

プロセスマネージャーやOSのサービス機能を使って、このコマンドを常時実行してください。公開範囲、認証、TLS、アクセス制御は、想定ユーザーと実行環境に応じてリバースプロキシまたはネットワーク側で構成します。

動作確認:

curl --fail http://127.0.0.1:3000/reports/test-result

リリースを検証する

npm ci
npm pack

npm pack は型検査、Lint、全テスト、ビルドを実行し、npmへ公開されるパッケージ内容をローカルで検証するために使用します。生成されたtarballは利用者向けのインストール経路として扱いません。

リリース

package.json の version をSemVerの正本とします。0系の間はリリースする変更ごとにパッチバージョンを上げます。

mainへのpushまたはpull requestのマージ後、CIがすべて成功すると、未公開のバージョンをnpmレジストリへ自動公開します。同じバージョンがすでに公開済みの場合は再公開せず、成功として終了します。

公開にはnpm Trusted Publishingを使用します。初回公開の準備が完了するまでは、GitHub Actionsの NPM_TOKEN secretを認証のフォールバックとして使用します。

開発

npm ci
npm run check
npm run lint
npm test
npm run build

テストには、実際のRSCサーバーを起動してHTMLプレビュー、非同期Server Component、日本語URL、HTTP 404、HTTP 500を検証するAcceptanceテストが含まれます。