目次

パッケージの公開

目次 keyboard_arrow_down keyboard_arrow_up
more_horiz

pub パッケージマネージャーは、他の人のパッケージを使用するためだけのものではありません。また、自分のパッケージを世界と共有することもできます。便利なプロジェクトがあり、他の人がそれを使用できるようにしたい場合は、dart pub publish コマンドを使用します。

パッケージのビルドと公開の概要については、次のビデオをご覧ください。


Dart でパッケージを構築する方法

注意: 公開は永続的です

#

公開されたパッケージは永遠に続くことを覚えておいてください。パッケージを公開するとすぐに、ユーザーはそれに依存することができます。ユーザーがそれに依存し始めると、パッケージを削除するとユーザーの環境が壊れてしまいます。それを避けるために、pub.dev ポリシーでは、ごくわずかな例外を除き、パッケージの公開取り消しは許可されていません。

パッケージの新しいバージョンをいつでもアップロードできますが、古いバージョンはまだアップグレードできないユーザーのために引き続き利用できます。

関連性が失われた、またはメンテナンスが不足している公開済みパッケージについては、廃止としてマークしてください。

公開用にパッケージを準備する

#

パッケージを公開するときは、pubspec 形式と パッケージレイアウト構造にある規約に従ってください。パッケージの使用を簡単にするために、Dart はこれらの規約を要求しています。これらの規約には、リンク先のガイドに記載されているいくつかの例外が含まれています。呼び出されると、pub は、Dart エコシステム内でパッケージがより良く機能するように、どのような変更を加えることができるかを指摘します。

これらの規約に加えて、次の要件に従う必要があります

  • パッケージに LICENSE ファイルを含めます。Dart および Flutter チームが通常使用している BSD 3 条項ライセンスをお勧めします。ただし、パッケージに適した任意のライセンスを使用できます。

  • パッケージの一部としてアップロードするものを再配布する法的権利があることを確認してください。

  • gzip 圧縮後、パッケージサイズを 100 MB 未満に保ちます。サイズが大きすぎる場合は、複数のパッケージに分割するか、不要なコンテンツを削除するために .pubignore ファイルを使用するか、含まれるリソースまたは例の数を減らすことを検討してください。

  • パッケージが、デフォルトの pub パッケージサーバーと SDK の依存関係 (sdk: flutter) からホストされている依存関係のみに依存するようにします。これらの制限により、パッケージの依存関係が将来見つかり、アクセスできるようになります。

  • Google アカウントを所有していること。Pub は、パッケージのアップロード権限を管理するために Google アカウントを使用します。Google アカウントは、Gmail アドレスまたはその他の任意のメールアドレスに関連付けることができます。

pub.dev の Web ページを作成する

#

Pub は、いくつかのファイルの内容を使用して、pub.dev/packages/<your_package> にパッケージのページを作成します。次のファイルは、パッケージの Web ページの内容に影響を与えます。

README.md
このファイルには、パッケージの Web ページで主要なコンテンツが表示されます。ファイルの内容は、Markdown を使用してマークアップする必要があります。優れた README の書き方については、パッケージページの作成をご覧ください。
CHANGELOG.md
見つかった場合、このファイルはパッケージの Web ページに独自のタブを表示します。開発者は、pub.dev から直接変更内容を読むことができます。ファイルの内容は、Markdown を使用してマークアップする必要があります。
pubspec.yaml
このファイルは、パッケージの Web ページの右側にパッケージの詳細を表示します。ファイルの内容は、YAML の規約に従う必要があります。これらの詳細には、説明、ホームページなどが含まれます。

認証済みパブリッシャーを使用する利点

#

認証済みパブリッシャー (推奨) または独立した Google アカウントを使用してパッケージを公開できます。認証済みパブリッシャーを使用すると、次の利点があります

  • パッケージの利用者は、パブリッシャーのドメインが認証されていることを知っています。
  • pub.dev に個人のメールアドレスを表示することを回避できます。代わりに、pub.dev はパブリッシャーのドメインと連絡先アドレスを表示します。
  • pub.dev サイトでは、検索ページと個々のパッケージページで、パッケージ名の横に認証済みパブリッシャーバッジ pub.dev の認証済みパブリッシャーロゴ が表示されます。

認証済みパブリッシャーを作成する

#

認証済みパブリッシャーを作成するには、次の手順に従います

  1. pub.dev に移動します。

  2. Google アカウントを使用して pub.dev にログインします。

  3. 右上隅のユーザーメニューから、パブリッシャーを作成を選択します。

  4. パブリッシャーに関連付けるドメイン名を入力します (例: dart.dev)。

  5. パブリッシャーを作成をクリックします。

  6. 確認ダイアログで、OK を選択します。

  7. プロンプトが表示されたら、認証フローを完了します。これにより、Google Search Console が開きます。

    • DNS レコードを追加すると、Search Console に変更が反映されるまで数時間かかる場合があります。
    • 認証フローが完了したら、手順 4 に戻ります。

パッケージを公開する

#

dart pub publish コマンドを使用して、パッケージを初めて公開するか、新しいバージョンに更新します。

どのファイルが公開されるか？

#

公開されたパッケージには、パッケージのルートディレクトリの下にある すべてのファイル が含まれます。ただし、次の例外があります

  • 隠しファイルまたはディレクトリ。これらの名前はドット (.) で始まります。
  • .pubignore または .gitignore ファイルで無視するようにリストされているファイルとディレクトリ

git と dart pub publish で異なる無視ルールを使用するには、特定のディレクトリで .gitignore ファイルを上書きするために .pubignore ファイルを作成します。ディレクトリに .pubignore ファイルと .gitignore ファイルの両方が含まれている場合、dart pub publish はそのディレクトリの .gitignore ファイルを 無視 します。.pubignore ファイルは、.gitignore ファイルと同じ形式に従います。

不要なファイルの公開を避けるには、次の方法に従ってください

  • 含めたくないファイルを削除するか、.pubignore または .gitignore ファイルに追加します。
  • パッケージをアップロードするときは、dart pub publish --dry-run が公開すると表示するファイルのリストを調べます。不要なファイルがリストに表示された場合は、アップロードをキャンセルします。

パッケージの公開をテストする

#

dart pub publish がどのように機能するかをテストするには、ドライランを実行できます

$ dart pub publish --dry-run

このコマンドを使用すると、dart pub は次のタスクを実行します

  1. パッケージが pubspec 形式と パッケージレイアウトの規約に従っていることを確認します。

  2. 公開するすべてのファイルを表示します。

次の例は、transmogrify という名前のパッケージを公開する場合を示しています

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart

Package has 0 warnings.

pub.dev に公開する

#

パッケージの公開準備が完了したら、--dry-run 引数を削除してください。

$ dart pub publish

このコマンドを使用すると、dart pub は次のタスクを実行します

  1. パッケージが pubspec 形式と パッケージレイアウトの規約に従っていることを確認します。

  2. 公開するすべてのファイルを表示します。

  3. pub.dev にパッケージをアップロードします。

パッケージが pub.dev へのアップロードに成功すると、pub のすべてのユーザーがダウンロードしたり、プロジェクトで依存関係として使用したりできます。

たとえば、transmogrify パッケージのバージョン 1.0.0 を公開した場合、別の Dart 開発者は、それを pubspec.yaml 内の依存関係として追加できます。

yaml
dependencies:
  transmogrify: ^1.0.0

サポートされているプラットフォームを検出する

#

pub.dev サイトは、パッケージがサポートするプラットフォームを検出し、これらのプラットフォームをパッケージページに表示します。pub.dev のユーザーは、プラットフォームで検索をフィルタリングできます。

サポートされるプラットフォームの生成されたリストを変更するには、pubspec.yaml ファイルでサポートされるプラットフォームを指定してください。

公開を自動化する

#

パッケージの最初のバージョンを公開したら、GitHub Actions または Google Cloud サービスアカウントを使用して、自動公開を構成できます。自動公開の詳細については、pub.dev へのパッケージの自動公開を参照してください。

プレリリースバージョンを公開する

#

パッケージの開発中に、プレリリースとして公開することを検討してください。プレリリースは、次のような場合に役立ちます。

  • パッケージの次のメジャーバージョンを積極的に開発している場合。
  • パッケージの次のリリース候補のベータテスターが必要な場合。
  • パッケージが Dart または Flutter SDK の不安定なバージョンに依存している場合。

セマンティックバージョニングで説明されているように、バージョンのプレリリースを作成するには、バージョンにサフィックスを追加します。たとえば、バージョン 2.0.0 のプレリリースを作成するには、バージョン 2.0.0-dev.1 を使用します。後でバージョン 2.0.0 をリリースすると、すべての 2.0.0-XXX プレリリースよりも優先されます。

pub は利用可能な場合は安定版リリースを優先するため、プレリリースパッケージのユーザーは、依存関係の制約を変更する必要がある場合があります。たとえば、ユーザーがバージョン 2.1.0 のプレリリースをテストする場合、^2.0.0 または ^2.1.0 の代わりに ^2.1.0-dev.1 を指定する場合があります。

プレリリースを pub.dev に公開すると、パッケージページにはプレリリースと安定版リリースの両方へのリンクが表示されます。プレリリースは、分析スコアに影響を与えたり、検索結果に表示されたり、パッケージの README.md やドキュメントを置き換えたりすることはありません。

プレビューバージョンを公開する

#

プレビューは、次のすべてが当てはまる場合に役立ちます。

  • パッケージの次の安定バージョンが完了している。
  • そのパッケージバージョンが、Dart SDK の安定バージョンでまだリリースされていない Dart SDK の API または機能に依存している。
  • パッケージが依存している API または機能が API として安定しており、安定版 SDK に到達する前に変更されないことを知っている。

例として、完成したバージョン 2.0.0 を持つ package:args の新しいバージョンを考えてみましょう。これは Dart 3.0.0-417.1.beta の機能に依存しています。ただし、Dart SDK の安定バージョン 3.0.0 はまだリリースされていません。pubspec.yaml ファイルは次のようになります。

pubspec.yaml
yaml
name: args
version: 2.0.0

environment:
  sdk: '^3.0.0-417.1.beta'

このパッケージを pub.dev に公開すると、プレビューバージョンとしてタグ付けされます。次のスクリーンショットはこれを示しています。安定版バージョンを 1.6.0、プレビューバージョンを 2.0.0 としてリストしています。

Illustration of a preview version

Dart が 3.0.0 の安定バージョンをリリースすると、pub.dev はパッケージリストを更新して、2.0.0 をパッケージの最新（安定）バージョンとして表示します。

このセクションの冒頭にあるすべての条件が当てはまる場合は、dart pub publish からの次の警告を無視してください。

"Dart SDK のプレリリースに対する SDK 制約を持つパッケージは、それ自体をプレリリースバージョンとして公開する必要があります。このパッケージに Dart バージョン 3.0.0-0 が必要な場合は、代わりにパッケージをプレリリースとして公開することを検討してください。"

公開権限を管理する

#

パッケージのパブリッシャーを特定する

#

パッケージに認証済みのパブリッシャーがある場合、そのパッケージの pub.dev ページには、パブリッシャーのドメインが表示されます。

パブリッシャーなしで公開されたパッケージの場合、pub.dev はプライバシー上の理由からパブリッシャーを開示しません。パブリッシャーフィールドには、「未認証のアップローダー」と表示されます。

パッケージのアップローダーを管理する

#

パッケージの最初のバージョンを公開した人が、そのパッケージの追加バージョンをアップロードする最初のそして唯一の権限を持つ人になります。

他の人がバージョンをアップロードすることを許可または禁止するには、次のいずれかを行います。

  • パッケージの管理ページで、認証済みアップローダーを管理します：https://pub.dev/packages/<package>/admin。
  • パッケージを認証済みのパブリッシャーに移行します。パブリッシャーのすべてのメンバーがアップロードする権限を持っています。

パッケージを認証済みパブリッシャーに移行する

#

パッケージを認証済みのパブリッシャーに移行するには、パッケージのアップローダーであり、認証済みのパブリッシャーの管理者である必要があります。

パッケージを認証済みのパブリッシャーに移行するには

  1. パッケージのアップローダーとしてリストされている Google アカウントで pub.dev にログインします。

  2. パッケージの詳細ページ（たとえば、https://pub.dev/packages/http）に移動します。

  3. 管理者タブを選択します。

  4. パブリッシャーの名前を入力し、パブリッシャーに移行をクリックします。

パッケージを管理する

#

パッケージバージョンを撤回する

#

新しいパッケージの消費者が公開されたパッケージのバージョンを7日以内に採用するのを防ぐために、公開後7日以内にそのパッケージバージョンをリトラクトできます。リトラクトされたバージョンは、リトラクト後7日以内に再度復元できます。

リトラクトは削除ではありません。リトラクトされたパッケージバージョンは、pub.dev のパッケージのバージョンリストのリトラクトされたバージョンセクションに表示されます。そのパッケージバージョンの詳細ビューには、リトラクト済みバッジが表示されます。

パッケージをリトラクトする前に、代わりに新しいバージョンを公開することを検討してください。パッケージをリトラクトすると、パッケージユーザーに悪影響を与える可能性があります。

依存関係の制約が欠落しているか依存関係の制約が緩い新しいバージョンを公開する場合、パッケージバージョンのリトラクトが唯一の解決策となる可能性があります。パッケージの新しいバージョンを公開しても、バージョンソルバーが古いバージョンを選択するのを止めることはできません。そのバージョンが pub が選択できる唯一のバージョンである可能性があります。不正な依存関係制約を持つパッケージバージョンをリトラクトすると、ユーザーは他の依存関係をアップグレードするか、依存関係の競合が発生するかのいずれかになります。

ただし、パッケージに軽微なバグが含まれている場合は、バージョンをリトラクトする必要がない場合があります。バグが修正された新しいバージョンと、CHANGELOG.md に修正されたバグの説明を公開します。これにより、ユーザーは何が起こったかを理解できます。新しいバージョンを公開することは、パッケージユーザーへの混乱を軽減します。

リトラクトされたパッケージのバージョンの使い方

#

パッケージが後でリトラクトされたパッケージバージョンに依存している場合でも、そのバージョンが依存パッケージの pubspec.lock ファイル内にある限り、そのバージョンを使用できます。すでにリトラクトされている特定のバージョンに依存するには、依存パッケージが pubspec.yaml ファイルの dependency_overrides セクションでそのバージョンをピン留めする必要があります。

リトラクトされたパッケージのバージョンから移行する方法

#

パッケージがリトラクトされたパッケージのバージョンに依存している場合、他の利用可能なバージョンに応じて、このバージョンから移行する方法を選択できます。

新しいバージョンにアップグレードする

#

ほとんどの場合、リトラクトされたバージョンを置き換えるために新しいバージョンが公開されています。この場合は、dart pub upgrade <package> を実行します。

最新のリトラクトされていないバージョンにダウングレードする

#

新しいバージョンが利用できない場合は、最新のリトラクトされていないバージョンへのダウングレードを検討してください。これは、次の 2 つの方法のいずれかで実行できます。

  1. pub ツールコマンドを使用する

    1. dart pub downgrade <package> を実行して、pubspec.yaml ファイルの制約に一致する、指定されたパッケージの最低バージョンを取得します。

    2. dart pub upgrade <package> を実行して、利用可能な最新の互換性がありリトラクトされていないバージョンを取得します。

  2. お好みの IDE で pubspec.lock ファイルを編集する

    1. リトラクトされたバージョンを持つパッケージのパッケージエントリ全体を削除します。

    2. dart pub get を実行して、利用可能な最新の互換性がありリトラクトされていないバージョンを取得します。

pubspec.lock ファイルを削除して dart pub get を実行することもできますが、これは推奨されません。これにより、他の依存関係のバージョンが変更される可能性があります。

指定されたバージョン制約外のバージョンにアップグレードまたはダウングレードする

#

現在のバージョン制約を満たす代替バージョンがない場合は、pubspec.yaml ファイルでバージョン制約を編集し、dart pub upgrade を実行します。

パッケージのバージョンをリトラクトまたは復元する方法

#

パッケージのバージョンをリトラクトまたは復元するには、まず、パッケージのアップローダーまたは認証済みのパブリッシャー管理者である Google アカウントを使用して pub.dev にサインインします。次に、パッケージの管理者タブに移動すると、最近のパッケージバージョンをリトラクトまたは復元できます。

パッケージを廃止する

#

パッケージは公開されたままですが、パッケージがアクティブなメンテナンスを受けていないことを開発者に通知できます。これには、パッケージを廃止としてマークする必要があります。

パッケージを廃止すると、パッケージは次のようになります。

  • pub.dev で公開されたままになります。
  • pub.dev で表示可能なままになります。
  • 明確な 廃止 バッジが表示されます。
  • pub.dev の検索結果には表示されません。

パッケージを廃止としてマークするには

  1. パッケージのアップローダーまたは認証済みのパブリッシャー権限を持つ Google アカウントを使用して、pub.dev にサインインします。

  2. パッケージの管理者タブに移動します。

  3. パッケージを廃止するには、「廃止」としてマークを選択します。

代替パッケージを推奨することもできます。

  1. 推奨される代替の下のフィールドに、別のパッケージの名前を入力します。

  2. 「推奨される代替」を更新をクリックします。

気が変わった場合は、いつでも廃止マークを削除できます。

特に明記されていない限り、このサイトのドキュメントは Dart 3.5.3 を反映しています。ページは 2024-10-22 に最終更新されました。 ソースを表示 または 問題を報告する。