Encore.ts と React を使用してリアルタイム ダッシュボードを構築する方法

リアルタイム ダッシュボードは、Web サイト分析の追跡からライブ財務データの監視、さらには IoT デバイスの監視に至るまで、さまざまなアプリケーションで非常に役立ちます。

?このチュートリアルでは、React と Encore.ts を使用してビルドする方法を示します。更新を即座にストリーミングし、情報に基づいて迅速な意思決定を行えるようにする動的なダッシュボードの作成方法を学びます。

私たちが構築するものを垣間見るには、完成品のこの GIF とここのソース コードをチェックしてください。飛び込んでみましょう！

前提条件

始める前に、これらのものがコンピュータにインストールされていることを確認してください

• Node.js (v18 以降)
• Npm (v10 以降)

アンコールの内容と理由

Encore.ts は、TypeScript を使用してバックエンドを構築し、型の安全性を確保するのに役立つオープンソース フレームワークです。 NPM への依存関係がないため、軽量かつ高速です。

分散バックエンド システムを開発する場合、運用環境をローカルに複製するのが困難なことが多く、開発者のエクスペリエンスが低下します。ローカルで合理的な方法で実行するためだけに、多くの複雑さに対処することになる可能性があり、実際のアプリケーションの構築に集中すると時間がかかります。 Encore.ts は、次のような分散システムを構築するための完全なツールセットを提供することでこの問題に対処します。

• ローカル環境はクラウドと一致します
• クロスサービスタイプセーフティ
• タイプ認識インフラストラクチャ
• 自動 API ドキュメントとクライアント
• ローカルテストトレース
• その他

さて、Encore とは何か、そして Encore がバックエンド サービスの構築にどのように役立つかについてお話しました。次のセクションでは、Encore をローカルにインストールしてビルドを開始しましょう。

Encore のインストール

Encore を使用するには、CLI をインストールする必要があります。これにより、ローカル環境の作成と管理が非常に簡単になります。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Encore アプリケーションの作成

Encore アプリケーションの作成は非常に簡単で、コマンドを実行するだけです。

encore app create

次の質問が表示されるので、それに応じて答えを選択してください。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

アプリが作成されたら、encore.app でアプリケーション構成を確認できます

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}
</random-id>

よし、Encore アプリケーションを作成しました。次のセクションでは、Encore のストリーミング API について説明します。

Encore のストリーミング API とは

ストリーミング API について説明する前に、Encore の API について説明しましょう。 Encore での API エンドポイントの作成は、タイプ セーフティを備えた API エンドポイントを定義するための API 関数が encore.dev/api モジュールから提供されるため、非常に簡単です。 Encore には、受信リクエストに対する検証も組み込まれています。 API の中核は、リクエストとレスポンスのスキーマ構造を備えた単純な非同期関数です。 Encore はコードを解析し、コンパイル時にボイラープレートを生成するため、API の定義だけに集中する必要があります。

ストリーミング API は、アプリケーションとの間でデータを送受信できる API であり、双方向通信が可能です。

Encore は、データ フローの方向が異なる 3 種類のストリームを提供します。

• StreamIn: これを使用してサービスにデータをストリーミングします。
• StreamOut: サービスからデータをストリーミング出力するためにこれを使用します。
• StreamInOut: これを使用して、サービスの内外の両方でデータをストリーミングします。

ストリーミング API エンドポイントに接続すると、クライアントとサーバーは HTTP リクエストを使用してハンドシェイクを実行します。サーバーがこのリクエストを受け入れると、クライアントと API ハンドラーの両方に対してストリームが作成されます。このストリームは実際には、メッセージの送受信を可能にする WebSocket です。

Encore の API とストリーミング API が何であるかがわかったので、次のセクションでストリーミング API エンドポイントを使用して、リアルタイムでデータを保存および取得するダッシュボード サービスを作成しましょう。

ダッシュボードサービスの作成

販売ダッシュボードとの間でデータをストリーミングするための販売 API を定義するダッシュボード サービスを作成しましょう。

ルート レベルに「dashboard」というフォルダーを作成し、encore.service.ts ファイルを追加します。このファイルは、ダッシュボード フォルダーとそのサブフォルダーをサービスの一部として扱うように Encore に指示します。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

次に、次のコードを encore.service.ts ファイルに追加します。 encore.dev/service から Service クラスをインポートし、サービス名として「dashboard」を使用してそのインスタンスを作成します。

encore app create

次に、dashboard.ts ファイルを作成し、販売 API を設定しましょう。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

API を設定する前に、まず売上データを保存するデータベースを設定します。 encore.dev/storage/sqldb モジュールの SQLDatabase を使用して、Encore でサポートされる PostgreSQL データベースを作成します。

SQL を移行として定義する必要があります。encore run コマンドを実行すると、Encore がこれを取得します。

ダッシュボード フォルダー内に migrations という名前のフォルダーを作成し、1_first_migration.up.sql というファイルを作成します。必ず、number_ で始まり up.sql で終わる命名規則に従ってください。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

ここでは、4 つの列を持つ sales というテーブルを作成しています。

• id: 自動インクリメントされ、主キーとして機能します
• セール: セールのタイトル
• 合計: 販売総額
• 日付: 販売日

次に、次のコードをdashboard.ts ファイルに追加します。

encore app create

ここでは、ダッシュボードという名前を付け、移行フォルダーへのパスを指定して、SQLDatabase のインスタンスを作成します。

データベース内の変更をリッスンして通知するために、postgres パッケージを使用しています。

?

次に、これらの型と、接続されたストリーム (WebSocket 接続) を保持するためのメモリ内マップを追加します。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

次に、新しいセールが発生したときに更新を送信するために、セール ストリーミング エンドポイントを設定しましょう。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}
</random-id>

ここでは、api.streamOut 関数を使用して API を定義します。これは 2 つの引数を取ります。

• ストリームオプション:
  • expose: エンドポイントを公開するには true に設定し、それ以外の場合は false
  • auth: エンドポイントを認証で保護するには true に設定し、それ以外の場合は false
  • パス: /sale
• 関数: 2 つの引数を取ります
  • ハンドシェイク: ストリーム接続を確立するために使用されます
  • stream: ストリーム オブジェクト

connectedStreams マップに接続を保持し、Postgres クライアントを使用して new_sale チャネルをリッスンします。新しいセールが発生すると、接続されているすべてのストリームに更新情報が送信されます。

次に、販売追加 API エンドポイントを定義します。ここで、リクエスト本文から販売データを取得し、db インスタンスを使用して新しい販売レコードを挿入します。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

ここでは、新しい販売レコードをデータベースに追加した後、Postgres クライアントを使用して、販売データとともに new_sale チャネルに通知を送信します。このようにして、new_sale チャネルのリスナーは通知を受け取り、アクションを実行できます。

最後に、販売レコードのリストを返す API エンドポイントを設定しましょう。

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

ここでは、db インスタンス メソッド クエリを使用してデータを取得し、それを処理してリストとして返します。

これで、すべての API エンドポイントが定義されました。次のセクションで Encore 開発ダッシュボードを見てみましょう。

開発ダッシュボードの探索

データベースをセットアップした API エンドポイントがありますが、サービスをテストおよびデバッグするにはどうすればよいでしょうか?心配しないでください。Encore は、開発者の作業を容易にし、生産性を向上させるローカル開発ダッシュボードを提供します。

アプリケーションの設計、開発、デバッグに役立ついくつかの機能が含まれています。

• ローカル バックエンドへの API 呼び出しを簡単に行うためのサービス カタログと API エクスプローラー
• 簡単かつ強力なデバッグのための分散トレーシング
• 知識を共有し、質問に答えるための自動 API ドキュメント
• マイクロサービス アーキテクチャを視覚化するための Encore フロー

これらの機能はすべて、アプリケーションを変更するとリアルタイムで更新されます。

ダッシュボードにアクセスするには、Encore run で Encore アプリケーションを起動すると、ダッシュボードが自動的に開きます。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

ダッシュボードは次のようになります。本番環境に移行する前に、すべてをローカルでテストできます。これにより、外部ツールを必要とせずにマイクロサービス アーキテクチャをテストすることがはるかに簡単になります。

ここでは、API Explorer を使用して新しいセールを追加する例を示します。 「API を呼び出す」ボタンをクリックすると、応答とログが取得されます。右側に依頼の痕跡が見えます。

トレース リンクをクリックすると、データベース クエリ、応答、ログなどの詳細が表示されます。

ローカル開発ダッシュボードについては以上です。サービス カタログ、フローなどの他のオプションを検討できます。次のセクションでは、ダッシュボード サービス API と通信するためにフロントエンド サービス (React アプリケーション) で使用する TypeScript タイプ セーフティを備えたクライアントを生成します。

クライアントの生成

Encore は、TypeScript または JavaScript でフロントエンド リクエスト クライアントを生成し、リクエスト/レスポンス タイプの同期を維持し、手作業なしで API を呼び出すことができます。

ルート ディレクトリにfrontend という名前のフォルダーを作成し、次のコマンドを実行して、Vite を使用して React プロジェクトをセットアップします。

encore app create

次に、src ディレクトリ内に lib フォルダーを作成し、client.ts という新しいファイルを追加し、空のままにします。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

次に、package.json ファイルに gen-client という新しいスクリプトを追加します。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}
</random-id>

次に、スクリプトを実行して src/lib/client.ts にクライアントを作成します。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

src/lib/client.ts ファイルには、生成されたコードが含まれている必要があります。

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

次に、lib ディレクトリに getRequestClient.ts という名前のファイルを作成し、次のコードを追加します。これにより、環境に基づいてクライアント インスタンスが返されます。

# make sure you are in dashboard folder
touch dashboard.ts

これで、React アプリケーションでダッシュボード API を呼び出すために使用するクライアントが完成しました。次のセクションでは、フロントエンド サービスを作成し、リアルタイム販売ダッシュボードの UI を構築しましょう。

フロントエンドサービスの作成

前のセクションでは、React アプリケーションを使用してフロントエンド フォルダーをセットアップしました。次に、それをサービスにします。 encore.service.ts ファイルを作成し、次のコードを追加して、フロントエンド フォルダーを「フロントエンド」サービスとして扱うように Encore に指示しましょう。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

2 つのオプションがあります:

• ダッシュボードとフロントエンド サービスを別々に提供する
• すべてを 1 つのバンドルとして提供します (このチュートリアルではこのアプローチを使用します)

React アプリケーションを提供するには、Encore で静的アセットとして構築して提供する必要があります。フロントエンドフォルダーに static.ts ファイルを設定しましょう。

Encore.ts での静的ファイルの提供は通常の API エンドポイントと似ていますが、代わりに api.static 関数を使用します。

encore app create

ここで注意すべき 2 つの重要な点があります: path および dir オプションを渡しています。

• path: /!path は、フォールバック ルートとして機能し、他のエンドポイントと競合しないことを保証します。
• dir: ./dist は、React アプリケーションのビルド バージョンのディレクトリです。

静的エンドポイントがセットアップされました。次に、React アプリケーションの依存関係をいくつかインストールしましょう

• 反応ルーターダム
• uuid
• 追い風CSS

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

次に、以下のコードで main.tsx を更新します。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}
</random-id>

次に、Tailwind CSS をセットアップして、いくつかのファイルを更新しましょう。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

tailwind.config.js のコンテンツ セクションを変更します

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

そして次のコードを含むindex.css。

# make sure you are in dashboard folder
touch dashboard.ts

次に、販売ダッシュボード用のコンポーネントをいくつか作成しましょう。

• SalesTable: 売上データを表形式で表示します。

# 1_first_migration.up.sql

CREATE TABLE sales (
    id BIGSERIAL PRIMARY KEY,
    sale VARCHAR(255) NOT NULL,
    total INTEGER NOT NULL,
    date DATE NOT NULL
);

ここでは、生成されたクライアントから型をインポートして、ダッシュボード サービスの型と一致させ、型の安全性を確保しています。

• SalesMetrics: 合計売上、最低売上、平均売上などの売上数値を表示します。

# dashboard.ts

import { SQLDatabase } from 'encore.dev/storage/sqldb';
import postgres from 'postgres';

const db = new SQLDatabase('dashboard', {
  migrations: './migrations',
});

const client = postgres(db.connectionString);

• RoleSelector: ユーザーがダッシュボードのロールを選択できるようにするために、2 つのオプションを表示します。
  • 閲覧者: 販売ダッシュボードを表示できます
  • マネージャー: 新しい売上を表示および作成できます

# dashboard.ts

...

// Map to hold all connected streams
const connectedStreams: Map<string streamout>> = new Map();

interface HandshakeRequest {
  id: string;
}

interface Sale {
  sale: string;
  total: number;
  date: string;
}

interface ListResponse {
  sales: Sale[];
}

</string>

• GenerateSales: 販売の生成ボタンを表示し、販売を生成するためのロジックを含めます。

売上を生成するには、模擬データが必要なので、src/constant.ts ファイルを作成して模擬データを追加しましょう

# dashboard.ts
...

import { api, StreamOut } from 'encore.dev/api';
import log from 'encore.dev/log';

...

export const sale = api.streamOut<handshakerequest sale>(
  { expose: true, auth: false, path: '/sale' },
  async (handshake, stream) => {
    connectedStreams.set(handshake.id, stream);

    try {
      await client.listen('new_sale', async function (data) {
        const payload: Sale = JSON.parse(data ?? '');

        for (const [key, val] of connectedStreams) {
          try {
            // Send the users message to all connected clients.
            await val.send({ ...payload });
          } catch (err) {
            // If there is an error sending the message, remove the client from the map.
            connectedStreams.delete(key);
            log.error('error sending', err);
          }
        }
      });
    } catch (err) {
      // If there is an error reading from the stream, remove the client from the map.
      connectedStreams.delete(handshake.id);
      log.error('stream error', err);
    }
  }
);
</handshakerequest>

# dashboard.ts
...
...

export const addSale = api(
  { expose: true, method: 'POST', path: '/sale/add' },
  async (body: Sale & { id: string }): Promise<void> => {
    await db.exec`
      INSERT INTO sales (sale, total, date)
      VALUES (${body.sale}, ${body.total}, ${body.date})`;

    await client.notify(
      'new_sale',
      JSON.stringify({ sale: body.sale, total: body.total, date: body.date })
    );
  }
);

</void>

ここでは、getRequestClient をインポートし、ダッシュボード サービスから addSale エンドポイントを呼び出します。これは非常に簡単で、addSale はタイプセーフであるため、許可されていない属性を渡そうとすると、エラーが発生します。

次に、SalesDashboard コンポーネントを作成して、売上指標、最近の売上、および過去の売上を含むダッシュボード ビューを表示しましょう。

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

SalesDashboard は、ロールと呼ばれる 1 つのプロパティを受け取り、GenerateSales コンポーネントを表示するかどうかを決定します。

saleStream はアクティブなストリーム参照を保持し、厳密に型指定されます。

encore app create

コンポーネントがマウントされると、ダッシュボード サービスの販売エンドポイントを使用してストリーム接続を作成します。次に、ソケットのオープン イベントとクローズ イベントをリッスンし、これらのイベントに基づいて適切なロジックを実行します。

saleStream.current から販売データを読み取り、recentSalesData 状態に保存します。

コンポーネントがアンマウントされると、現在のストリームをクリーンアップして閉じます。

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

このコードは、listSales エンドポイントを使用してダッシュボード サービスから保存された売上を取得し、salesData 状態に保存します。

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}
</random-id>

このコードは、最近の売上データと過去の売上データを計算します。

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

最後に、このコードで App.tsx ファイルを更新します。

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

ここでは、ロール クエリ パラメーターが使用可能かどうかに基づいて、SalesDashboard コンポーネントと RoleSelector コンポーネントを表示しています。

次に、フロントエンドのルートで以下のコマンドを実行して、React アプリケーションを構築しましょう。

# make sure you are in dashboard folder
touch dashboard.ts

コマンドが正常に実行されると、フロントエンド ディレクトリ内に dist フォルダーが作成されます。

次のセクションでは、アプリケーションを実行して最初から最後までテストしてみましょう。

アプリケーションの実行

アンコール アプリケーションの実行は簡単です。以下のコマンドを使用してください。

# 1_first_migration.up.sql

CREATE TABLE sales (
    id BIGSERIAL PRIMARY KEY,
    sale VARCHAR(255) NOT NULL,
    total INTEGER NOT NULL,
    date DATE NOT NULL
);

コマンドが正常に実行されると、次のようなログがターミナルに表示されます。

# dashboard.ts

import { SQLDatabase } from 'encore.dev/storage/sqldb';
import postgres from 'postgres';

const db = new SQLDatabase('dashboard', {
  migrations: './migrations',
});

const client = postgres(db.connectionString);

ブラウザで http://127.0.0.1:4000 にアクセスすると、以下のような画面が表示されます。

次に、1 つのタブで [Viewer] を選択し、別のタブで [Manager] を選択します。

• 閲覧者

• マネージャー

開発ダッシュボードを確認しながら、販売レコードを作成しました。データベースに保存されたため、UI にも表示されます。

次に、マネージャー ビューで [売上の生成] ボタンをクリックし、ダッシュボードの両方のタブがリアルタイムで更新されるのを確認します。

まとめ

このチュートリアルでは、React と Encore.ts を使用してリアルタイム販売ダッシュボードを作成しました。アプリは新しい販売アイテムや在庫アイテムで即座に更新されるため、迅速な意思決定に役立ちます。オープンソース フレームワークである Encore.ts を使用して、安全かつスムーズなコーディングを実現するために TypeScript でバックエンドを構築しました。 Encore の主な機能は次のとおりです:

1. タイプ セーフティ: すべての API エンドポイントとデータ構造が安全であることを確認し、間違いを減らし、コードの信頼性を高めます。
2. ストリーミング API: StreamIn、StreamOut、StreamInOut を使用したリアルタイム データ ストリーミングを可能にし、クライアントとサーバー間の双方向通信を可能にします。
3. ローカル開発ダッシュボード: サービス カタログ、API エクスプローラー、分散トレースなどのテストとデバッグ用のツールを提供し、生産性を向上させます。
4. 自動クライアント生成: TypeScript または JavaScript でフロントエンド リクエスト クライアントを作成し、リクエスト/レスポンスのタイプを調整します。
5. 簡素化されたマイクロサービス: 通常の複雑さを伴うことなく複数のサービスを含むアプリを構築でき、マイクロサービスをより簡単に処理する方法を提供します。

これらの機能を組み合わせることで、複雑なアプリの構築と管理が容易になり、優れた開発者エクスペリエンスが提供されます。

関連リンク

• GitHub の Star Encore
• この例のソース コードを見つける
• Discord コミュニティに参加してください

以上がEncore.ts と React を使用してリアルタイム ダッシュボードを構築する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。