Node.js、TypeScript、グローバルスコープ拡張：エラー「Augmentations for the global scope can only be directly nested in external modules or ambient module declarations(2669)」の解決策

Node.js、TypeScript、グローバルスコープにおける「Augmentations for the global scope can only be directly nested in external modules or ambient module declarations(2669)」エラーの解説

このエラーは、TypeScriptでNode.jsのグローバルスコープ拡張を試みた際に発生します。これは、グローバルスコープ拡張は外部モジュールまたはambientモジュール宣言内でのみ直接ネストできるという制限によるものです。

原因

TypeScriptでは、グローバルスコープは特別なモジュールとして扱われます。そのため、他のモジュールと同様に拡張するには、いくつかの規則に従う必要があります。

解決策

このエラーを解決するには、以下の2つの方法があります。

外部モジュールを使用する

グローバルスコープ拡張を外部モジュールとして定義し、それをプロジェクトにインポートします。

例：

// global-augmentations.ts
declare global {
  interface Window {
    myGlobalFunction(): void;
  }
}

// index.ts
import './global-augmentations';

window.myGlobalFunction();

ambientモジュール宣言を使用する

declare global構文を使用して、グローバルスコープ拡張をambientモジュール宣言として直接定義します。

// index.ts
declare global {
  interface Window {
    myGlobalFunction(): void;
  }
}

window.myGlobalFunction();

注意事項

• 外部モジュールを使用する方法の方が、コードの構造化と再利用性の観点から推奨されます。
• ambientモジュール宣言を使用する方法は、簡潔ですが、コードの意図が分かりにくくなる可能性があります。

このエラーメッセージは、TypeScriptのバージョンによって異なる場合があります。詳細については、TypeScriptの公式ドキュメントを参照してください。

外部モジュールを使用する

declare global {
  interface Window {
    myGlobalFunction(): void;
  }
}

index.ts

import './global-augmentations';

window.myGlobalFunction();

ambientモジュール宣言を使用する

declare global {
  interface Window {
    myGlobalFunction(): void;
  }
}

window.myGlobalFunction();

補足

上記以外にも、以下の方法でグローバルスコープ拡張を行うことができます。

• declare var構文を使用する

// declare var
declare var myGlobalVariable: string;

// declare namespace
declare namespace MyGlobalNamespace {
  function myGlobalFunction(): void;
}

グローバルスコープ拡張は、コードの再利用性と保守性を向上させるために有効な手段です。上記のサンプルコードを参考に、状況に応じて適切な方法を選択してください。

グローバルスコープ拡張の他の方法

declare var myGlobalVariable: string;

myGlobalVariable = 'Hello, world!';

declare namespace MyGlobalNamespace {
  function myGlobalFunction(): void;

  export function myOtherGlobalFunction(): void;
}

MyGlobalNamespace.myGlobalFunction();
MyGlobalNamespace.myOtherGlobalFunction();

declare function構文

declare function myGlobalFunction(): void;

myGlobalFunction();

declare class MyGlobalClass {
  constructor(public name: string);

  public sayHello(): void {
    console.log(`Hello, ${this.name}!`);
  }
}

const myGlobalClass = new MyGlobalClass('World');
myGlobalClass.sayHello();

declare module 'my-global-module' {
  export function myGlobalFunction(): void;
}

import * as myGlobalModule from 'my-global-module';

myGlobalModule.myGlobalFunction();

• declare var構文とdeclare namespace構文は、古いバージョンのTypeScriptでのみサポートされています。
• declare function構文、declare class構文、declare module構文は、TypeScript 2.0以降でサポートされています。