Zenn
📛

tsconfig.json の moduleDetection

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

概要

moduleDetection は、ファイルがスクリプトであるかモジュールであるかを TypeScript がどのように判断するかを制御します。選択肢は 3 つあります。公式の説明は以下です。

値 説明
auto TypeScriptは、importおよびexportステートメントを探すだけでなく、module: nodenextまたはnode16で実行される際にpackage.jsonの"type"フィールドが"module"に設定されているかどうかをチェックし、jsx: react-jsxで実行される場合に現在のファイルがJSXファイルであるかどうかもチェックします。
legacy 4.6 以前と同じ動作に、importおよびexportを使用してファイルがモジュールかどうかを判断します。
force すべての非宣言ファイルがモジュールとして扱われるようにします。

ですが、この説明は少しわかりにくいです。もう少し分かりやすく説明すると以下のとおりとなります。

値 説明
auto TypeScript はファイルがモジュールかスクリプトかを自動で判断します。
legacy TypeScript はファイルがモジュールかスクリプトかを import および export を使用して判断します
force すべての非宣言ファイルがモジュールとして扱われるようにします。

moduleDetection は auto がデフォルト値です。

Next.js の設定考察

create next-app で作成した Next.js プロジェクトで moduleDetection は記載されていません。よって、デフォルト値の auto が指定されています。明示的にファイルをモジュールとして扱うようにするため、moduleDetection を force に設定することをお勧めします。

tsconfig.json
{
  "compilerOptions": {
    "moduleDetection": "force",
  },
}

参考

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

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

スクリプトとモジュールとの違いについては以下の記事が参考になります。

https://www.typescriptlang.org/docs/handbook/modules/theory.html#scripts-and-modules-in-javascript

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

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

https://github.com/hayato94087/next-tsconfig-moduledetection

この記事の内容

この記事では moduleDetection の値を指定し動作を確認します。Node.js & TypeScript のプロジェクトと Next.js のプロジェクトで動作確認を行います。

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

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

事前環境の構築

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

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

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

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

$ mkdir -p tsconfig-moduledetection
$ cd tsconfig-moduledetection
$ pnpm init

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

package.json
{
  "name": "tsconfig-moduledetection",
  "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 を作成します。

tsconfig.json
{
  "compilerOptions": {
    "target": "es2015",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "esModuleInterop":true
  },
  "include": ["**/*.ts","**/*.js"],
  "exclude": ["node_modules", "dist"]
}

git を初期化します。

$ git init

.gitignore を作成します。

$ touch .gitignore
.gitignore
node_modules

コミットします。

$ git add .
$ git commit -m "feat:初期コミット"

moduleDetection が force の場合

moduleDetection が force の場合の動作を確認します。moduleDetection が force の場合、ファイルはモジュールとして扱われます。

moduleDetection に force を設定します。

tsconfig.json
{
  "compilerOptions": {
    "target": "es2015",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "strict": true,
    "skipLibCheck": true,
+   "moduleDetection": "force",
    "forceConsistentCasingInFileNames": true,
    "esModuleInterop":true
  },
  "include": ["**/*.ts","**/*.js"],
  "exclude": ["node_modules", "dist"]
}

コードを作成します。

$ touch arithmetics.ts index.ts bar.ts foo.ts
arithmetics.ts 
export let money = 0; // 外部から参照できるが、変更できない
let message = "hello world"; // 外部から参照できない
export const add = ( value : number) => {
  money += value;
  return money;
}
bar.ts
const name = "bar";
foo.ts
const name = "foo";
index.ts
import { add,money } from "./arithmetics";
 
add(1);
console.log(`money is ${money}`);  // money is 1
 
add(2);
console.log(`money is ${money}`);  // money is 13

// 外部からモジュールの変数を変更できないので以下はエラーとなる。
// money = 10;

ファイルがモジュールとして扱われる場合、以下のような特徴があります。

  • 各モジュールは独自のトップレベルのスコープがあります。
  • モジュール内で定義されたトップレベルの変数はグローバルではなくモジュール内のローカル変数として定義されます。
  • モジュール内で定義された変数を変更できるのはモジュール内のみとなります。外からの変更はできません。

つまり、以下が言えます。

  • arithmetics.ts の money は外部から参照できますが、変更できません。
  • arithmetics.ts の message は外部から参照できません。
  • arithmetics.ts の add 関数を通じて money を変更できます。

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

$ pnpm run dev

money is 1
money is 3

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

$ pnpm run typecheck

コミットします。

$ git add .
$ git commit -m "feat: moduleDetectionをforceを設定"

moduleDetection が legacy の場合

moduleDetection に legacy を設定します。これでファイルはスクリプトとして扱われます。

tsconfig.json を修正します。moduleDetection に legacy を設定します。

tsconfig.json
{
  "compilerOptions": {
    "target": "es2015",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "strict": true,
    "skipLibCheck": true,
-   "moduleDetection": "force",
+   "moduleDetection": "legacy",
    "forceConsistentCasingInFileNames": true,
    "esModuleInterop":true
  },
  "include": ["**/*.ts","**/*.js"],
  "exclude": ["node_modules", "dist"]
}

型チェックします。するとエラーが出ます。

$ pnpm run typecheck

bar.ts:1:7 - error TS2451: Cannot redeclare block-scoped variable 'name'.

1 const name = "bar";
        ~~~~

  node_modules/.pnpm/typescript@5.4.3/node_modules/typescript/lib/lib.dom.d.ts:27434:15
    27434 declare const name: void;
                        ~~~~
    'name' was also declared here.

foo.ts:1:7 - error TS2451: Cannot redeclare block-scoped variable 'name'.

1 const name = "foo";
        ~~~~

  node_modules/.pnpm/typescript@5.4.3/node_modules/typescript/lib/lib.dom.d.ts:27434:15
    27434 declare const name: void;
                        ~~~~
    'name' was also declared here.

Found 2 errors in 2 files.

Errors  Files
     1  bar.ts:1
     1  foo.ts:1

moduleDetection が force の場合、ファイルがモジュールとして扱われていたため、エラーが出ませんでした。が、legacy に変更することで、ファイルをスクリプトとして扱われるようになりました。これにより、foo.ts と bar.ts で定義している name がプロジェクト全体でのスコープとなり、name が重複しているためエラーが出てしまいます。

bar.ts
const name = "bar";
foo.ts
const name = "foo";

コミットします。

$ git add .
$ git commit -m "feat: moduleDetectionをlegacyを設定"

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

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

事前環境の構築

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

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

プロジェクトを作成

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

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

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"]
}

スクリプトを追加

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

package.json
{
  "name": "next-tsconfig-moduledetection",
  "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.38",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "tailwindcss": "^3.3.0",
    "typescript": "^5"
  }
}

動作確認

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

$ pnpm run dev

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

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

moduleDetection が force の場合

moduleDetection が force の場合、ファイルはモジュールとして扱われます。

moduleDetection の値に force を追加します。

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,
+   "moduleDetection": "force",
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

incremental が true の場合、設定変更がうまく反映されないため tsconfig.tsbuildinfo を削除します。

$ rm -rf tsconfig.tsbuildinfo

コードを作成します。

$ mkdir src/lib/
$ touch src/lib/arithmetics.ts src/lib/bar.ts src/lib/foo.ts
arithmetics.ts 
export let money = 0; // 外部から参照できるが、変更できない
let message = "hello world"; // 外部から参照できない
export const add = ( value : number) => {
  money += value;
  return money;
}
bar.ts
const name = "bar";
foo.ts
const name = "foo";
src/app/page.tsx
import { type FC } from "react";
+import { add, money } from "@/lib/arithmetics";

const Home: FC = () => {
+ add(1);
+ console.log(`money is ${money}`); // money is 1

+ add(2);
+ console.log(`money is ${money}`); // money is 13

+ // 外部からモジュールの変数を変更できないので以下はエラーとなる。
+ // money = 10;

  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;

ファイルがモジュールとして扱われる場合、以下のような特徴があります。

  • 各モジュールは独自のトップレベルのスコープがあります。
  • モジュール内で定義されたトップレベルの変数はグローバルではなくモジュール内のローカル変数として定義されます。
  • モジュール内で定義された変数を変更できるのはモジュール内のみとなります。外からの変更はできません。

つまり、以下が言えます。

  • arithmetics.ts の money は外部から参照できますが、変更できません。
  • arithmetics.ts の message は外部から参照できません。
  • arithmetics.ts の add 関数を通じて money を変更できます。

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

$ pnpm run typecheck

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

$ pnpm run dev

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

 ✓ Ready in 2.7s
 ○ Compiling / ...
 ✓ Compiled / in 2.3s (456 modules)
money is 1
money is 3
 ✓ Compiled in 308ms (220 modules)

ビルドします。エラーは出ません。

$ pnpm run build

   ▲ Next.js 14.1.4

   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types    
 ✓ Collecting page data    
   Generating static pages (0/5)  [=   ]money is 1
money is 3
money is 4
money is 6
 ✓ Generating static pages (5/5) 
 ✓ Collecting build traces    
 ✓ Finalizing page optimization    

Route (app)                              Size     First Load JS
┌ ○ /                                    137 B          84.4 kB
└ ○ /_not-found                          885 B          85.2 kB
+ First Load JS shared by all            84.3 kB
  ├ chunks/672-f5652b77b66c42f3.js       29 kB
  ├ chunks/90234aad-523d1b31770fe8fa.js  53.4 kB
  └ other shared chunks (total)          1.86 kB


○  (Static)  prerendered as static content

コミットします。

$ git add .
$ git commit -m "feat: moduleDetectionをforceを設定"

moduleDetection が legacy の場合

moduleDetection に legacy を設定します。これでファイルはスクリプトとして扱われます。

tsconfig.json を修正します。moduleDetection に legacy を設定します。

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,
-   "moduleDetection": "force",
+   "moduleDetection": "legacy",
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

incremental が true の場合、設定変更がうまく反映されないため tsconfig.tsbuildinfo を削除します。

$ rm -rf tsconfig.tsbuildinfo

型チェックします。するとエラーが出ます。

$ pnpm run typecheck

src/lib/bar.ts:1:7 - error TS2451: Cannot redeclare block-scoped variable 'name'.

1 const name = "bar";
        ~~~~

  node_modules/.pnpm/typescript@5.0.2/node_modules/typescript/lib/lib.dom.d.ts:18092:15
    18092 declare const name: void;
                        ~~~~
    'name' was also declared here.

src/lib/foo.ts:1:7 - error TS2451: Cannot redeclare block-scoped variable 'name'.

1 const name = "foo";
        ~~~~

  node_modules/.pnpm/typescript@5.0.2/node_modules/typescript/lib/lib.dom.d.ts:18092:15
    18092 declare const name: void;
                        ~~~~
    'name' was also declared here.

Found 2 errors in 2 files.

Errors  Files
     1  src/lib/bar.ts:1
     1  src/lib/foo.ts:1

moduleDetection が force の場合、ファイルがモジュールとして扱われていたため、エラーが出ませんでした。が、legacy に変更することで、ファイルをスクリプトとして扱われるようになりました。これにより、foo.ts と bar.ts で定義している name がプロジェクト全体でのスコープとなり、name が重複しているためエラーが出てしまいます。

bar.ts
const name = "bar";
foo.ts
const name = "foo";

コミットします。

$ git add .
$ git commit -m "feat: moduleDetectionをlegacyを設定しエラーを確認"

Next.jsの設定考察

create next-app で作成した Next.js プロジェクトで moduleDetection は記載されていません。明示的にファイルをモジュールとして扱うようにするため、moduleDetection を force に設定することをお勧めします。

まとめ

moduleDetection は、ファイルがスクリプトであるかモジュールであるかを TypeScript がどのように判断するかを制御します。Node.js & TypeScript のプロジェクトと Next.js のプロジェクトで動作確認を行いました。

参考

https://www.webdesignleaves.com/pr/jquery/typescript-basic-05.html

Discussion