ESモジュールスコープでのrequireエラー：完全ガイド

問題の概要

Node.jsで以下のコードを実行するとエラーが発生します：

const sass = require('gulp-sass')(require('sass'));

エラーメッセージ：

ReferenceError: require is not defined in ES module scope, you can use import instead
This file is being treated as an ES module because it has a '.js' file extension and 'C:\path\to\package.json' contains "type": "module".

根本原因

このエラーは、プロジェクトのpackage.jsonで"type": "module"が設定されている場合に発生します。これにより、.jsファイルがESモジュールとして扱われ、CommonJSのrequire関数が使用できなくなります。

解決策

方法1：import構文を使用する（推奨）

ESモジュール環境ではimport構文を使用します：

import sass from 'gulp-sass';
import dartSass from 'sass';

const sassCompiler = sass(dartSass);

方法2：package.jsonの設定を変更する

CommonJSを維持したい場合：

{
  "type": "commonjs"
}

WARNING

プロジェクト全体のモジュールシステムが変更されるため、既存のimport文に影響が出る可能性があります。

方法3：ファイル拡張子を変更する

ESモジュールとCommonJSを併用する場合：

• ESモジュール: .mjs拡張子を使用
• CommonJS: .cjs拡張子を使用

方法4：createRequireを使用する（ハイブリッド環境）

ESモジュール内でCommonJSモジュールをインポートする場合：

import { createRequire } from "module";
const require = createRequire(import.meta.url);

const sass = require('gulp-sass')(require('sass'));

追加のエラーへの対処

元の質問で発生していた追加のエラー：

const PRODUCTION = yargs.argv.prod;
// TypeError: Cannot read property 'prod' of undefined

このエラーはyargsの初期化が正しく行われていない場合に発生します。以下のように修正します：

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

const argv = yargs(hideBin(process.argv)).argv;
const PRODUCTION = argv.prod;

その他の考慮事項

Node.jsのバージョン互換性

INFO

Node.jsのバージョンとpackage.jsonのenginesフィールドが一致していることを確認してください。不一致があると予期せぬエラーが発生することがあります。

Jestテスト環境での注意点

TypeScriptとJestを使用している場合、追加の設定が必要です：

// jest.config.js
module.exports = {
  transform: {
    "^.+\\.(j|t)s?$": ["ts-jest", {
      useESM: false,
      diagnostics: {
        ignoreCodes: [1343]
      },
      astTransformers: {
        before: ["node_modules/ts-jest-mock-import-meta"]
      }
    }]
  }
};

ベストプラクティス

1. 一貫性の維持: プロジェクト内でモジュールシステムを統一する
2. 最新の構文を使用: 新しいプロジェクトではESモジュールを採用する
3. 段階的な移行: 大規模なプロジェクトでは徐々に移行する
4. ツールの互換性確認: 使用するライブラリがESモジュールに対応しているか確認する

まとめ

ESモジュールとCommonJSの混在によるエラーは、以下のいずれかの方法で解決できます：

1. import構文への移行（推奨）
2. package.jsonのtype設定変更
3. ファイル拡張子の適切な使用
4. createRequireを使ったハイブリッドアプローチ

プロジェクトの要件と既存のコードベースに合わせて最適な方法を選択してください。