Zenn
📑

tsconfig.jsonのesModuleInterop

2024/03/24に公開
Next.js
TypeScript
tech

まとめ

概要
esModuleInterop を true にすると、TypeScript は CommonJS/AMD/UMD モジュールを ES6 モジュールと同様に扱います。

デフォルト
module が node16 か nodenext の場合はデフォルトで esModuleInterop が true になります。それ以外の場合は false になります。

Next.js
create next-app で作成した Next.js プロジェクトで esModuleInterop は true が設定されています。利便性の観点から特段理由がなければ esModuleInterop を有効化しておくことをお勧めします。

tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true,
  }
}

補足
公式の説明はこちらです。

https://www.typescriptlang.org/ja/tsconfig#esModuleInterop

以下が作業リポジトリです。

https://github.com/hayato94087/tsconfig-esmoduleinterop

https://github.com/hayato94087/next-tsconfig-es-module-interop

この記事の内容
この記事では esModuleInterop が false の場合と true の場合で動作を確認します。
Node.js & TypeScript のプロジェクトと Next.js のプロジェクトで動作確認を行います。

Node.js & TypeScriptのプロジェクトで動作確認

TypeScript の簡易プロジェクトを作成し、esModuleInterop が false の場合と true の場合で動作を確認します。

esModuleInterop が false の場合

esModuleInterop が false の場合、TypeScript は CommonJS/AMD/UMD モジュールを EcmaScript のモジュール標準と同様に扱えません。エラーになることをここでは確認します。

TypeScript の簡易プロジェクトを作成し動作確認をします。

まず、package.json を作成します。

$ mkdir tsconfig-esmoduleinterop
$ cd tsconfig-esmoduleinterop
$ pnpm init

下記で package.json を上書きします。ポイントは scripts に 3 つのスクリプトを追加しています。typecheck で型をチェックし、dev でローカルで動作確認、build でトランスパイルします。

package.json
{
  "name": "tsconfig-esmoduleinterop",
  "version": "1.0.0",
  "description": "",
  "main": "index.ts",
  "scripts": {
    "typecheck": "tsc --noEmit",
    "dev": "ts-node index.ts",
    "build": "tsc"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

TypeScript をインストールします。

$ pnpm install -D typescript ts-node

tsconfig.json を作成します。

$ npx tsc --init

tsconfig.json を作成します。esModuleInterop に false を設定しています。

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2019",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": false,
    "forceConsistentCasingInFileNames": true,
  },
  "include": ["**/*"]
}

git を初期化します。

$ git init

.gitignore を作成します。

$ touch .gitignore

git の管理対象外にするファイルを追加します。

.gitignore
node_modules

CommonJS モジュールのパッケージを追加します。

$ pnpm add snakecase-keys

追加した CommonJS モジュールのパッケージを利用するスクリプトを作成します。

$ touch index.ts
index.ts
import snakecaseKeys from 'snakecase-keys';

const user = { userName: 'micheal', emailAddress: 'taro@gmail.com' };

const userSnakeCase = snakecaseKeys(user);

console.log(userSnakeCase);

型をチェックします。

$ pnpm run typecheck

index.ts:1:8 - error TS1259: Module '"/Users/hayato94087/Private/tsconfig-esmoduleinterop/node_modules/.pnpm/snakecase-keys@6.0.0/node_modules/snakecase-keys/index"' can only be default-imported using the 'esModuleInterop' flag

1 import snakecaseKeys from 'snakecase-keys';
         ~~~~~~~~~~~~~

  node_modules/.pnpm/snakecase-keys@6.0.0/node_modules/snakecase-keys/index.d.ts:120:1
    120 export = snakecaseKeys;
        ~~~~~~~~~~~~~~~~~~~~~~~
    This module is declared with 'export =', and can only be used with a default import when using the 'esModuleInterop' flag.


Found 1 error in index.ts:1

エラーが出る理由は、TypeScript は ECMAScript のモジュール標準に準拠しています。import snakecaseKeys from 'snakecase-keys' のような構文をサポートするには、そのファイルに default export が含まれている必要があります。が、インポートしている、snakecase-keys は CommonJS のモジュールであり、default export は含まれていることは稀です。

snakecase-keys のソースコードはこちらです。default export は含まれていません。
https://github.com/bendrucker/snakecase-keys/blob/master/index.js

tsc でトランスパイルします。default import が必要だとエラーは出ますがトランスパイルされた結果は保存されます。

$ pnpm run build

index.ts:1:8 - error TS1259: Module '"/Users/hayato94087/Private/tsconfig-esmoduleinterop/node_modules/.pnpm/snakecase-keys@6.0.0/node_modules/snakecase-keys/index"' can only be default-imported using the 'esModuleInterop' flag

1 import snakecaseKeys from 'snakecase-keys';
         ~~~~~~~~~~~~~

  node_modules/.pnpm/snakecase-keys@6.0.0/node_modules/snakecase-keys/index.d.ts:120:1
    120 export = snakecaseKeys;
        ~~~~~~~~~~~~~~~~~~~~~~~
    This module is declared with 'export =', and can only be used with a default import when using the 'esModuleInterop' flag.


Found 1 error in index.ts:1

トランスパイルの結果はこちらです。

./dist/index.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const snakecase_keys_1 = require("snakecase-keys");
const user = { userName: 'micheal', emailAddress: 'taro@gmail.com' };
const userSnakeCase = (0, snakecase_keys_1.default)(user);
console.log(userSnakeCase);
//# sourceMappingURL=index.js.map

作業結果をコミットします。

$ git add .
$ git commit -m "feat:esModuleInteropを無効化しエラーを確認"

esModuleInterop が true の場合

エラーを解消するために esModuleInterop を有効化します。esModuleInterop を有効化することで、ECMAScript のモジュールの使用に準拠した形で CommonJS のモジュールをインポートできるようになります。

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2019",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "strict": true,
    "skipLibCheck": true,
-   "esModuleInterop": false,
+   "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
  },
  "include": ["**/*"]
}

型をチェックします。特にエラーは出ません。

$ pnpm run typecheck

ローカルの開発環境で動作確認します。問題無く動作します。

$ pnpm run dev

{ user_name: 'micheal', email_address: 'taro@gmail.com' }

tsc でトランスパイルします。トランスパイルした結果は ./dist に保存されます。

$ pnpm tsc

トランスパイルの結果はこちらです。esModuleInterop を有効化することで、index.js に __importDefault という関数が追加されました。これにより import snakecaseKeys from 'snakecase-keys'; のような構文がサポートされるようになりました。

./src/index.js
"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
Object.defineProperty(exports, "__esModule", { value: true });
-const snakecase_keys_1 = require("snakecase-keys");
+const snakecase_keys_1 = __importDefault(require("snakecase-keys"));
const user = { userName: 'micheal', emailAddress: 'taro@gmail.com' };
const userSnakeCase = (0, snakecase_keys_1.default)(user);
console.log(userSnakeCase);
//# sourceMappingURL=index.js.map

作業結果をコミットします。

$ git add .
$ git commit -m "feat:esModuleInteropを有効化しエラーを解消"

Next.jsのプロジェクトで動作確認

Next.js のプロジェクトを作成し、esModuleInterop が false の場合と true の場合で動作を確認します。

esModuleInterop が false の場合

動作を作業するための Next.js プロジェクトを作成します。長いので、折り畳んでおきます。

新規プロジェクト作成と初期環境構築の手順詳細

プロジェクトを作成

create next-app@latestでプロジェクトを作成します。

$ pnpm create next-app@latest next-tsconfig-es-module-interop --typescript --eslint --import-alias "@/*" --src-dir --use-pnpm --tailwind --app
$ cd next-tsconfig-es-module-interop

Peer Dependenciesの警告を解消

Peer dependenciesの警告が出ている場合は、pnpm installを実行し、警告を解消します。

 WARN  Issues with peer dependencies found
.
├─┬ autoprefixer 10.0.1
│ └── ✕ unmet peer postcss@^8.1.0: found 8.0.0
├─┬ tailwindcss 3.3.0
│ ├── ✕ unmet peer postcss@^8.0.9: found 8.0.0
│ ├─┬ postcss-js 4.0.1
│ │ └── ✕ unmet peer postcss@^8.4.21: found 8.0.0
│ ├─┬ postcss-load-config 3.1.4
│ │ └── ✕ unmet peer postcss@>=8.0.9: found 8.0.0
│ └─┬ postcss-nested 6.0.0
│   └── ✕ unmet peer postcss@^8.2.14: found 8.0.0
└─┬ next 14.0.4
  ├── ✕ unmet peer react@^18.2.0: found 18.0.0
  └── ✕ unmet peer react-dom@^18.2.0: found 18.0.0

以下を実行することで警告が解消されます。

$ pnpm i -D postcss@latest react@^18.2.0 react-dom@^18.2.0

不要な設定を削除し、プロジェクトを初期化します。

styles

CSSなどを管理するstylesディレクトリを作成します。globals.cssを移動します。

$ mkdir -p src/styles
$ mv src/app/globals.css src/styles/globals.css

globals.cssの内容を以下のように上書きします。

src/styles/globals.css
@tailwind base;
@tailwind components;
@tailwind utilities;

初期ページ

app/page.tsxを上書きします。

src/app/page.tsx
import { type FC } from "react";

const Home: FC = () => {
  return (
    <div className="">
      <div className="text-lg font-bold">Home</div>
      <div>
        <span className="text-blue-500">Hello</span>
        <span className="text-red-500">World</span>
      </div>
    </div>
  );
};

export default Home;

レイアウト

app/layout.tsxを上書きします。

src/app/layout.tsx
import "@/styles/globals.css";
import { type FC } from "react";
type RootLayoutProps = {
  children: React.ReactNode;
};

export const metadata = {
  title: "Sample",
  description: "Generated by create next app",
};

const RootLayout: FC<RootLayoutProps> = (props) => {
  return (
    <html lang="ja">
      <body className="">{props.children}</body>
    </html>
  );
};

export default RootLayout;

TailwindCSSの設定

TailwindCSSの設定（tailwind.config.ts）を上書きします。

tailwind.config.ts
import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  plugins: [],
}
export default config

TypeScriptの設定

TypeScriptの初期設定はこちらです。

tsconfig.json
{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

TypeScriptの設定を上書きします。

tsconfig.json
{
  "compilerOptions": {
    "target": "es2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "checkJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "noUncheckedIndexedAccess": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "plugins": [
      {
        "name": "next"
      }
    ],
  },
  "include": [
    ".eslintrc.cjs",
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "**/*.cjs",
    "**/*.mjs",
    ".next/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

スクリプトを追加

型チェックのスクリプトを追加します。

package.json
{
  "name": "next-tsconfig-strict",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
+   "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "next": "14.1.4"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "autoprefixer": "^10.0.1",
    "eslint": "^8",
    "eslint-config-next": "14.1.4",
    "postcss": "^8.4.37",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "tailwindcss": "^3.3.0",
    "typescript": "^5"
  }
}

動作確認

ローカルで動作確認します。

$ pnpm run dev

コミットして作業結果を保存しておきます。

$ git add .
$ git commit -m "feat:新規にプロジェクトを作成し, 作業環境を構築"

esModuleInterop を無効化します。

tsconfig.json
{
  "compilerOptions": {
    "target": "es2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "checkJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
-   "esModuleInterop": true,
+   "esModuleInterop": false,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "noUncheckedIndexedAccess": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "plugins": [
      {
        "name": "next"
      }
    ],
  },
  "include": [
    ".eslintrc.cjs",
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "**/*.cjs",
    "**/*.mjs",
    ".next/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

CommonJS モジュールのパッケージを追加します。

$ pnpm add snakecase-keys

追加した CommonJS モジュールのパッケージを利用する文を追加します。正しく動作すれば、コンソールに { user_name: 'Taro Yamada' } が表示されます。

src/app/page.tsx
+import snakecaseKeys from "snakecase-keys";
import { type FC } from "react";

const Home: FC = () => {
+ console.log(snakecaseKeys({ userName: "Taro Yamada" }));

  return (
    <div className="">
      <div className="text-lg font-bold">Home</div>
      <div>
        <span className="text-blue-500">Hello</span>
        <span className="text-red-500">World</span>
      </div>
    </div>
  );
};

export default Home;

型をチェックします。

$ pnpm run typecheck

src/app/page.tsx:1:8 - error TS1259: Module '"/Users/hayato94087/Private/next-tsconfig-es-module-interop/node_modules/.pnpm/snakecase-keys@6.0.0/node_modules/snakecase-keys/index"' can only be default-imported using the 'allowSyntheticDefaultImports' flag

1 import snakecaseKeys from "snakecase-keys";
         ~~~~~~~~~~~~~

  node_modules/.pnpm/snakecase-keys@6.0.0/node_modules/snakecase-keys/index.d.ts:120:1
    120 export = snakecaseKeys;
        ~~~~~~~~~~~~~~~~~~~~~~~
    This module is declared with 'export =', and can only be used with a default import when using the 'allowSyntheticDefaultImports' flag.


Found 1 error in src/app/page.tsx:1

エラーが出る理由は、TypeScript は ECMAScript のモジュール標準に準拠しています。import snakecaseKeys from 'snakecase-keys' のような構文をサポートするには、そのファイルに default export が含まれている必要があります。が、インポートしている、snakecase-keys は CommonJS のモジュールであり、default export は含まれていることは稀です。

snakecase-keys のソースコードはこちらです。default export は含まれていません。
https://github.com/bendrucker/snakecase-keys/blob/master/index.js

コミットします。

$ git add .
$ git commit -m "feat:esModuleInteropを無効化しエラーを確認"

esModuleInterop が true の場合

エラーを解消するために esModuleInterop を有効化します。esModuleInterop を有効化することで、ECMAScript のモジュールの使用に準拠した形で CommonJS のモジュールをインポートできるようになります。

tsconfig.json
{
  "compilerOptions": {
    "target": "es2017",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "checkJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
-   "esModuleInterop": false,
+   "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "noUncheckedIndexedAccess": true,
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./src/*"
      ]
    },
    "plugins": [
      {
        "name": "next"
      }
    ]
  },
  "include": [
    ".eslintrc.cjs",
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "**/*.cjs",
    "**/*.mjs",
    ".next/types/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

型をチェックします。特にエラーは出ません。

$ pnpm run typecheck

ローカルで動作確認します。ターミナルに { user_name: 'Taro Yamada' } が表示されれば成功です。

$ pnpm run dev

   ▲ Next.js 14.1.4
   - Local:        http://localhost:3000

 ✓ Ready in 2.4s
 ○ Compiling / ...
 ✓ Compiled / in 3.2s (462 modules)
{ user_name: 'Taro Yamada' }
 ✓ Compiled in 323ms (220 modules)

コミットします。

$ git add .
$ git commit -m "feat:esModuleInteropを有効化しエラーを解消"

Next.jsの設定考察

create next-app で作成した Next.js プロジェクトで esModuleInterop は true が設定されています。利便性の観点から特段理由がなければ esModuleInterop を有効化しておくことをお勧めします。

さいごに

esModuleInterop を true にすると、TypeScript は CommonJS/AMD/UMD モジュールを ES6 モジュールと同様に扱います。Node.js & TypeScript のプロジェクトと Next.js のプロジェクトで動作確認を行いました。

参考

https://qiita.com/eyuta/items/fccebb53d88798c76da5

https://numb86-tech.hatenablog.com/entry/2020/07/11/160159

https://dev.classmethod.jp/articles/esmoduleinterop-flag-for-typescript/

Discussion