app-core と react-tools から移行する

前提条件

このガイドは @dataarthub/app-core と @dataarthub/react-tools を使用するアプリケーションを対象にします。公開版の移行先は @alneas/[email protected] と @alneas/[email protected] です。公開版のバージョン番号は、従来の非公開パッケージのバージョンとは独立しています。0.1.0 は既存パッケージをそのままダウングレードするものではありません。

Node.js 24.0.0 以降を使用してください。公開 React は、^19.2.3 に合う React と React DOM を必要とします。依存関係を変更する前に、アプリケーションの既存のロックファイルと動作するリビジョンを保持してください。まず機能別のインポートと実行時の動作を棚卸しします。

公開インポート

2つのパッケージ名を指定してインストールしてください。フレームワークに依存しない API は @alneas/appkit-core/data、/storage、/japan、/graph、/ai から、React の機能は @alneas/appkit-react/ui、/tools、/ai からインポートします。完全なインポート先は以下の表と、Core のエクスポートリファレンス、React のエクスポートリファレンスに記載しています。

実装手順

1. 移行経路を選ぶ

経路	移行先	変更内容
制限付き製品とその拡張を維持する	`@dataarthub/appkit-core` と `@dataarthub/appkit-react` （GitHub Packages）	パッケージのプレフィックスを変更し、使用する各サブパスと名前付きエクスポートを非公開リリースと照合します。
単独で利用できる公開版の機能範囲に移行する	`@alneas/appkit-core` と `@alneas/appkit-react` （npm）	各 API を機能別のサブパスへ移し、動作の違いを確認し、公開エクスポートに含まれない機能を置き換えます。

これらは異なる配布物です。@dataarthub を @alneas に置き換えても、従来の製品の機能全体が保持されるわけではありません。公開エクスポートのリファレンスに API がない場合は、古い依存を削除する前に、その制限付き実装を維持するか、アプリケーションが所有する代替実装を選択してください。

制限付き配布物の名前変更では、次のプレフィックス変更を想定しています。

旧パッケージ	新しい制限付きパッケージ
`@dataarthub/app-core`	`@dataarthub/appkit-core`
`@dataarthub/react-tools`	`@dataarthub/appkit-react`

たとえば、この経路では /schema/core は引き続き Core のサブパス、/form は React のサブパスです。GitHub Packages のアカウントで実際に利用できるバージョンを選択してください。ソース manifest にバージョンがあるだけでは、公開済みとは確認できません。以下の公開パッケージ向けインストールコマンドと互換性の説明は、公開版への移行だけに適用されます。このガイドは非公開版のリリースやその利用側を保証しません。

2. 公開パッケージをインストールし、レジストリのスコープを分離する

フォームの手順を使用する React アプリケーションの場合:

bun add --exact @alneas/[email protected] @alneas/[email protected] [email protected] [email protected] @tanstack/[email protected]

サーバー専用アプリケーションに必要なのは @alneas/[email protected] と、選択したアダプターの依存関係だけです。機能別のピア依存はエクスポートリファレンスに従ってインストールしてください。ルートパッケージのインストールで、データベース、ストレージのエンドポイント、AI プロバイダーが設定されることはありません。

両方の配布物をアプリケーションに残す場合は、スコープ別のレジストリ振り分けを維持してください。

@alneas:registry=https://registry.npmjs.org
@dataarthub:registry=https://npm.pkg.github.com

GitHub Packages の認証は、アプリケーションの既存の秘密情報管理設定で保持してください。公開パッケージだけを使う利用側には、GitHub Packages の認証情報は不要です。公開パッケージのためにデフォルトレジストリを GitHub Packages へ変更しないでください。レジストリの依存を、隣接するソースへのエイリアスや tarball の上書きに置き換えないでください。

3. React のインポートを機能別のサブパスへ移す

以下は確認すべき移行先のエントリーポイントです。古い再エクスポートの集約ファイル内のすべてのシンボルが、新しいエントリーでも使えるという意味ではありません。

従来のインポート	公開版の移行先
`@dataarthub/react-tools/ui`	`@alneas/appkit-react/ui`
`@dataarthub/react-tools/core`	`@alneas/appkit-react/tools/core`
`@dataarthub/react-tools/form`	`@alneas/appkit-react/tools/form`
`@dataarthub/react-tools/data-table`	`@alneas/appkit-react/tools/data-table`
`@dataarthub/react-tools/data-access/react`	`@alneas/appkit-react/tools/data-access/react`
`@dataarthub/react-tools/filter`	`@alneas/appkit-react/tools/filter`
`@dataarthub/react-tools/pane`	`@alneas/appkit-react/tools/pane`
`@dataarthub/react-tools/workflow`	`@alneas/appkit-react/tools/workflow`
`@dataarthub/react-tools/calendar`	`@alneas/appkit-react/tools/calendar`
`@dataarthub/react-tools/kanban`	`@alneas/appkit-react/tools/kanban`
`@dataarthub/react-tools/gantt`	`@alneas/appkit-react/tools/gantt`
`@dataarthub/react-tools/chart`	`@alneas/appkit-react/tools/chart`
`@dataarthub/react-tools/barcode`	`@alneas/appkit-react/tools/barcode`
`@dataarthub/react-tools/file-browser`	`@alneas/appkit-react/tools/file-browser`
`@dataarthub/react-tools/error`	`@alneas/appkit-react/tools/error`
`@dataarthub/react-tools/i18n`	`@alneas/appkit-react/tools/i18n`
`@dataarthub/react-tools/proposal`	`@alneas/appkit-react/ai/proposal`
`@dataarthub/react-tools/action`	`@alneas/appkit-react/ai/action`
`@dataarthub/react-tools/generative-ui`	`@alneas/appkit-react/ai/generative-ui`
`@dataarthub/react-tools/styles`	`@alneas/appkit-react/styles`

公開の sidebar、header、splash、priority-queue、editable-table の各エントリーにも、同じ /tools/ の移行先パターンを適用します。非公開の認証構成は、公開の /tools/auth ヘルパーエントリーで置き換えられるものではありません。

変更前:

import { FormView } from '@dataarthub/react-tools/form';
import '@dataarthub/react-tools/styles';
import { FormView } from '@alneas/appkit-react/tools/form';
import '@alneas/appkit-react/styles';

公開スタイルシートは、アプリケーションの境界で一度インポートしてください。/dist/react-tools.css、/theme.css、/base.css、/globals.css の公開互換エクスポートはありません。表示される UI に対して独自の CSS 上書きを見直してください。インポートの変更だけでは、見た目が同等であることは証明できません。

4. フレームワークに依存しない Core のインポートと React のバインディングを分離する

従来の Core インポート	公開版の移行先と判断
`@dataarthub/app-core/schema`	`@alneas/appkit-core/data/schema`
`@dataarthub/app-core/schema/core`	`@alneas/appkit-core/data/schema/core`
`@dataarthub/app-core/schema/compiler`	`@alneas/appkit-core/data/schema/compiler`
`@dataarthub/app-core/schema/server`	`@alneas/appkit-core/data/schema/server` （サーバー専用）
`@dataarthub/app-core/data-access`	`@alneas/appkit-core/data` （共通の契約・サービス）
`@dataarthub/app-core/data-access/types`	`@alneas/appkit-core/data/types`
`@dataarthub/app-core/data-access/sqlite`	`@alneas/appkit-core/data/sqlite`
`@dataarthub/app-core/data-access/d1`	`@alneas/appkit-core/data/d1`
`@dataarthub/app-core/storage`	`@alneas/appkit-core/storage`; アダプターの設定を確認
`@dataarthub/app-core/storage/local-adapter`	`@alneas/appkit-core/storage/server`; コンストラクターのオプションを確認
`@dataarthub/app-core/storage/types`	型は次からインポート: `@alneas/appkit-core/storage`
`@dataarthub/app-core/proposal`	`@alneas/appkit-core/ai/proposal`
`@dataarthub/app-core/action`	`@alneas/appkit-core/ai/action`
`@dataarthub/app-core/generative-ui`	`@alneas/appkit-core/ai/generative-ui`
`@dataarthub/app-core/ai`	`@alneas/appkit-core/ai/ai-chat` 会話・チャット API 用。各シンボルを確認
`@dataarthub/app-core/agent-output`	`@alneas/appkit-core/ai/agent-output`
`@dataarthub/app-core/encoding`	`@alneas/appkit-core/data/encoding`
`@dataarthub/app-core/content`	`@alneas/appkit-core/data/content`; Git Markdown は次を使用: `@alneas/appkit-core/data/content/git-markdown`
`@dataarthub/app-core/editor`	`@alneas/appkit-core/data/editor` （JSON・アップロードのヘルパー。エディター UI ではありません）
`@dataarthub/app-core/excel`	汎用アダプター: `@alneas/appkit-core/data/excel`; 日本向けテンプレート: `@alneas/appkit-core/japan/excel`
`@dataarthub/app-core/csv`	汎用の次のものを選ぶ: `@alneas/appkit-core/data/csv` または次の日本向けデフォルト: `@alneas/appkit-core/japan/csv`
`@dataarthub/app-core/finance`	汎用計算: `@alneas/appkit-core/data/finance`; 日本の請求書ルール: `@alneas/appkit-core/japan/finance`
`@dataarthub/app-core/edi`	汎用の契約: `@alneas/appkit-core/data/edi`; 日本の文書変換: `@alneas/appkit-core/japan/edi`
`@dataarthub/app-core/pdf`	汎用データ: `@alneas/appkit-core/data/pdf`; 日本向けプリセット: `@alneas/appkit-core/japan/pdf`; どちらも React の PDF 描画を置き換えません
`@dataarthub/app-core/legal-document`	`@alneas/appkit-core/japan/legal-document`
`@dataarthub/app-core/notifications`	`@alneas/appkit-core/data/notifications` または `@alneas/appkit-core/japan/notifications` を選択
`@dataarthub/app-core/google-calendar`	`@alneas/appkit-core/data/google-calendar`

従来 @dataarthub/react-tools を経由していたフレームワークに依存しないインポートも、対応する React エクスポートを仮定せず Core へ移してください。プロバイダー別のレコードアダプターには、@alneas/appkit-core/data/supabase や @alneas/appkit-core/data/neon などの明示的なエントリーがあります。それぞれのピア依存を別途インストールします。バックエンド SDK、ファイルシステムへのアクセス、認証情報をブラウザー向けのエントリーモジュールに含めないでください。

公開 Core のルートは、名前空間（data、storage、japan、graph、ai、us）をエクスポートします。古い Core のフラットな集約エクスポートを再現するものではありません。機能別の名前付きインポートを推奨します。

import { createAjvValidator } from '@alneas/appkit-core/data/schema/core';
import { CSVGenerator } from '@alneas/appkit-core/japan/csv';
import type { DataAccessAdapter } from '@alneas/appkit-core/data/types';

export const validate = createAjvValidator({ locale: 'ja' });
export const csv = new CSVGenerator();
export function loadRecords(adapter: DataAccessAdapter) {
  return adapter.find('records', {});
}

5. プロバイダーを再接続し、動作を確認する

QueryClientProvider、DataAccessProvider、安定した query クライアント、collection、schema、mode、明示的な検証方針を備えた動作するフォームは、申請フォームの完全な手順を参照してください。onSave を使っても、これらのプロバイダーの要件はなくなりません。非公開の AppProvider は公開 Appkit ではエクスポートされません。代わりに、必要な公開プロバイダーをホストアプリケーションで組み合わせてください。

関連するフックとプロバイダーは同じ配布物からインポートし、互換性のある React ランタイムと query コンテキストを1つに保ち、直接インポートする依存を宣言してください。データベースの移動やバックエンド実装の置き換えをせずに、アプリケーション独自の互換アダプターを公開 UI に渡すことができます。

トラフィックを切り替える前に、次の契約を確認してください。

検証: ロケール、空文字列の扱い、数値の型変換、JSON Schema のドラフトを明示的に選択してください。汎用インポートでも従来の地域別デフォルトが維持されると仮定せず、無効な入力、省略値、デフォルト値を確認します。
地域別の書式: 汎用ヘルパーと日本向けプリセットは役割が異なります。選択するエントリーを変更する場合は、代表的なフィクスチャで CSV の日付書式、請求金額の丸め、税、文書出力を維持してください。
ストレージ: 設定したアダプターに対して、コンストラクターのオプション、オブジェクトキー、URL 生成、失敗時の動作を確認します。公開ストレージ層は Web 標準の署名とランタイム API を使用します。古い SDK クライアントのコンストラクターやコンプライアンスのラッパーを、そのまま交換できると仮定しないでください。
永続化: インポートの変更でレコードが移動したり、マイグレーションが実行されたり、認可が変わったりはしません。接続設定と既存データを維持し、アプリケーションのアダプターに対して読み取り・作成・更新・削除と失敗時の処理を検証してください。
AI: 提案の検証と契約には Core、確認 UI には React を使います。構造化 API の検査やこの移行例は、AI コーディングエージェントが任意のアプリケーションを正しく移行できることを示すものではありません。

6. 切り替え後に従来の依存を削除する

従来のすべてのインポートを公開版の機能範囲へ移したアプリケーションの場合:

bun remove @dataarthub/react-tools @dataarthub/app-core

非公開の機能でまだ使用する制限付き依存は維持してください。アプリケーションのインポートに加え、TypeScript・バンドラー・テストのエイリアス、モック、CSS のインポート、AI 向け指示の参照も更新します。古いソースや tarball の上書きを削除し、アプリケーション自身のパッケージマネージャーでロックファイルを再生成してください。

公開 AI のエントリーポイントは @alneas/appkit-core/ai-instructions と @alneas/appkit-react/ai-instructions で、機械向けコンテキストは各パッケージの /package-context.json にあります。従来の dist/ai/setup.mjs は公開のセットアップ CLI ではありません。非公開の compliance/prepare.mjs も公開パッケージには含まれません。公開パッケージの LICENSE ファイルと React の THIRD_PARTY_NOTICES.md を確認し、残す非公開依存やアプリケーションの依存についても必要な通知を維持してください。

検証

利用側のアプリケーションで次を実施します。

ソース、テスト、設定から @dataarthub/app-core と @dataarthub/react-tools を検索します。残る使用箇所は、すべて意図したものである必要があります。
通常のモジュール解決でアプリケーションの TypeScript 検査を実行します。移行先のサブパスだけでなく、移した各シンボルが存在することを確認してください。
本番ビルドを実行して移行した画面を開きます。プロバイダー、スタイル、検証、ロケール、任意の連携機能の読み込みを確認します。
変更した機能の境界だけを実行検証します。実際のフォームの永続化、アダプターの失敗、関連する文書や CSV の出力を対象にします。入力条件が一致する変更のない統合検証結果は再利用し、移行の試験として本番データへ書き込まないでください。
依存ツリーに従来の依存の残りや、React・query のコンテキストの重複がないかを確認し、移行差分とアプリケーションの検証結果を一緒に保持します。

期待する結果は、アプリケーションがソースエイリアスなしで選択した公開済みパッケージを解決でき、型チェックに通り、明示的なアダプターとプロバイダーを通じて検証済みの動作を維持することです。Appkit の 0.1.0 のリリース検査は、分離した公開パッケージの利用側、型宣言、申請フォームの手順を対象としています。利用するアプリケーション、非公開の拡張、すべてのホストされたプロバイダーを保証するものではありません。このガイドのインポート例は別途検査しており、従来の完全なアプリケーションの移行を実証したとはしていません。

トラブルシューティングとよくある問題

症状	確認すること
パッケージのインストールで 401/404 が返る	公開パッケージは npm を使用します。残す制限付きパッケージには正しい GitHub のスコープと認証情報が必要です。
`Package subpath is not defined by exports`	新しい機能パスを完全に指定してください。古いサブパスや `dist/*` を一括で扱う互換エイリアスはありません。
名前付きエクスポートが見つからない	ルートの集約エクスポートが異なります。エクスポートリファレンスで実際のシンボルを探してください。一部の機能は制限付きのままです。
query・data-access のコンテキストがない	フォームの完全な手順にある公開プロバイダーの組み合わせを使用し、依存インスタンスの重複を確認してください。
UI にスタイルが適用されない	アプリケーションの境界で `@alneas/appkit-react/styles` をインポートしてください。
日付、検証、文書が変わった	ロケール・検証の設定と、適切な汎用または日本向けプリセットのエントリーを明示的に選択してください。
ブラウザービルドにバックエンドのコードが入る	ファイルシステム・SDK・認証情報のインポートをサーバーモジュールへ移し、機能別のエントリーを明示してください。
従来のプロバイダー・エディター・PDF コンポーネントに公開版の対応物がない	制限付き配布物を維持するか、その機能を明示的に置き換えてください。名前空間の変更だけでは不十分です。