フロントエンド開発者としてバックエンドを構築する：Payload CMSでの経験

大規模なモバイルアプリケーション向けのヘッドレスCMSの実装を任されたとき、私は慣れない領域に足を踏み入れることになりました。フロントエンド開発者として、バックエンド開発はデータベース設計、API実装、認証システム、デプロイインフラストラクチャなど、困難な要素の組み合わせのように感じられました。

Payloadは、既存のTypeScriptスキルを活用しながら、必要なバックエンド機能を提供するアプローチを提供しました。本番環境へのデプロイと、複数回の高トラフィック期間を通じたシステムの保守を経て、この記事ではPayloadでバックエンドシステムを構築する際の実践的な現実を振り返ります。

Payloadとは？

Payloadは、TypeScriptとNext.jsで構築されたオープンソースのヘッドレスコンテンツ管理システム（CMS）です。WordPressやDrupalなどの従来のCMSプラットフォームとは異なり、ヘッドレスCMSはAPIを介してコンテンツを配信するため、あらゆるフロントエンドスタックがコンテンツを利用できます。

Payloadの主要な特徴は、コードファーストの哲学です。ContentfulやStrapiなどの他のヘッドレスCMSが管理画面を通じてスキーマを定義する必要があるのに対し、PayloadではすべてをTypeScriptで定義できます。このアプローチは、モダンなJavaScriptフレームワークに慣れていて、同じ開発体験をバックエンドのインフラにも拡張したい開発者にアピールします。

Next.jsの上に構築されたPayloadは、フレームワークのサーバーサイドレンダリングとAPIルーティングを活用しながら、独自のデータベース抽象化レイヤーも提供します。PostgreSQLとMongoDBの両方をサポートし、RESTとGraphQL APIを提供し、AWS Lambdaなどのサーバーレスプラットフォームや従来のサーバーにデプロイできます。

バックエンド作業に取り組むフロントエンド開発者にとって、これは慣れ親しんだTypeScript環境内で、完全に新しいバックエンドスタックを学ぶ必要なく、コンテンツの管理、データ構造の定義、APIの公開をすべて行えることを意味します。

コードとしての設定

Payloadは、GUIの設定やSQL文ではなく、コードとしてスキーマ定義を管理することで差別化を図っています。Payloadでは、collectionsはTypeScriptの設定オブジェクトであり、強く型付けされたfieldsを持ち、自動的にデータベーステーブルのカラムに変換されます。

export const Articles: CollectionConfig = {
  slug: "articles",
  fields: [
    {
      name: "title",
      type: "text",
      required: true,
    },
    {
      name: "body",
      type: "richtext",
    },
    {
      name: "category",
      type: "relationship",
      relationTo: "categories",
    },
  ],
};

フロントエンド開発者の視点から見ると、この構文は馴染みやすく、データベーススキーマを定義するというよりも、コンポーネントのプロップスを定義するような感覚です。さらに、コードがバージョン管理システム内に存在するため、変更を追跡し、共同でレビューし、必要に応じてロールバックできます。

上記のコレクションは、自動的にいくつかの成果物を生成します：

データベーススキーマ

フィールド設定に基づいてデータベーステーブルが作成されます。上記のコレクションは、以下のカラムを持つarticlesテーブルを生成します：

REST APIエンドポイント

すべてのコレクションは、追加の設定なしで完全なREST APIも受け取ります：

GET    /api/articles          # ページネーション付きでリストを取得
GET    /api/articles/:id      # 単一のエンティティを取得
POST   /api/articles          # 新規作成
PATCH  /api/articles/:id      # 既存のものを更新
DELETE /api/articles/:id      # エンティティを削除

フィルタリングとソートを簡単に行うためのデフォルトのクエリパラメータも提供されています。例えば、タイトルに「frontend」を含む最初の10件の記事を作成日順に取得するには：

/api/articles?where[title][contains]=frontend&sort=createdAt&limit=10

TypeScript型定義

コレクション設定に基づいて型インターフェースも生成され、モダンなIDEで型チェックと自動補完のサポートを提供します。

export interface Articles {
  id: number;
  title: string;
  body?: {
    root: {
      type: string;
      children: {
        type: string;
        version: number;
        [k: string]: unknown;
      }[];
      direction: ("ltr" | "rtl") | null;
      format: "left" | "start" | "center" | "right" | "end" | "justify" | "";
      indent: number;
      version: number;
    };
    [k: string]: unknown;
  } | null;
  category?: {
    relationTo: "category";
    value: number | Category;
  } | null;
  createdAt?: string | null;
  updatedAt?: string | null;
}

この自動的な成果物生成により、かなりの量のボイラープレートコードとメンテナンスが不要になり、バックエンド開発がより速く、より信頼性の高いものになります。

バックエンドの学習曲線を低減

Payloadのいくつかの機能により、フロントエンド開発者にとってバックエンド開発がよりアプローチしやすくなります：

組み込み管理画面

Payloadには、開発中に即座のフィードバックを得るためにNext.jsのHot Module Replacement（ホットモジュール置換）を活用する、事前構築された自動生成管理画面が含まれています。本番環境対応の管理画面は、TypeScriptスキーマの変更を自動的に反映し、複雑なUI要件を持つプロジェクトのために高度にカスタマイズ可能です。

多言語対応

多言語のサポートは、複雑なセットアップではなく、設定を通じて処理されます。フィールドをlocalizedとしてマークでき、コンテンツ編集者が管理画面で直接翻訳を管理できるようになります。システムは、ロケール固有のクエリを自動的に処理し、翻訳が欠落している場合のフォールバック動作を提供します。

export const Articles: CollectionConfig = {
  slug: "articles",
  fields: [
    {
      name: "title",
      type: "text",
      localized: true, // ロケールごとのコンテンツを有効化
    },
  ],
};

APIリクエストは、クエリパラメータを介してロケールの設定を指定でき、Payloadは適切なコンテンツバージョンを取得するために基礎となるデータベースクエリを処理します。例えば、/api/articles?locale=ja&fallback-locale=enをリクエストすると、利用可能な場合は日本語のコンテンツを返し、それ以外の場合は英語にフォールバックします。

データリレーションシップモデリング

データ構造間の関係を作成するには、上記のサンプルコレクションで示されているように、relationshipフィールドタイプを使用します。Payloadは基礎となるデータベース結合を処理し、関連コンテンツを選択するための機能的な管理UIを提供します。

フック

コレクションレベルおよびフィールドレベルのフック（beforeRead、afterRead、beforeChange、afterChangeなど）は、Reactのライフサイクルメソッドを模倣しており、比較的簡単にビジネスロジックを実装できます。

export const Articles: CollectionConfig = {
  slug: "articles",
  fields: [
    {
      name: "title",
      type: "text",
      required: true,
    },
    {
      name: "slug",
      type: "text",
    },
    //...
  ],
  hooks: {
    beforeChange: [
      ({ data }) => {
        data.slug = data.title.toLowerCase().replace(/\s+/g, "-");
      },
    ],
  },
};

カスタムエンドポイント

標準的なCRUD操作を超えて、より複雑なワークフローを処理するためにカスタムエンドポイントを定義できます。

export const Articles: CollectionConfig = {
  slug: "articles",
  fields: [
    /* ... */
  ],
  endpoints: [
    {
      path: "/:id/summary", // エンドポイントを定義
      method: "get", // メソッドを定義
      handler: async req => {
        if (!req.user) {
          return Response.json({ error: "Unauthorized" }, { status: 401 });
        }
        const article = await req.payload.findByID({
          collection: "articles",
          id: req.routeParams.id as string,
        });

        // 複雑な操作を実行、外部APIを呼び出すなど
        const summary = await generateAISummary(article.body);

        return Response.json({ success: true, summary });
      },
    },
  ],
};

アクセス制御

認可は、コレクションレベルとフィールドレベルの両方で強制でき、UIの可視性に依存するのではなく、データレイヤーでセキュリティが一貫して処理されることを保証します。

export const Articles: CollectionConfig = {
  slug: "articles",
  access: {
    // 誰でも「published」の記事を読むことを許可
    read: ({ req: { user } }) => {
      if (user) return true;
      return { status: { equals: "published" } };
    },
    // 認証済みユーザーのみが記事を作成、更新、削除できる
    create: ({ req: { user } }) => Boolean(user),
    update: ({ req: { user } }) => Boolean(user),
    delete: ({ req: { user } }) => Boolean(user),
  },
};

この宣言的なアプローチにより、すべてのルートハンドラーで手動で権限をチェックするよりも、アクセス制御がシンプルでメンテナンスしやすくなります。セキュリティはすべてのリクエストに対して一貫して強制され、データレイヤーが保護されていることを確信できます。

注意点と課題

Payloadは魅力的な開発者体験を提供しますが、本番環境への移行では考慮する価値のあるいくつかの課題が浮上します。

データベースとスキーマ管理

開発中は、TypeScriptからデータベースへのワークフローがシームレスに感じられますが、PostgreSQLを使用する本番環境では、明示的なマイグレーション管理が必要になります。Payloadはマイグレーションスクリプトを提供しますが、すべてのスキーマ変更に対してpayload migrate:createを実行し、環境全体でマイグレーションの順序を慎重に管理する必要があります。これにより、複数の開発者が同時にスキーマを更新している場合、調整のオーバーヘッドが追加される可能性があります。

サーバーレスデプロイメントの複雑さ

Payloadをサーバーレス関数としてデプロイすることは、予想以上に複雑になる可能性があります。コールドスタートはパフォーマンスに影響を与える可能性がありますが、実稼働サービスでは、一般的なトラフィックパターンと適切なメモリ割り当てにより、通常は問題になりません。さらに、Payloadはサーバーレス環境でスケジュールされたタスクやバッチ処理をネイティブにサポートしていないため、スケジュールされた公開などの機能には、Lambda関数とEventBridgeスケジューリングを使用した別個のインフラストラクチャの構築が必要です。

ReactとNext.jsの統合

PayloadはApp Routerを使用したNext.jsの上に構築されているため、React Server Componentの課題も継承します。カスタム管理画面コンポーネントは、サーバー/クライアント境界を慎重にナビゲートする必要があり、ブラウザAPIとやり取りするカスタムフィールドを構築する際にハイドレーションの不一致が発生する可能性があります。以前にNext.jsのハイドレーションエラーに苦しんだことがある場合は、ここでも同じ問題に遭遇することが予想されます。

まとめ

フロントエンド開発者として、Payloadを使った作業は、まったく新しいバックエンドフレームワークを学ぶというよりも、TypeScriptのツールセットを拡張するような感覚でした。その馴染みやすいパターン、自動API生成、強力なスキーマ型付けにより、バックエンド開発は予想以上にアプローチしやすくなりました。

まだ課題はあります — マイグレーションの管理、サーバーレスデプロイメントの最適化、基礎となるデータベース構造の理解には意図的な努力が必要です。しかし、Payloadは、既存のTypeScript経験をバックエンドシステムに適用することで、フロントエンドとバックエンド開発の間のギャップを狭めます。Payloadがすべてをカバーするわけではありません — 高度なデータベース最適化、分散システム、インフラストラクチャ管理には専門的な学習が必要です。しかし、実用的なエントリーポイントを提供します。

Reactとモダンなビルドパイプラインに慣れている開発者にとって、慣れ親しんだ領域を離れることなくバックエンドシステムを構築できることを証明しています。

---

Payload、Payloadのデザイン、および関連するマーク、デザイン、ロゴは、米国およびその他の国におけるPayload CMS, Inc.の商標または登録商標です。