dart-package-management

Dart パッケージの管理

目次

• パッケージのディレクトリ構成の規約
• Pubspec の設定
• モノレポのワークスペース
• ワークフロー
• 例

パッケージのディレクトリ構成の規約

ツールとの互換性を確保し、API の境界を明確にするため、標準化されたディレクトリ構成で Dart パッケージを整理します。

• lib/：公開ライブラリとアセットを配置します。公開 API のみをエクスポートします。
• lib/src/：内部実装ファイルを配置します。他のパッケージの lib/src/ からインポートしないでください。自分のパッケージ内で lib/src/ から lib/ にインポートする場合は、相対インポートを使用します。
• bin/：公開するコマンドライン実行ファイルを配置します。
• tool/：内部スクリプトやツール（コード生成、ドキュメント用スクリプトなど）を配置します。
• test/：ユニットテストを配置し、ファイル名の末尾を _test.dart にします。
• integration_test/：時間のかかる統合レベルのテストを配置します。
• example/：パッケージの使用方法を示す、単独で実行可能なサンプルプログラムを配置します。親パッケージを参照するには package: インポートを使用します。
• web/：Web 固有のエントリーポイント（main.dart）とアセット（index.html、CSS）を配置します。
• hook/：SDK のビルドフック（build.dart など）を配置します。

Pubspec の設定

各パッケージのルートに、有効な pubspec.yaml を用意します。

• バージョン制約：依存関係のバージョン制約にはキャレット構文（^）を使用し（例：^3.2.0）、互換性を損なわない更新を許可します。
• SDK 制約：下限の SDK 制約を指定した environment を必ず定義します。
• 公開アセット：パッケージに必要な公開アセット（画像、フォント）をすべて明示的に列挙します。
• 実行ファイル：bin/ のスクリプトを executables フィールドでコマンド名に対応付けます。
• メタデータ：公開するパッケージには name、version、description、repository、issue_tracker を含めます。
• トピック：topics フィールドを使用して公開するパッケージを分類します（最大 5 件、小文字の英数字とハイフンを使用）。
• 誤検出されるシークレット：pub の公開前の漏えい検出で誤検出を防ぐため、gitignore パターンを指定した false_secrets フィールドを使用します。

モノレポのワークスペース

モノレポでワークスペースを実装し、ローカルパッケージ間で依存関係を共有することで、メモリ使用量を削減し、バージョンの一貫性を確保します。

• ルート Pubspec：リポジトリのルートでワークスペースを定義します。publish_to: none を設定し、SDK のバージョンを ^3.6.0 以上に指定して、glob パターン（例：packages/*）を使って workspace フィールドを設定します。
• 子 Pubspec：各ワークスペースパッケージで SDK のバージョンを ^3.6.0 以上に指定し、resolution: workspace を設定します。
• 相互依存関係：他のワークスペースパッケージに通常どおり依存します。Pub は自動的にローカルのワークスペースバージョンを解決します。
• オーバーライド：ワークスペース全体に適用するには、dependency_overrides をルートの pubspec.yaml に配置します。

ワークフロー

モノレポのワークスペースを設定する

標準的なリポジトリを Dart ワークスペースに変換するには、このチェックリストを使用します。

• ルートに pubspec.yaml を作成します。
• ルートの pubspec で publish_to: none と environment: sdk: ^3.6.0 を設定します。
• glob パターン（例：- packages/*）を使って、ルートの pubspec に workspace: フィールドを追加します。
• すべての子 pubspec.yaml ファイルに environment: sdk: ^3.6.0（またはそれ以上）を設定します。
• すべての子 pubspec.yaml ファイルに resolution: workspace を追加します。
• リポジトリのルートで dart pub get を実行します。
• フィードバックループ：バリデーターを実行 -> エラーを確認 -> 修正します。子ディレクトリに余分な pubspec.lock や .dart_tool/package_config.json ファイルがないことを確認します。解決に失敗する場合は、子パッケージ間で競合する依存関係のバージョンを揃えます。

依存関係を管理する

• dart pub get を実行して依存関係を取得し、package_config.json を生成します。
• dart pub upgrade を実行して、互換性のある最新バージョンに依存関係を更新します。
• pubspec.lock をコミットするのはアプリケーションパッケージのみです。ライブラリパッケージでは含めません。

例

Standard Library Pubspec

name: enchilada
description: A comprehensive toolkit for newt transmogrification.
version: 1.2.3
repository: https://github.com/example/enchilada
issue_tracker: https://github.com/example/enchilada/issues

environment:
  sdk: ^3.6.0

dependencies:
  path: ^1.8.0
  transmogrify: ^0.4.0

dev_dependencies:
  test: ^2.0.0
  lints: ^3.0.0

executables:
  enchilada: main

topics:
  - transmogrification
  - utilities

Workspace Root Pubspec

name: my_monorepo
publish_to: none

environment:
  sdk: ^3.6.0

workspace:
  - packages/*

# Apply overrides globally across all workspace packages
dependency_overrides:
  transmogrify: ^0.5.0-dev

Workspace Child Pubspec

name: client_package
description: The client application for the monorepo.
version: 1.0.0
publish_to: none

environment:
  sdk: ^3.6.0

resolution: workspace

dependencies:
  shared_package: ^1.0.0 # Resolves locally within the workspace
  http: ^1.1.0