ReactのUMDグローバルエラー：原因と解決策

問題の概要

ReactプロジェクトでTypeScriptを使用している際に、以下のエラーが発生することがあります：

'React' refers to a UMD global, but the current file is a module.
Consider adding an import instead.ts(2686)

このエラーは、Reactコンポーネントを定義しているがReactを明示的にインポートしていない.tsxファイルで発生します。

// エラーが発生する例
const Users = () => {
    return <>Teachers aka Users</>;
};

export default Users;

エラーの原因

このエラーは、TypeScriptコンパイラがJSX構文を適切に処理できないために発生します。React 17以降では「新しいJSX変換」が導入され、各ファイルで明示的にReactをインポートする必要がなくなりました。しかし、TypeScriptの設定がこの新しい仕様に対応していない場合、このエラーが表示されます。

解決策

1. TypeScript設定の更新（推奨）

最も根本的な解決策は、tsconfig.jsonを適切に設定することです。

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "target": "es2015", // または "esnext"
    "module": "esnext",
    "strict": true,
    "allowJs": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    ".storybook/*" // Storybookを使用している場合
  ]
}

重要

• jsx: "react-jsx"：新しいJSX変換を有効にします
• target: "es2015"以上：新しいJSX変換にはES2015以上のターゲットが必要です
• include：プロジェクトのすべての関連ファイルを含めるように設定します

2. Viteを使用している場合

Viteプロジェクトでは、tsconfig.node.jsonにも設定が必要な場合があります。

// tsconfig.node.json
{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

3. Babelの設定（カスタムセットアップの場合）

カスタムWebpack設定を使用している場合は、Babelの設定も確認してください。

// babel.config.js
module.exports = {
  presets: [
    ["@babel/preset-react", {
      "runtime": "automatic" // これが新しいJSX変換を有効にします
    }]
  ]
};

4. TypeScriptサーバーの再起動（VS Code）

設定を変更した後、VS CodeでTypeScriptサーバーを再起動します。

1. Ctrl+Shift+P（Windows）または Cmd+Shift+P（Mac）でコマンドパレットを開く
2. 「TypeScript: Restart TS server」を選択して実行

ヒント

プロジェクトを閉じて再度開くだけでも解決することがあります。

5. ワークスペースのTypeScriptバージョン確認

VS Codeが正しいTypeScriptバージョンを使用していることを確認します。

1. コマンドパレットを開く
2. 「TypeScript: Select TypeScript Version」を選択
3. ワークスペースのバージョン（node_modules内のもの）を選択

その他の状況別対応

JavaScriptプロジェクトでエラーが発生する場合

JavaScriptファイルで同様のエラーが発生する場合は、VS Codeの設定を確認してください。

// settings.json
{
  "js/ts.implicitProjectConfig.checkJs": false
}

特定のディレクトリでエラーが発生する場合

.storybookディレクトリなど、特定のパスでエラーが発生する場合は、tsconfig.jsonのinclude設定に該当パスを追加します。

{
  "include": [
    "src/**/*",
    ".storybook/*"
  ]
}

非推奨の解決方法

以下の方法は一時的な解決策として機能しますが、最新のReactのベストプラクティスに反するため、推奨されません。

// 非推奨：明示的なReactインポート
import React from 'react';

const Users = () => {
    return <>Teachers aka Users</>;
};

export default Users;

// 非推奨：ESLintでのグローバル定義
{
  "globals": {
    "React": "readonly"
  }
}

まとめ

ReactのUMDグローバルエラーは、TypeScriptの設定がReact 17の新しいJSX変換に対応していないことが主な原因です。tsconfig.jsonでjsx: "react-jsx"を設定し、適切なターゲットバージョンを指定することで解決できます。設定変更後は、TypeScriptサーバーの再起動を忘れずに行いましょう。

新しいJSX変換はバンドルサイズの最適化やパフォーマンス向上など多くの利点があるため、明示的なReactインポートに戻るのではなく、正しい設定で対応することをお勧めします。