メインコンテンツまでスキップ

❓ トラブルシューティングガイド

このガイドでは、Nodeblocks フロントエンドコンポーネントを統合、ビルド、スタイリングする際によく発生する問題の解決策を紹介します。

🎨 壊れた、素の、または「悪い」スタイル​

症状​

コンポーネントは画面に表示されますが、まったくスタイルが当たっていないように見えます。ボタンはただの HTML ボタンのように見え、余白はずれていて、色は間違っており、公式の Basal ブランドのインターフェースではなくデフォルトの Material-UI 要素が表示されます。

原因​

Nodeblocks フロントエンドコンポーネントは、統一されたカスタマイズ済みの Material-UI (MUI) デザインシステムの上にスタイルされています。アプリケーションのルートでデザインシステムを登録せずにブロックをレンダリングすると、スタイルのないプリミティブにフォールバックします。

解決策​

React アプリケーションのルート（通常は main.tsx、index.tsx、または App.tsx）を、@nodeblocks/frontend-theme が提供する <ThemeProvider> と defaultTheme でラップしてください（@nodeblocks-frontend-blocks/packages/theme/src から提供されています）。

実装例​

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import {ThemeProvider, defaultTheme} from '@nodeblocks/frontend-theme';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider theme={defaultTheme}>
      <App />
    </ThemeProvider>
  </React.StrictMode>,
);

🌐 サーバーサイドレンダリング (SSR) と hydration の失敗​

症状​

SSR ベースのフレームワーク（Next.js、Remix、Docusaurus など）を使用すると、ビルドが次のようなエラーで失敗します: ReferenceError: window is not defined または、ブラウザのコンソールで hydration の不一致に関する警告が表示されます。

原因​

一部のサブ依存関係やインタラクティブなブロックは、生成時に window、document、navigator などのブラウザ専用グローバルにアクセスしますが、これらは Node.js のサーバー環境では利用できません。

解決策​

Next.js では、next/dynamic に ssr: false を指定して、クライアントサイドレンダリングを強制します:

import dynamic from 'next/dynamic';

const ListUsers = dynamic(() => import('@nodeblocks/frontend-list-users-block').then(mod => mod.ListUsers), {
  ssr: false,
});

export default function MyPage() {
  return <ListUsers data={[]} listUsersTitle="Members" labels={{}} />;
}

📦 不足している peer dependency エラー​

症状​

Nodeblocks パッケージのインストール時に npm install の途中で警告/エラーが出るか、次のようなコンパイル失敗が発生します: Module not found: Can't resolve '@mui/material' または @emotion/react

原因​

バンドルサイズを最適化し、アプリケーション内で同じライブラリの複数バージョンが混在するのを避けるために、Nodeblocks は Material-UI や Emotion のようなコア UI エンジンを peer dependencies として扱っています。これらの peer パッケージは自分でインストールする必要があります。

解決策​

必要な Material-UI と Emotion の peer dependency がインストールされていることを確認してください:

# npm
npm install @mui/material @mui/icons-material @emotion/react @emotion/styled

# yarn
yarn add @mui/material @mui/icons-material @emotion/react @emotion/styled

# pnpm
pnpm add @mui/material @mui/icons-material @emotion/react @emotion/styled

🛑 アクション / クリックイベントハンドラーが動作しない​

症状​

タブのクリック、ページ変更、検索、またはチップフィルターの削除をしても、テーブルデータが変わらない、または UI 状態が更新されません。

原因​

Nodeblocks のブロックは、最大限のレイアウト制御を可能にするために プレゼンテーション用（ステートレス）コンポーネント として作られています。内部でリスト、検索キーワード、アクティブタブ、ページ数などの状態は保持しません。

解決策​

onTabChange、onPageChange、onSearchFieldChange、onSearchSubmit のようなコールバック props の中でイベントを受け取り、ローカルの React state を更新してください。その state は props として再度渡し戻します。

各ブロックのページにあるコード例（たとえば List Users → Quick Start）を確認すると、これらの state バインディングをどのように接続するかが分かります。