Clerk の useOrganizationList で組織データを取得する時は引数を正しく渡そう

Clerkの`useOrganizationList`フックを使う際の落とし穴と最適な引数指定方法を解説。データを確実に取得するには`pageSize`の明示指定がおすすめ。4つのパターンの違いと実践的な使い方を検証結果と共に紹介。

Clerk の useOrganizationList フックは、ユーザーの organization 情報を取得する重要な機能ですが、引数の指定方法によって大きく動作が変わります。この記事では、実際の検証結果と Clerk 公式ドキュメントを基に、4つの主要なパターンとその違いを詳しく解説します。

ざっくり要約

useOrganizationList フックは、引数なしでも利用できますが、Organization のデータは取得されません。取得したいリソースの種類や情報について明示的に引数へ渡しましょう。渡し方は3種類あります。true のみ指定すると、デフォルト設定（pageSize: 10）で取得されます。infinite: true を指定すれば全データを自動取得できますが、全件取得のパフォーマンスに不安を覚えるでしょう。個人的には、pageSize を明示指定することをお勧めします。指定した件数分を確実に取得でき、パフォーマンスと確実性のバランスが最も良くなります。

基本的な使い方と公式ドキュメントの説明

Clerk 公式ドキュメントには以下のように記載されています。

“To keep network usage to a minimum, developers are required to opt-in by specifying which resource they need to fetch and paginate through. So by default, the userMemberships, userInvitations, and userSuggestions attributes are not populated.”

つまり、明示的に指定しない限り、データは取得されません。

パターン1: 引数なし

const { userMemberships } = useOrganizationList()
console.log(userMemberships) // undefined

結果として userMemberships は undefined になります。これは公式ドキュメントにも明記されている通り、デフォルトでは何も取得されないためです。

// userMemberships.data will never be populated
const { userMemberships } = useOrganizationList()

パターン2: true のみ指定

const { userMemberships } = useOrganizationList({
  userMemberships: true
})
console.log(userMemberships.data) // 空配列の場合がある

デフォルト設定で取得されますが、空配列が返される場合があります。空配列になった原因は不明ですが、ドキュメントにはこのように記載されていました。

“Use default values to fetch userMemberships, such as initialPage = 1 and pageSize = 10”

この辺りのデフォルトで設定される引数との兼ね合い・・・かもしれません。もしこの方法でデータが取得できない場合は、パターン3もしくは4をお試しください。

パターン3: infinite: true 指定

ここからはデータ取得に成功したパターンです。1つめは全件取得を指示する引数です。

const { userMemberships } = useOrganizationList({
  userMemberships: {
    infinite: true
  }
})
console.log(userMemberships.data) // 全データが取得される

全てのデータが確実に取得されます。公式ドキュメントには以下のように説明されています。

“If true, newly fetched data will be appended to the existing list rather than replacing it. Useful for implementing infinite scroll functionality.”

メリットとして、データの取得漏れがなく、全 organization が確実に表示されることがあります。一方で、大量の organization がある場合にパフォーマンスに影響を与える可能性があり、不要なネットワーク通信が発生するといったデメリットもあるでしょう。

パターン4 pageSize 明示指定（推奨）

const { userMemberships } = useOrganizationList({
  userMemberships: {
    pageSize: 50,
    initialPage: 1
  }
})
console.log(userMemberships.data) // 最大50件のデータが確実に取得

指定した件数分のデータが確実に取得されます。このパターンにはメリットが多く、パフォーマンスをコントロールでき、データの取得漏れを防げます。また、必要に応じて fetchNext() で追加取得も可能です。ただし、pageSize 以上のデータがある場合は手動で追加取得が必要になります。

実際の検証結果

以下は実際の検証で得られた結果です。

パターン	userMemberships.data	理由
引数なし	undefined	公式仕様通り
true のみ	[]（空配列）	デフォルト値が当てはまらない場合は、取れない？
infinite: true	[…organizations]	全データ取得
pageSize: 50	[…organizations]	十分なサイズで確実取得

まとめ

Clerk の useOrganizationList を使うときは、取得したいリソースについてpageSizeを明示的に指定することをお勧めします。

const { userMemberships, isLoaded } = useOrganizationList({
  userMemberships: {
    pageSize: 5, // 一般的な使用量を想定
  }
})

if (!isLoaded) return <div>Loading...</div>

// 必要に応じて追加取得
const loadMore = () => {
  if (userMemberships.hasNextPage) {
    userMemberships.fetchNext()
  }
}

まとめ

useOrganizationList の引数指定は、アプリケーションのパフォーマンスとユーザー体験に直結する重要な選択といえます。

開発初期やプロトタイプでは infinite: true で確実にデータを取得し、本格運用では pageSize を明示指定してパフォーマンスを最適化することをお勧めします。大規模アプリケーションの場合は Backend API を活用してサーバーサイドで処理するのが良いでしょう。

適切な引数指定により、確実なデータ取得とパフォーマンスの両立を実現できます。

参考資料

Clerk useOrganizationList() Hook Documentation

Clerk Organizations Overview

Custom Flows: Build a custom flow for switching organizations