TypeScriptのビルドプロセス

TypeScriptで書かれたアプリケーションは、本番環境で実行する前にJavaScriptにコンパイルする必要があります。

TypeScriptのソースファイルのコンパイルは、さまざまなビルドツールを使用して行うことができます。しかし、AdonisJSでは、最もシンプルなアプローチを採用し、以下の信頼性のあるツールを使用しています。

以下に挙げるすべてのツールは、公式のスターターキットとして開発依存関係として事前にインストールされています。

TSC は、TypeScriptの公式コンパイラです。TSCを使用して型チェックを行い、本番ビルドを作成します。
TS Node Maintained は、TypeScriptのJust-in-Timeコンパイラです。これにより、TypeScriptファイルをコンパイルせずに実行することができ、開発には非常に便利なツールです。
SWC は、Rustで書かれたTypeScriptコンパイラです。開発時にTS Nodeと組み合わせて使用し、JITプロセスを非常に高速化します。

コンパイルせずにTypeScriptファイルを実行する

ts-node-maintained/register/esmフックを使用して、TypeScriptファイルをコンパイルせずに実行できます。たとえば、次のコマンドを実行してHTTPサーバーを起動できます。

node --import=ts-node-maintained/register/esm bin/server.js

--import: インポートフラグを使用すると、モジュールの解決とロードのためのカスタマイズフックをエクスポートするモジュールを指定できます。詳細については、Node.jsのカスタマイズフックのドキュメントを参照してください。
ts-node-maintained/register/esm：TypeScriptソースをJavaScriptにコンパイルするためのJust-in-Timeコンパイルを実行するライフサイクルフックを登録するts-node-maintained/register/esmスクリプトへのパスです。
bin/server.js：AdonisJSのHTTPサーバーエントリーポイントファイルへのパスです。詳細はこちらを参照してください：ファイル拡張子に関する注意事項

同様に、他のTypeScriptファイルに対してもこのプロセスを繰り返すことができます。たとえば：

テストを実行する

node --import=ts-node-maintained/register/esm bin/test.ts

Aceコマンドを実行する

node --import=ts-node-maintained/register/esm bin/console.ts

他のTypeScriptファイルを実行する

node --import=ts-node-maintained/register/esm path/to/file.ts

ディスク上のファイルは.tsの拡張子で保存されているにもかかわらず、私たちはいたるところで.jsの拡張子を使用していることに気付いたかもしれません。

これは、ESモジュールでは、インポートやスクリプトの実行時に.js拡張子を使用するようにTypeScriptが強制されるためです。この選択の背後にある理論については、TypeScriptのドキュメントで学ぶことができます。

もしTypeScript 5.7以降を使用している場合、.ts拡張子を使用してTypeScriptファイルをインポートすることができます。これは、相対パスのためのパス書き換え機能によって可能になります。

一部のランタイムでは、TypeScriptコードを「その場で」実行し、.ts拡張子を要求することができるため、将来の互換性のためにすでに.ts拡張子を使用することを好むかもしれません。

bin/server.jsファイルを直接実行する代わりに、以下の理由からserveコマンドの使用をオススメします。

コマンドにはファイルウォッチャーが含まれており、ファイルの変更時に開発サーバーを再起動します。
serveコマンドは、アプリケーションで使用しているフロントエンドアセットバンドラーを検出し、その開発サーバーを起動します。たとえば、プロジェクトのルートにvite.config.jsファイルがある場合、serveコマンドはviteの開発サーバーを起動します。

node ace serve --watch

--assets-argsコマンドラインフラグを使用して、Viteの開発サーバーコマンドに引数を渡すことができます。

node ace serve --watch --assets-args="--debug --base=/public"

Viteの開発サーバーを無効にするには、--no-assetsフラグを使用します。

node ace serve --watch --no-assets

serveコマンドは、開発サーバー（bin/server.tsファイル）を子プロセスとして起動します。子プロセスにnode引数を渡す場合は、コマンド名の前にそれらを定義できます。

node ace --no-warnings --inspect serve --watch

AdonisJSアプリケーションの本番ビルドは、node ace buildコマンドを使用して作成されます。buildコマンドは、以下の操作を実行して、./buildディレクトリ内にスタンドアロンのJavaScriptアプリケーションを作成します。

ace.jsファイルへの変更はビルドプロセス中に失われます。ビルドの前にAceが開始される前に実行する追加のコードがある場合は、代わりにbin/console.tsファイル内で行うべきです。

以上です！

node ace build

ビルドが作成されたら、buildフォルダに移動し、本番依存関係をインストールしてアプリケーションを実行できます。

cd build

# 本番依存関係のインストール
npm ci --omit=dev

# サーバーの実行
node bin/server.js

--assets-argsコマンドラインフラグを使用して、Viteビルドコマンドに引数を渡すことができます。

node ace build --assets-args="--debug --base=/public"

フロントエンドアセットのコンパイルを回避するには、--no-assetsフラグを使用します。

node ace build --no-assets

スタンドアロンビルドとは、元のTypeScriptソースなしで実行できるアプリケーションのJavaScript出力を指します。

スタンドアロンビルドを作成することで、デプロイするコードのサイズを削減できます。ソースファイルとJavaScript出力の両方をコピーする必要がないためです。

本番ビルドを作成した後、./buildを本番サーバーにコピーし、依存関係をインストールし、環境変数を定義してアプリケーションを実行できます。

コンセプト

ツール設定

基本

ルーティング