ライブラリ用のAngular Schematics: プロジェクトを最新の状態に保つ

角度回路図とは何ですか、そしてその利点は何ですか?ng add と ng update を最大限に活用して、Angular schematics を使用してライブラリを改善する方法を学びます。

V Slavov Last Updated Feb 19, 2025 13min read

Angular回路図はしばらく前から存在しており、私たちのほとんどはそれらを使用して作業し、その多くの利点を享受することに慣れていると思います。単純な新規機能の実行から、ワークフローやプロジェクトのセットアップを自動化する複雑な回路図の作成まで、回路図エンジンはAngularアプリケーションのライフサイクルの大部分を占めています。

しかし、Angular図書館はどうでしょうか?

Infragisticsでは、オープンソースのAngularコンポーネントライブラリの開発と保守に大きな誇りを持っています。しかし、図書館の利用者が増え、Angularの性質が進化し続ける中、プロジェクトを最新の状態に保つための簡単な方法を提供する必要がありました。ここで、Angularほとんどのものと同様に、回路図が重要になります。

ng add, ng update and more

このブログでは、Angular CLI の ng add コマンドと ng update コマンドを最大限に活用できるようにライブラリを設定する方法を紹介します。これを行うには、スケマティックコレクションを特定の方法で定義します。

Disclaimer:

この投稿を最大限に活用するには、理想的には、Angular回路図の基本にすでに精通している必要があり、次のいくつかに興味があるかもしれません。他すごい楨ミディアムで。

最近の angular.io 記事から借りると:

回路図は、複雑なロジックをサポートするテンプレートベースのコードジェネレータです。これは、コードを生成または変更してソフトウェアプロジェクトを変換するための一連の命令です。回路図はコレクションにパッケージ化され、npm と共にインストールされます。

Try Ignite UI for Angular

Angular Schematicsとは何ですか?

回路図は、Angular CLIのビルディングブロックです。これらは、既存のファイルに対して操作を実行したり、ファイル/コンテンツを生成したりする実行可能な命令セットです。あなたがAngular開発者であれば、おそらく以下を実行してコンポーネントを作成したことでしょう。

ng g c [component name]

スケマティックはAngularエコシステムの大部分を占めており、スケマティックをよりよく理解することで、あなたとあなたのユーザーの両方の生活を大幅に改善することができます。

角度の簡単なチュートリアルを見ていきますので、深く掘り下げる前に基本に慣れることができます。

Angular Schematics の記述方法

Angular 独自のschematics cliを利用することで、独自の回路図の作成をすぐに開始できます。

以下を実行するだけで、グローバルにインストールできます。

npm install -g @angular-devkit/schematics-cli

次に、次のように呼び出して、すぐに使用できる空白のサンプル回路図を作成します。

schematics blank --name=intro-schematic

生成されたファイルを調べると、それらを調べて、回路図が使用者にどのように公開されているかを正確に調べることができます。

package.jsonファイルでは、「schematics」プロパティがあり、「collection.json」を指していることがわかります
そのパスをたどると、そのファイルを調べることができます - これはかなり標準的な.jsonファイルであり、1つの重要な点があります - 「schematics」プロパティ、これはユーザーに公開されているすべての回路図のリストです。
上記の例のコマンドを実行した直後は、リストには「Intro schematics」という1つのエントリのみが含まれている必要があります。エントリには、簡単な説明と「ファクトリ」への参照が含まれています – これが回路図の本体が定義される場所です。
参照された「index.ts」ファイルでは、回路図の「本体」が定義されています。これは、消費するプロジェクトのコンテキストで実行され、すべてのカスタムロジックが存在する「ルール」です

プロジェクトの外部から example を呼び出すには、次のようにします。

ng g [path-to-collection.json]:intro-schematics

しかし、スケマティックを呼び出す方法はそれだけではありません。Angular、ユーザーのエクスペリエンスをさらに自動化できる便利な「フック」を開発者に提供しています。

Angular Schematicのエントリポイント

通常のAngular schematicを呼び出す以外に、

ng g my-custom-library:schematics [args]

Angularの CLI は、カスタムライブラリワークフローの他の 2 つのエントリポイント (ng add と ng update) も提供します。これらのngコマンドに詳しくない場合は、こちらとこちらで詳細を確認できます。ライブラリを使用しているAngularアプリケーションでは、これらはnpmのpostinstallフックと同様に機能します。これらは、Angular CLI によって自動的に呼び出されます (

ng add my-custom-library

又は

ng update my-custom-library

それぞれ。

Migration Schematics

Angular の CLI を使用する主な利点の 1 つは、パッケージの依存関係を更新しながら、破壊的な変更や非推奨を手動で回避する必要性を最小限に抑えることです。これらはすべて、ライブラリの移行スキーマを定義することで自動化できます。

移行スキーマは、ng update your-custom-library を介して新しいバージョンのライブラリが消費アプリケーションに追加されるたびに実行されます。移行スケマティックでは、移行スケマティックが実行する変更を定義するだけでなく、移行の範囲 (影響を受けるバージョン) も指定できます。

Adding migration schematics

移行スケマティックの定義は、通常のスケマティックの定義と同様の方法で行われます — ルールを返す関数を作成する必要があります。このルールは、ワークツリーを操作したり、ログを作成したり、Javascriptでできることを何でも操作できます。より具体的な部分は、Angular CLIがng updateフックで回路図を呼び出すことを確認することです。

Defining the schematics collection

まず、回路図collection.jsonファイルを定義する必要があります。名前は関係ありません。私たちのライブラリの場合、複数の概略図コレクションがあり、これによりどれがどれであるかを簡単に見分けることができるため、migration-collection.jsonと名付けました。

collection.jsonの構造は次のようになります。

{
    "schematics": {
        "migration-01": {
            //  Migration name, no strict naming, must be unique
            "version": "2.0.0", // The target version
                "description": "Updates my-custom-library from v1 to v2", // A short description, not mandatory
                "factory": "./update-2" // The update schematic factory
        }

        ,
        "migration-02": {
            "version": "3.0.0",
                "description": "Updates my-custom-library from v2 to v3",
                "factory": "./update-3"
        }

        ,

        ...
    }
}

schematics オブジェクトには、更新するすべてのスケマティック定義が格納されます。各定義は名前付きプロパティ(一意である必要があります)の下にあり、それぞれについて、「変更」が導入されるバージョンと、作業ツリーで実行される回路図のファクトリを指定する必要があります。バージョン属性は、スケマティックをいつ実行する必要があるかを決定するために使用されます。

たとえば、my-custom-library@1.0.0 を使用するアプリがあるとします。上記の回路図定義では、ng update my-custom-library@2.0.0を実行すると、定義された "version": "6.0.0" 回路図のみが実行されます。実行時

ng update my-custom-library@3.0.0

2.0.0 と 3.0.0 の両方の移行スキーマが実行されます。

移行スケマティックの実際の定義 (v2.0.0 など) は ./update-2/index.ts にあり、他のスケマティックと同様に使用できます。非常に基本的な実装は、次のようになります。

export default function(): Rule {
  return (host: Tree, context: SchematicContext) => {
    const version = `1.0.0` // You can get this dynamically from the package.json
    context.logger.info(`Applying migration for custom library to version ${version}`);

    return host;
  };
}

最新の移行回路図の 1 つの定義は、 igniteui-angularにあります (詳細を見る)。.

免責事項:ライブラリの概略実装では、ファイルの操作にTypeScript言語サービスを多用しています。詳細に立ち入らないのは申し訳ありませんが、それはそれ自体が投稿を保証するでしょう。ご不明な点がございましたら、コメント欄でお気軽にお問い合わせください、そして私はできる限り最善を尽くして答えようとします。

schematics コレクションをng-updateフックにアタッチする

移行collection.jsonが作成され、移行回路図が定義されたら、あとはそれらをng-updateフックに適切にアタッチするだけです。そのために行う必要があるのは、ライブラリのpackage.jsonに移動して、次の「ng-update」プロパティを追加することです。

{
    "name": "my-custom-library",
    "version": "2.0.0",
    ... "ng-update": {
        "migrations": "./migrations/migration-collection.json"
    }
}

それです！これで、誰かが ng update my-custom-library を実行するたびに、Angular CLI と慎重に作成した回路図が、ユーザーが見逃す可能性のある厄介な破壊的変更や非推奨を処理します。

ng-add

Angular CLI が提供するもう 1 つの便利なエントリポイントは、ng add フックです。ng add schematic を定義すると、ユーザーがライブラリを消費するプロジェクトに追加するとすぐに、

ng add [custom-library]

これは、npm の postinstall フックのようなものと考えることができます。

ライブラリのng addスケマティックを定義することは、ユーザーが初めて簡単に体験できるようにするための最良の方法です。回路図を通じて、必須の初期設定を自動化したり、パッケージを追加/更新したり、すべてのユーザーに「ありがとう!」と大々的に伝えたりすることができます。🙂

私たちのライブラリには、IgniteUI CLIをプロジェクトワークスペースにインストールするng addスケマティックを追加して、ユーザーがCLIを介してコンポーネントスイートを最大限に活用できるようにしました。
ワークスペースへの初期変換 (CLI の実行に必要なカスタム .json ファイルの追加)、いくつかのスタイルとパッケージの追加 (コンポーネントを適切にレンダリングするため)、さらには CLI からいくつかの回路図を呼び出す (schematiception!) 。Angular CLI 固有のロジックの一部をオフロードしました。

これらすべて(およびそれ以上の)は、ng addを呼び出すだけで自動的に実行できます-私の意見では、それがAngular CLIの真の魅力です。

ng-addスケマティックを作成する

ライブラリに ng add schematic を追加するには、まずそれを定義する必要があります。他の回路図と同様に、コレクションの一部である必要があります。プロジェクトがすでに回路図を公開している場合は、ng-add という名前で既存のコレクションに追加できます。そうでない場合は、コレクションを最初から作成できます。

ライブラリのルートフォルダで、次の操作を行います。

mkdir schematics && cd schematics

echo blank > collection.json

mkdir ng-add

新しく作成したcollection.jsonを開き、ng-add回路図の定義を指すように変更します

{
    "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
    "schematics": {
        "ng-add": {
            "description": "Installs the needed dependencies onto the host application.",
                "factory": "./ng-add/index",
                "schema": "./ng-add/schema.json"
        }
    }
}

schematics/ng-add/index.ts の下で、他の回路図と同じように ng-add 回路図の実装を作成できます。たとえば、ユーザーに「ありがとう!」というシンプルなメッセージを表示するには、次の操作を行います。

export default function (options: Options): Rule {
	return (_tree: Tree, context: SchematicContext) => {
		context.logger.info(`Thank you for using our custom library! You're great!`);
	};
}

IgniteUI Angular の ng-add 回路図の実装は、こちらでご覧いただけます。

package.jsonに含める

回路図の実装が完了したら、ライブラリのpackage.jsonにコレクション定義を含める必要があります。あなたのライブラリがすでに回路図コレクションを公開している場合は、これをカバーしています。そうでない場合は、新しく作成したcollection.jsonの場所を指す「schematics」プロパティを追加するだけです。

{
    "project": "my-custom-library",
    "version": "2.0.0",
    ... "schematics": "./schematics/collection.json"
}

セットアップのこの部分は、ライブラリリポジトリに反映されています。

Bundling your schematics

定義した回路図(migrationsとng-addコレクションの両方)がライブラリパッケージに適切に付属していることを確認する必要があります。これを行うには、回路図に対して別のビルドタスク (メインビルドタスクの実行後に実行) を定義し、outDir をプロジェクトの dist フォルダ内の適切な場所を指すように指定する必要があります (したがって、collection.json ファイルは package.json に対して同じパスを持ちます)。最後に、コンパイラによって除外されたファイル (.json ファイルなど) を明示的にコピーする必要があります。

コンパイル済みプロジェクトの出力ディレクトリが ../dist (つまり、プロジェクトのバンドルされたファイルは ../dist/my-custom-lib/) 回路図のコンパイル出力は ../dist/schematics (デフォルトの回路図コレクション用、ng-add を含む) と ../dist/migrations (移行の概略図集用)

これを行うには、まず、スケマティックコレクションの tsconfig.json ファイル (それぞれ ./schematics/ または ./migrations) を定義する必要があります。たとえば、コアスケマティックコレクション (./schematics) のファイルの内容は、次のようになります。

{
   "compilerOptions": {
	"target": "es6",
	"module": "commonjs",
	"sourceMap": false,
	"composite": true,
	"declaration": true,
	"outDir": "../../../dist/my-custom-lib/schematics/"
   }
}

次に、プロジェクトのpackage.jsonで、回路図をビルドするスクリプトと、ファイルをコピーするスクリプトを定義します。

{
   "name": "my-custom-library",
   ...
   "scripts": {
      "build:schematics": "tsc --project migrations/tsconfig.json",
      "copy:schematics:collection": "cp --parents migrations/*/collection.json ../../dist/my-custom-lib/"
   },
   ...
}

移行についても同じことが言えます - TypeScriptコンパイル用とファイルコピー用の別々のスクリプトです。

Ignite UI for Angularリポジトリの場合は、リンクを確認して、既定のスケマティックコレクションの実装と移行を確認できます。(ビルドツールとしてgulpを使用しているため、collection.jsonファイルをコピーするための個別のタスクを定義しています)

ng-add および ng-update 回路図をローカルで実行する

新しくて光沢のある ng update と ng add 機能を使用してライブラリパッケージを公開する前に、回路図が適切なワークプレイス変換を実行していることを確認したい場合があります。結局のところ、これらは両方とも基本的な回路図の実装にすぎないため、他のものと同じように ng g を使用して実行できます。

ライブラリファイルと回路図+マイグレーションをビルドした後、指定した出力ディレクトリ(バンドルのpackage.jsonが配置されている場所)に移動してパックできます

npm pack

Running ng-add

新しいプロジェクト内でng-add isコマンドがどのように実行されているかを確認するには、次の操作を行います。

Angular CLI を使用した新しいプロジェクトの作成

ng g my-test-project --routing=true

プロジェクトが作成されたら、プロジェクトフォルダに移動して、.tgzファイルからパッケージを手動でインストールできます。

npm i my-custom-library.tgz

Then, simply run

ng g my-custom-library:ng-add

そして、それが終わったらワークプレイスの変更を確認します - それがあなたのパッケージのng-addが行うことです!

Running migrations

移行をテストするには、上記と同じ手順に従うことができますが、移行スケマティックcollection.jsonへのパスを指定する必要があります (プロジェクトのデフォルトのスケマティックコレクションとは異なるため)。

テストする最新の移行スキーマの名前が update-1 であるとします。.tgzファイルを手動でインストールしたら、次のコマンドを実行するだけです。

ng g "./node_modules/my-custom-library/migration-collection.json:update-1"

これにより、最新の移行スキーマが適用されるすべてのワークプレイスの変更が適用されます。

締めくくりの感想

うまくいけば、この投稿があなたにとって役に立ち、Angular CLIのngaddおよびngupdate機能についていくつかのことを明確にしました。Angularの回路図は、今や彼らのプロジェクトのエコシステムの確固たる部分であり、確実に改善を続けるでしょう。ますます多くの開発者がそれらを使用し、それらに対する認識を高めているため、今こそライブラリが schematicsの利用を開始する絶好の機会です。あなたとあなたのユーザーの両方が心配するのを自動化してみませんか?🙂

ご不明な点がございましたら、コメントでお気軽にお問い合わせください。

Thanks for reading!

Angular