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

❓ トラブルシューティング & FAQ

よくある問題、解決策、よくある質問 🔧

このガイドでは、Nodeblocksフロントエンドコンポーネントを使用する際に開発者が最も頻繁に遭遇する問題とその解決策について説明します。

📋 目次​

🚨 インストールの問題​

パッケージが見つからないエラー​

問題:

npm ERR! 404 Not Found - GET https://registry.npmjs.org/@nodeblocks%2ffrontend-navbar-block

解決策:

  1. .npmrc設定を確認:
# .npmrcが存在し、正しい内容であることを確認
cat .npmrc
  1. トークンが設定されていることを確認:
echo $NODEBLOCKS_DEV_TOKEN
  1. レジストリ設定を確認:
@nodeblocks:registry=https://registry.npmjs.org
@basaldev:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${NODEBLOCKS_DEV_TOKEN}

認証失敗（401エラー）​

問題:

npm ERR! 401 Unauthorized - GET https://registry.npmjs.org/@nodeblocks/...

解決策:

  1. トークンの有効性を確認:

    • 新しいトークンについてNodeblocksチームにお問い合わせください
    • トークンが期限切れでないことを確認

  2. 環境変数を確認:

# Linux/macOS
export NODEBLOCKS_DEV_TOKEN=your_actual_token_here

# Windows
set NODEBLOCKS_DEV_TOKEN=your_actual_token_here
  1. npmキャッシュをクリア:
npm cache clean --force

🔐 認証とレジストリ​

プライベートパッケージにアクセスできない​

問題: @nodeblocksパッケージで404またはアクセス拒否エラーが発生する。

チェックリスト:

  1. ✅ プロジェクトルートに.npmrcファイルが存在する
  2. ✅ レジストリ設定が正しい
  3. ✅ NODEBLOCKS_DEV_TOKEN環境変数が設定されている
  4. ✅ トークンが有効で期限切れでない
  5. ✅ アクセス権限がある

簡単な修正:

# 現在のnpm設定を確認
npm config list

# nodeblocksレジストリ設定を確認
npm config get @nodeblocks:registry

トークン環境変数が機能しない​

問題: トークンを設定したが、まだ認証エラーが発生する。

解決策:

  1. 現在のセッション用:
# Linux/macOS
export NODEBLOCKS_DEV_TOKEN=your_token

# Windows Command Prompt
set NODEBLOCKS_DEV_TOKEN=your_token

# Windows PowerShell
$env:NODEBLOCKS_DEV_TOKEN="your_token"
  1. 永続的な設定:
# Linux/macOS - ~/.bashrcまたは~/.zshrcに追加
echo 'export NODEBLOCKS_DEV_TOKEN=your_token' >> ~/.bashrc

# Windows - システム環境変数を使用
  1. トークンが読み込まれていることを確認:
npm install --verbose

🔧 設定の問題​

環境変数が機能しない​

問題: サービスエンドポイントが環境変数から読み込まれない。

フレームワーク固有の解決策:

Vite:

# VITE_で始まる必要があります
VITE_USER_SERVICE_URL=https://api.example.com
// コンポーネントでアクセス
const userServiceUrl = import.meta.env.VITE_USER_SERVICE_URL;

Create React App:

# REACT_APP_で始まる必要があります
REACT_APP_USER_SERVICE_URL=https://api.example.com
// コンポーネントでアクセス
const userServiceUrl = process.env.REACT_APP_USER_SERVICE_URL;

🎨 テーマの問題​

コンポーネントが正しくスタイリングされない（ThemeProviderがない）​

問題: コンポーネントが不正確なスタイル、間違った色、または壊れたレイアウトでレンダリングされる。

原因: ThemeProviderがアプリケーションをラップしていない。

解決策: アプリケーション全体をThemeProviderでラップします：

// ❌ 間違い - ThemeProviderがない
function App() {
  return (
    <div>
      <Navbar ... />
      <SignIn ... />
    </div>
  );
}

// ✅ 正しい - ThemeProviderがすべてをラップ
import { ThemeProvider } from '@nodeblocks/frontend-theme';

function App() {
  return (
    <ThemeProvider>
      <div>
        <Navbar ... />
        <SignIn ... />
      </div>
    </ThemeProvider>
  );
}

CSS変数が機能しない​

問題: var(--mui-palette-primary-main)のようなCSS変数がundefinedを返すか、機能しない。

原因: ThemeProviderがないか、cssVariablesが無効になっている。

解決策:

  1. ThemeProviderがアプリをラップしていることを確認
  2. カスタムテーマを使用している場合は、CSS変数を有効にする：
import { createTheme } from '@mui/material/styles';
import { defaultTheme, ThemeProvider } from '@nodeblocks/frontend-theme';

const customTheme = createTheme(defaultTheme, {
  cssVariables: true,  // CSS変数を使用するには有効にする必要があります
  palette: {
    primary: { main: '#your-color' }
  }
});

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      {/* アプリ */}
    </ThemeProvider>
  );
}

テーマのカスタマイズが適用されない​

問題: カスタムテーマの色やタイポグラフィがコンポーネントに適用されない。

原因と解決策:

  1. ThemeProviderにテーマを渡していない:
// ❌ 間違い - カスタムテーマが渡されていない
<ThemeProvider>

// ✅ 正しい - カスタムテーマを渡す
<ThemeProvider theme={customTheme}>
  1. 拡張ではなくすべてのデフォルトをオーバーライドしている:
// ❌ 間違い - Nodeblocksのデフォルトがすべて失われる
const customTheme = createTheme({
  palette: { primary: { main: '#8B5CF6' } }
});

// ✅ 正しい - defaultThemeを拡張
import { defaultTheme } from '@nodeblocks/frontend-theme';

const customTheme = createTheme(defaultTheme, {
  palette: { primary: { main: '#8B5CF6' } }
});
  1. ネストされたデフォルトをスプレッドしていない:
// ❌ 間違い - primary.contrastText、primary.lightなどが失われる
palette: {
  primary: { main: '#8B5CF6' }
}

// ✅ 正しい - すべてのprimaryプロパティを保持
import { palette as defaultPalette } from '@nodeblocks/frontend-theme';

palette: {
  ...defaultPalette,
  primary: { ...defaultPalette.primary, main: '#8B5CF6' }
}

📖 完全なテーマドキュメントについては、テーマガイドをご覧ください。

🖌️ スタイリングとUIの問題​

コンポーネントが期待と異なって見える​

問題: コンポーネントが期待されるデザインやドキュメントと一致しない。

解決策:

  1. グローバルCSSの競合を確認:
/* グローバルスタイルが干渉している可能性があります */
* {
  box-sizing: border-box; /* これがコンポーネントレイアウトに影響する可能性があります */
}
  1. コンポーネント固有のスタイリングを使用:
<SignIn
  style={{
    maxWidth: '400px',
    margin: '0 auto',
    padding: '2rem'
  }}
>
  {/* コンポーネントの内容 */}
</SignIn>
  1. コンポーネントがスタイルを受け付けない場合:
/* より高い特異性を使用してコンポーネントスタイルをオーバーライド */
#root .your-component-class {
  /* ここにカスタムスタイル */
  background-color: #f5f5f5;
  border-radius: 8px;
  padding: 1rem;
}

/* より具体的なオーバーライドには、複数のセレクタを使用 */
#root .product-grid .product-item {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s ease;
}

❓ よくある質問​

一般的な質問​

Q: すべてのコンポーネントをインストールする必要がありますか？ A: いいえ！必要なコンポーネントのみをインストールしてください。各コンポーネントは別々のパッケージです。

Q: スタイリングをカスタマイズできますか？ A: もちろんです！コンポーネントはMUIスタイリング用のsxプロップを受け入れ、グローバルにテーマを設定できます。テーマガイドをご覧ください。

Q: コンポーネントがスタイルなしで表示されるのはなぜですか？ A: アプリが@nodeblocks/frontend-themeのThemeProviderでラップされていることを確認してください。テーマの問題をご覧ください。

技術的な質問​

Q: NodeblocksはTypeScriptで動作しますか？ A: はい、すべてのコンポーネントにTypeScript定義が含まれています。

Q: ReduxなどのState管理ライブラリとNodeblocksを使用できますか？ A: はい、ただしDomain Appには組み込みの状態管理が提供されています。必要に応じて外部状態と統合できます。

Q: フォームバリデーションはどのように処理しますか？ A: setError、getValues、clearErrors関数でonChangeプロパティを使用します。

Q: コンポーネントの動作をオーバーライドできますか？ A: はい、例えばブロックオーバーライドパターンを使用して。高度な使用法ガイドをご覧ください。

別の問題がありますか？具体的な問題の詳細とともにサポートチームにお問い合わせください。