Refine（React）とは？react-adminとの違い・v5の変更点と管理画面の作り方

Refineは、社内管理画面やダッシュボードのようにCRUDが中心になる画面を、Reactで組むためのフレームワークです。認証・一覧・フォーム・権限といった毎回同じものをフックとして持つ一方、見た目のライブラリは選択制。似た立ち位置のreact-adminとよく比較されますが、両者はUIの決め方が根本的に違い、そこが選定の分かれ目になります。この記事は2026年7月29日時点のnpmレジストリと公式ドキュメントの実測値で、両者の違い、v5で変わった前提、データ接続の設計、そして詰まりやすいバージョンの噛み合わせまでを扱います。

まとめ：RefineとReact-adminの選び分け

先に結論を出します。UIライブラリを自分たちで決めたい、または既存のデザインシステムに合わせたいならRefine、Material UIで一気に完成形へ近づけたいならreact-adminです。Refineのコアはヘッドレスで、画面の見た目を持ちません。react-adminはMaterial UI前提で作られており、そのぶん初期の完成度が高い代わりに見た目の自由度は下がります。

バージョンの現在地も押さえておきます。Refineは@refinedev/coreが5.0.12（2026-04-02公開、MIT）で、v5からTanStack Query v5が必須です。react-adminは5.15.1（2026-06-24公開、MIT）。どちらもReact 18と19に対応するため、フレームワーク側がReactの版を縛ることはありません。ただし周辺は別で、@mantine/core 9.5.0はreact ^19.2.0を、react-router 8.3.0はreact 19.2.7以上を要求します。18に留まる前提があるなら、UIとルーターの版から先に決めてください。

費用は「何にお金を払うか」が違います。RefineのnpmパッケージはコアもプラグインもすべてMITで、機能を解放するための有料パッケージはありません。アクセス制御もAccessControlProviderとしてコアに入っています。Refineが課金するのはホスト型のアプリビルダー（月額0.99ドルから）と、自己ホスト・IdP連携・監査ログ・優先サポートを含むEnterprise契約であって、フレームワークの機能制限ではありません。対してreact-adminは、リストの直接編集やリアルタイム更新、権限制御といった機能そのものが有料モジュール（非公開npmレジストリで配布）として切り出されており、最小プランで145€/month（年額請求・開発者2名まで）かかります。無償の範囲で要件を満たせるかは、この線引きで確認してください。

Refineとは｜見た目を持たないReactの管理画面フレームワーク

Refineは@refinedev/coreを中心にしたパッケージ群です。コアが提供するのはUIコンポーネントではなくフックで、useListやuseFormを呼ぶとデータの取得・更新・キャッシュ・エラー処理が済んだ状態で値が返ります。表示は自分で書くか、Ant Design・Material UI・Chakra UI・Mantineに対応した公式のUIパッケージを載せます。

この構造の利点は、既存プロダクトのデザインシステムをそのまま使えることです。逆に、UIパッケージを使わずヘッドレスで始めると、一覧のテーブルもフォームも自分で書くことになるため、初日の見た目はreact-adminより明らかに素朴になります。

導入はnpm create refine-app@latestで対話的に作るのが最短ですが、既存プロジェクトに足す場合は必要なパッケージだけを入れます。データ層はTanStack Query v5がそのまま露出しているので、キャッシュの挙動を細かく制御したい場合はTanStack Queryとは？React Queryとの違い・v5の使い方と脆弱性対策の内容がそのまま効いてきます。

# react / react-dom は 18 か 19 が別途必要（peerDependencies）
npm install @refinedev/core@5 @tanstack/react-query@5

# ルーターとUIを足す場合（React Router v7系を使う構成）
npm install @refinedev/react-router@2 react-router@7
npm install @refinedev/antd@6 antd@5

react-adminとの違い｜UIを固定するか、選べるようにするか

細かい機能差を並べる前に、UIの決め方で大半が決まります。次に効くのが、無償の範囲でどこまで作れるかという線引きです。データ層の違いは、既存プロジェクトにTanStack Queryが入っているかどうかで意味が変わります。

実務上の判断はこうなります。納期が短く、見た目は標準的なものでよく、一覧・フォーム・フィルタが揃っていれば十分——この条件ならreact-adminが速いです。自社サービスの管理画面で、既存のトンマナに合わせる必要がある、あるいは将来UIライブラリを載せ替える可能性があるならRefineです。Refineはコアがフックなので、UIパッケージを外してもデータ取得のロジックは残ります。

費用の線引きも具体的に見てください。react-adminのEnterprise Editionには、リストの直接編集（Datagrid AG）、複雑な関連データの編集（Relationships）、多段メニュー（Navigation）、権限制御（Role Based Access Control）、監査ログ（Audit Log）、リアルタイム更新（Realtime）などが入ります。管理画面の要件としてはよくあるものが有料側に含まれるため、「本体がMITだから無料で作れる」と見積もると後で崩れます。

データ接続の設計｜公式data providerの範囲と、自作が必要になる場面

Refineでバックエンドにつなぐ部品がdata providerです。公式パッケージとして提供されているのは、REST、Airtable、Appwrite、GraphQL、Simple REST、Strapi v4、Supabase、Nest.js Query、NestJS CRUD、Hasuraです。これ以外はコミュニティ提供か、自作になります。

ここは誤情報が流通している箇所です。AWS Amplifyは公式のdata provider一覧に含まれていません。「RefineとAmplifyは相性が良い」という説明を見かけますが、公式パッケージは存在せず、AmplifyのGraphQL APIに合わせたdata providerを自分で書くか、コミュニティ実装を採用することになります。工数見積もりの前提が変わるので、選定時に必ず確認してください。

自作する場合に実装するのは、一覧取得・単体取得・作成・更新・削除・複数取得にあたるメソッド群です。REST寄りのAPIならSimple RESTの実装を写経して差分を埋めるのが早く、GraphQLなら公式のGraphQLパッケージにクエリの組み立てだけを渡す形にできます。

import { DataProvider } from "@refinedev/core";

export const dataProvider = (apiUrl: string): DataProvider => ({
  getList: async ({ resource, pagination }) => {
    // v5でPaginationのcurrentはcurrentPageへ改名されている
    const { currentPage = 1, pageSize = 10 } = pagination ?? {};
    const res = await fetch(
      `${apiUrl}/${resource}?_page=${currentPage}&_limit=${pageSize}`
    );
    const data = await res.json();
    return { data, total: Number(res.headers.get("x-total-count") ?? 0) };
  },
  getOne: async ({ resource, id }) => {
    const res = await fetch(`${apiUrl}/${resource}/${id}`);
    return { data: await res.json() };
  },
  // create / update / deleteOne / getApiUrl も同様に実装する
  // ※抜粋のため as で型検査を外している。実装時は外して未実装を検出させる
} as DataProvider);

getListが返すtotalは、一覧のページャが件数を出すために使われます。ヘッダに総件数を返さないAPIだと最後のページ番号が出ないため、バックエンド側の仕様を先に確認しておくと手戻りがありません。

CRUD画面とダッシュボード｜resources登録とフックの対応

CRUD画面の作り方

resourcesに扱う対象を登録すると、一覧・作成・編集・詳細のルートが決まります。あとは各画面でフックを呼ぶだけで、取得とキャッシュはコアが持ちます。

import { Refine, useList } from "@refinedev/core";
import routerProvider from "@refinedev/react-router";
import { BrowserRouter, Routes, Route } from "react-router";
import { dataProvider } from "./dataProvider"; // 前節で実装したもの

const App = () => (
  <BrowserRouter>
    <Refine
      dataProvider={dataProvider("https://api.example.com")}
      routerProvider={routerProvider}
      resources={[
        { name: "orders", list: "/orders", edit: "/orders/edit/:id" },
      ]}
    >
      <Routes>
        <Route path="/orders" element={<OrderList />} />
      </Routes>
    </Refine>
  </BrowserRouter>
);

const OrderList = () => {
  const { result, query } = useList({ resource: "orders" });
  if (query.isLoading) return <p>loading</p>;
  return <ul>{result.data.map((o) => <li key={o.id}>{o.title}</li>)}</ul>;
};

ダッシュボード画面の作り方

ダッシュボードは、resourcesの枠に収まりません。売上推移や進捗率のような集計値は特定のリソースの一覧ではないため、resourcesに登録せず独立したルートとして置き、useCustomで集計APIを叩きます。無理にresourcesへ寄せると、使わない一覧・編集のルートが自動で生えます。

複数の集計を1画面に並べる場合、フックはウィジェット単位で呼んで構いません。TanStack Queryがクエリキー単位でキャッシュを持つため、同じ集計を複数箇所で参照しても実際のリクエストは1回にまとまります。

なおRefineは、Next.jsやRemixのようにレンダリング方式まで規定するメタフレームワークではありません。ルーティングとデータ取得の層を提供するだけなので、既存のNext.jsプロジェクトの中にも同居できます。画面そのものの設計、たとえば一覧に何列出すか、フィルタをどこに置くかといった判断は、フレームワークの外側の問題です。業務システムの画面デザイン｜実装者向けUI設計パターンとライブラリ選定で扱っているパターンが、そのまま管理画面にも当てはまります。

UIパッケージで詰まる点｜peerDependenciesが指す版は最新ではない

Refineの公式UIパッケージは、対応するUIライブラリの最新メジャーに追随していません。npmのpeerDependenciesを実測すると、次のようにずれています（2026年7月29日時点）。

意味するところは単純です。公式UIパッケージを採用すると、そのUIライブラリの版が固定されます。Mantineは4メジャー、Chakra UIは1メジャー、Material UIは3メジャー離れています。既存プロジェクトがMaterial UI 9で動いているなら、@refinedev/muiをそのまま載せることはできません。

回避策は2つです。ひとつはコアだけを使い、UIは自前で書くこと。Refineのコアはヘッドレスなので、UIライブラリの版に縛られません。もうひとつは、peerDependenciesの警告を承知のうえで新しい版を入れることですが、テーマAPIの破壊的変更を踏むため推奨しません。UIライブラリの最新版を使いたい前提があるなら、UIパッケージは最初から採用しないほうが安全です。

ルーターも同じ構図です。@refinedev/react-routerはreact-router 7系を要求し、8系は範囲外です。なお旧パッケージの@refinedev/react-router-v6は4.6.2（2024-12-13公開）で更新が止まっているので、v5構成では使いません。

v4からv5への移行で壊れるもの

@refinedev/coreのv5.0.0は2025-09-03に公開されました。4系の最終版4.58.0が前日の2025-09-02なので、実質そこで系列が切り替わっています。

移行で最初に効くのは依存関係です。TanStack Query v5が必須で、v4のまま上げると動きません。Reactは18でも19でも構いません。そのうえで、次のAPIが削除・改名されています。

影響が大きいのはlegacy系の削除です。v3時代の記法を互換レイヤーで動かしていたプロジェクトは、v5では新しいプロバイダの形式に書き直す必要があります。逆にv4の標準的な書き方で組んでいれば、書き換えはフック名の置換が中心で済みます。

Refineを選ばないほうがよい場面

フレームワークの得手不得手ははっきりしています。次の条件に当てはまるなら、Refineは向きません。

• 画面が3〜4枚で終わる小規模な管理画面。resourcesやプロバイダの設定コストが、素直にfetchを書く手間を上回ります。
• CRUDではない画面が主体。ワークフロー承認や複雑な集計が中心なら、Refineの型に合わせるほうが遠回りになります。ダッシュボードだけならフレームワークは不要です。
• UIライブラリを最新メジャーで使う必要がある。前述のとおり公式UIパッケージが版を固定します。コアのみの採用に留められないなら見送りです。
• チームにReactの経験がない。フックとプロバイダの設計を理解していないと、フレームワークの内部で何が起きているか追えなくなります。

逆に、扱うリソースが10種類を超え、一覧とフォームが繰り返し発生し、認証と権限も必要——という条件では、Refineの記述量削減が効いてきます。判断の目安は画面数ではなくリソース数です。

よくある質問

Refineとは何ですか？

Reactで社内管理画面やダッシュボードなどのCRUD中心の画面を作るためのフレームワークです。データ取得・認証・権限・ルーティングをフックとして提供し、画面の見た目は自分で選びます。パッケージは@refinedev/coreを中心に構成され、2026年7月29日時点の最新は5.0.12です。

Refineは無料で使えますか？

使えます。公式パッケージはMITライセンスで公開されており、有料エディションの区分はありません。npmから@refinedev/coreとして取得できます。比較対象のreact-adminも本体はMITですが、権限制御やリアルタイム更新などは有料のEnterprise Edition側にある点が異なります。

Refineとreact-adminはどちらを選ぶべきですか？

UIを自分たちで決めたいならRefine、Material UIで早く形にしたいならreact-adminです。判断を分けるのはUIの自由度と、有料モジュールが必要になるかどうかの2点です。既存のデザインシステムに合わせる制約があるなら、UIを固定しないRefineが適します。

Refineの使い方はどこから始めればよいですか？

npm create refine-app@latestで対話的にプロジェクトを作るのが最短です。既存プロジェクトに組み込む場合は、@refinedev/coreとTanStack Query v5を入れ、data providerとrouterProviderをRefineコンポーネントに渡すところから始めます。UIパッケージは、UIライブラリの版が固定される点を確認してから足してください。

Refineはどのバックエンドにつなげられますか？

公式のdata providerが用意されているのはREST、Airtable、Appwrite、GraphQL、Simple REST、Strapi v4、Supabase、Nest.js Query、NestJS CRUD、Hasuraです。AWS Amplifyは公式一覧に含まれていないため、つなぐ場合はコミュニティ実装を使うか自作します。自作といっても実装するのは一覧・単体取得・作成・更新・削除にあたるメソッドで、REST寄りのAPIなら公式実装を土台にできます。

関連記事

• TanStack Queryとは？React Queryとの違い・v5の使い方と脆弱性対策
• 業務システムの画面デザイン｜実装者向けUI設計パターンとライブラリ選定
• HonoXとは？Hono×Viteのメタフレームワークの特徴・使い方・採用判断
• レンダリングとは？ブラウザ描画の仕組みとCSR/SSR/SSGの違い・選定基準を解説