~7 分で読める · チュートリアル

私は多くの MUI 管理テンプレートを見てきました。material-kit-react from the minimals people は、何度も見返してしまうものの一つです。クリーンで型付けされており、フォルダ構造も理にかなっています。リポジトリ: minimal-ui-kit/material-kit-react。

しかし、単に見てみたい場合や、色を一つ変えて確認したい場合、毎回同じ儀式を繰り返すことになります。git clone、npm install、待機、npm run dev、さらに待機、localhost にタブを切り替える。数分が過ぎ、ディスクに数百 MB の node_modules が残ります。すべてダッシュボードを見るためだけです。

そこで今回はビルドをスキップしました。フォルダを CrossUI Studio で開き、src/main.tsx を直接レンダリングしました。インストールも、Vite も、localhost も不要です。以下に私が実際にやったことと、途中で考えさせられた点をまとめます。

最初に正直な注記を。これは開発サーバーの代わりにはなりません。テストや本番ビルド、実際の機能開発には依然として本物が必要です。これは「見て調整する」ループに適しています。テンプレートの評価、色の変更、クライアントへのデモなど、ツールチェーン全体を起動するコストがタスク自体よりも高くつく場面で有効です。

クイックノート: ローカルフォルダのサポートには Pro アカウントが必要です。試用するには、元のブログのコードで無料アップグレードをご利用ください。クレジットカードは不要で、在庫がある限りご利用いただけます。

お使いのブラウザは動画をサポートしていません。YouTube でご覧ください。

1. ローカルディスクにクローンする（GitHub から直接開かない）

Studio は GitHub リポジトリを直接マウントできます。小規模なリポジトリではこれが最も快適な方法です。今回はまずディスクにクローンしました:

git clone https://github.com/minimal-ui-kit/material-kit-react

フルスクリーンにする フルスクリーンを解除する

理由は単純です。src/ だけでも約 130 ファイル、プロジェクト全体で約 245 ファイルに及び、sections/、components/、layouts/、theme/、routes/ に分散しています。プロジェクトを開くと、ツールは触れるファイルをすべて取得する必要があります。GitHub API 経由でオンデマンドに取得すると、リクエストが大量に発生します。動作はしますが、レスポンスは遅く、操作を続けるとレート制限に達する可能性があります。ローカルフォルダの場合はファイルシステムに直接アクセスするため、瞬時に動作します。この規模のテンプレートでは、ローカルの方が優位です。

ここでは npm install は行いません。ソースのみをクローンしました。ビルドしないことが目的です。

2. フォルダを開く — プロジェクト設定を生成させる

Studio で ローカルフォルダ を開き、クローンした material-kit-react ディレクトリを選択します。ツリーを読み込みます。インストールも実行も行わず、ファイルはディスク上に残ります。最後の点は、クライアントのコードベースを「見るためだけに」どこかにアップロードしたくない場合に重要です。

CrossUI Studio — React と MUI 向けビジュアル IDE

初回起動時、Studio はプロジェクト設定ファイルが存在しないことを検知し、プロンプトを表示します:

このプロジェクトには CrossUI Studio の設定ファイルがありません。まず自動スキャンで設定ファイルを生成し、その後手動で編集することをお勧めします。

CrossUI Studio — React と MUI 向けビジュアル IDE

スキャンして生成 をクリックします。プロジェクトの既存設定ファイルを解析し、ルートに設定ファイルを出力します。以降、テンプレートが使用するインポートは Vite を介さずに解決されます。設定は一切不要でした。

CrossUI Studio — React と MUI 向けビジュアル IDE

後で手動編集も可能です。生成されたファイルを直接開いて Project Settings ダイアログで編集できますが、以下の作業では自動生成された設定で十分でした。数秒で完了し、依然として npm install はゼロです。

3. src/main.tsx を開いてプレビューを実行

Project Settings ダイアログを閉じると、Studio はエントリーファイルを自動で開きます。ファイルツリー内を探索する必要はありません。

通常は「そのままレンダリング」できないファイルです:

// src/main.tsx
const router = createBrowserRouter([
  {
    Component: () => (
      <App>
        <Outlet />
      </App>
    ),
    errorElement: <ErrorBoundary />,
    children: routesSection,
  },
]);

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>
);

フルスクリーンにする フルスクリーンを解除する

これは Vite のエントリーファイルです。createBrowserRouter + RouterProvider を使用し、アプリ全体が <App>（テーマプロバイダー）と routesSection（ルート定義）の内側にあります。このファイルをそのまま分離してレンダリングしようとすると、router コンテキストもテーマも、アプリが期待する #root も存在しないためエラーになります。

それでもレンダリングされました。何も設定していません。main.tsx を開いてプレビューをクリックしただけで、MUI テーマを含むダッシュボードがキャンバスに表示されました。

CrossUI Studio — React と MUI 向けビジュアル IDE

Design Mode に戻ります。エントリーファイルからプロバイダーを自動検出しているようです。起動時に特殊な処理をしているテンプレートの場合は、手動で正しいエントリーファイルを指定する必要があります。material-kit の場合は app.tsx がシンプルだったため、そのまま動作しました:

// src/app.tsx
export default function App({ children }: AppProps) {
  return (
    <ThemeProvider>
      {children}
      {/* github fab */}
    </ThemeProvider>
  );
}

フルスクリーンにする フルスクリーンを解除する

エントリーファイルがクリーンであることが重要です。詳細は後述します。

4. ドリルダウン — プロバイダーが自動で追従する（これが本質）

/ のダッシュボードは単一のコンポーネントではありません。遅延ロードのスタックです:

main.tsx  (RouterProvider と検出された ThemeProvider がここで定義)
  └─ routesSection              (src/routes/sections.tsx)
       └─ DashboardPage          (src/pages/dashboard.tsx, lazy)
            └─ OverviewAnalyticsView   (src/sections/overview/view)
                 └─ AnalyticsWidgetSummary ×4   (src/sections/overview, 統計カード)

フルスクリーンにする フルスクリーンを解除する

CrossUI Studio — React と MUI 向けビジュアル IDE

キャンバス上で Ctrl+クリック すると、ツリーを一段ずつ下に降りられます。嬉しい発見: プロバイダーのラッピングが自動で追従します。 Render Decorations パネルを開くと、どの階層でも RouterProvider と ThemeProvider の 2 つのラッパーが表示されます:

  • main.tsx では両方が表示されますが、RouterProvider は自動スキップされます。このファイル内で定義されているため、重複適用を避けるためです。テーマのみが適用されます。
  • sections.tsx、dashboard.tsx 以下では両方が有効（パネルに "2" と表示）です。router とテーマのコンテキストが途切れず維持されます。手動で「missing provider」を修正する必要はありませんでした。

通常、深い階層のファイルを分離してレンダリングする際に最も苦労する点ですが、ここでは自動で処理されました。目的のファイルに到達するまでに 2 つの小さな迂回がありました。どちらもクラッシュではありません。実際のコードが持つ自然な形です。

迂回 1 — sections.tsx が誤った JSX ブロック（renderFallback）で開く。

ルーターファイルに Ctrl+クリック すると、Suspense のスピナーである renderFallback に着地します:

// src/routes/sections.tsx
const renderFallback = () => (
  <Box sx={{ display: 'flex', flex: '1 1 auto', alignItems: 'center', justifyContent: 'center' }}>
    ...
  </Box>
);

フルスクリーンにする フルスクリーンを解除する

キャンバスはほぼ空になります。1 つのファイルに複数の JSX ブロックが存在し、このスピナーが先頭にあっただけです。上部にブロックナビゲーター（パンくずリストのドロップダウン）があり、すべてのブロックを一覧できます。routesSection とその子要素にジャンプしました:

export const routesSection: RouteObject[] = [
  {
    element: ( /* <DashboardLayout><Suspense><Outlet/></Suspense></DashboardLayout> */ ),
    children: [
      { index: true, element: <DashboardPage /> },
      { path: 'user',     element: <UserPage /> },
      { path: 'products', element: <ProductsPage /> },
      { path: 'blog',     element: <BlogPage /> },
    ],
  },
  // sign-in, 404 ...
];

フルスクリーンにする フルスクリーンを解除する

CrossUI Studio — React と MUI 向けビジュアル IDE

{ index: true, element: <DashboardPage /> }（/ ルート）を選択すると、ダッシュボード全体がレンダリングされました。テーマは自動ラッパーから引き継がれています。DashboardPage が UserPage / ProductsPage の隣にあるのが一目でわかります。ルート定義が URL マップのように読めます。

CrossUI Studio — React と MUI 向けビジュアル IDE

教訓: ファイルに複数の JSX ブロックがある場合、最初に表示されるものを信用せず、ブロックナビゲーターを使って目的のブロックに移動してください。

迂回 2 — index.ts はバレルで、コンポーネントではない。

DashboardPage からさらにドリルダウンすると次のファイルに到達しました:

// src/sections/overview/view/index.ts
export * from "./overview-analytics-view.tsx";

フルスクリーンにする フルスクリーンを解除する

CrossUI Studio — React と MUI 向けビジュアル IDE

NO-TARGET-JSX: No target jsx block found in the file。正しい挙動です。これは再エクスポートで、JSX は含まれていません。sections/ ではこうした短いバレルが多用されており、インポートを簡潔に保っています（from 'src/sections/overview/view' のようにフルパスを書かずに済む）。ファイル一覧から overview-analytics-view.tsx をクリックしてソースファイルを開きます。overview-analytics-view.tsx が開かれ、テーマが適用された状態で表示されます。これが実際に編集するファイルです（次のセクション）。

この 2 つの「停止点」はエラーではありませんでした。プロバイダーは自動で追従し、1 つ目は複数の JSX ブロックを持つファイル（ナビゲーターを使用）、もう 1 つはバレル再エクスポート（クリックして進む）でした。どちらも半秒程度の小さな迂回ですが、テンプレートの構成をよく表しています。

CrossUI Studio — React と MUI 向けビジュアル IDE

（エディタ上部のブロックナビゲーターでも、任意の階層に直接ジャンプできます。）

5. 何かを変更する

overview-analytics-view.tsx は 4 つの統計カードに props を渡す場所で、読みやすい構造になっています:

<AnalyticsWidgetSummary
  title="Weekly sales"
  percent={2.6}
  total={714000}
  // color は primary がデフォルト
/>

フルスクリーンにする フルスクリーンを解除する

キャンバスとインスペクターから 2 つの小さな編集を行いました。「Weekly sales」カードの color を warning に変更し、total の値を増やしました。次に「New users」カードの color を secondary から success に変更しました。生成された差分はまさにその変更のみです:

   <AnalyticsWidgetSummary
     title="Weekly sales"
     percent={2.6}
-    total={714000}
+    total={928000}
+    color="warning"
     ...
   />
   <AnalyticsWidgetSummary
     title="New users"
     percent={-0.1}
     total={1352831}
-    color="secondary"
+    color="success"
     ...
   />

フルスクリーンにする フルスクリーンを解除する

CrossUI Studio — React と MUI 向けビジュアル IDE

再フォーマットもなく、インポートも変更されず、他のカードはバイト単位で同一です。このツールで最も重視する点です。内部モデルからファイル全体を再生成するのではなく、実際に自分が書いたであろう編集をそのまま出力してほしい。今回はプロパティの外科的な変更が行われました。

より大きな変更が必要な場合はテーマを編集します。src/theme/ でパレットを定義しており、primary カラーを変更すればボタン、ナビゲーション、アクティブ状態など全体に反映されます。同じループで、より広い影響範囲を持ちます。

6. アプリ全体に戻る — ブラウザの戻るボタンを押すだけ

予想以上に気に入った小さな機能です。ファイルツリーから main.tsx を再度開いて戻る必要がありませんでした。ドリルダウンの各ステップは実際のナビゲーションで、URL が変わるため、ブラウザの戻るボタンでそのまま戻れます。ビュー → ページ → ルート → main.tsx。進む・戻るが通常の Web アプリのように動作します。数回戻ると、編集が反映された完全なダッシュボードが表示されます。「Weekly sales」カードは、変更した分離ビューだけでなく、実際のレイアウト内でも琥珀色になっています。

CrossUI Studio — React と MUI 向けビジュアル IDE

ビュー深部で編集し、戻るボタンで全体を確認する一連の流れは、通常はリロードとコンテキストの切り替えを必要とします。ここでは同じキャンバスと戻るボタンだけで完了します。

git clone から「実行中のダッシュボードで琥珀色のカードを確認」までの所要時間は数分で、そのほとんどがクローン時間です。npm install は一切ありません。

摩擦が生じた理由（テンプレート作者への注記）

完全に摩擦ゼロではありませんでした。ドリルダウン中に 2 つの小さな迂回がありました。しかし、どちらも予測可能な場所（複数ブロックを持つルーターファイルとバレル再エクスポート）で、ワンクリックで解決できました。予測可能だった大きな理由はツールではなく、テンプレート自体の構成にあります。material-kit-react は協調性の高い作りになっています:

  • エントリー（main.tsx / app.tsx）がシンプルです。プロバイダーが直接記述されており、3 層の間接参照で隠されていません。そのため RouterProvider と ThemeProvider が検出され、ドリルダウンしたすべての階層で適用され続けました。テーマコンテキストは自動で引き継がれ、手動修正は不要でした。
  • ルートは lazy() で routesSection にまとめられており、ブロックナビゲーターが URL 構造のように読めます。DashboardPage が UserPage / ProductsPage の隣にあるのが一目でわかります。
  • sections/ は短いバレル index.ts の背後に機能ごとに分割されています。実際のアプリではインポートが簡潔になり、ドリルダウン時は export * の行をクリックするだけで済みます。予測可能なパターンは、巧妙なパターンよりも優れています。
  • カードはプレーンな props を受け取ります。AnalyticsWidgetSummary は title/total/percent/color/chart のみで、ビューから供給されます。ビューから編集するのはデータ変更であり、バックエンド呼び出しではなく、差分は 1 行に収まります。

より複雑なテンプレートでは、この方法でのプレビューは難しくなります。動的に組み立てられるプロバイダー、2000 行の単一ページ、実際のフェッチデータがなければ動作しないセクションなどです。優れたテンプレート構造は、「ビルドせずに開く」を現実的にする大きな要因です。material-kit-react の構造には敬意を表します。実際に機能しています。

テンプレートを制作・販売する方への実践的な示唆です。テンプレートを評価しようとする人が最初に直面する摩擦の大部分は、クローン→インストール→実行という税金です。ソースから直接プレビュー・編集可能にすることで、その税金を大幅に削減できます。検討する価値があります。

使わない方がよい用途

  • テストスイートの実行や実際の Vite ビルド。これはプレビュー + 編集用であり、CI ではありません。
  • ライブのバックエンドデータがなければレンダリングできないもの。ドリルダウン用にモックすることは可能ですが、別のワークフローになります。
  • ランタイム動作の最終判断。これはソースから構造をレンダリングするものであり、アプリが実際にエンドツーエンドで実行される様子を監視するものではありません。

「このテンプレートを開いて少し変更し、コンテキストの中で確認する」という、管理キットを選定する前に最もよく行う作業では、ビルドをスキップすることで手間が大幅に減りました。

クイックノート: ローカルフォルダのサポートには Pro アカウントが必要です。試用するには、元のブログのコードで無料アップグレードをご利用ください。クレジットカードは不要で、在庫がある限りご利用いただけます。