How to fix Global declaration in non-declaration file in TypeScript

// WRONG - In a regular .ts file (src/utils.ts):
declare global {
  interface Window {
    myCustomProperty: string;
  }
}
// Error: Global declaration in non-declaration file

// CORRECT - Create a declaration file (src/global.d.ts):
declare global {
  interface Window {
    myCustomProperty: string;
  }
}

// Also correct - In a declaration file for module augmentations (src/module-augmentations.d.ts):
declare module "some-module" {
  export interface SomeInterface {
    extraField: boolean;
  }
}

// tsconfig.json
{
  "compilerOptions": {
    // ... other options
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.d.ts",  // Include declaration files
    "types/**/*.d.ts" // If you have a types folder
  ],
  "exclude": ["node_modules"]
}

{
  "include": [
    "src/**/*",
    "types/**/*.d.ts"
  ]
}

// WRONG - Regular import in .d.ts file:
import { SomeType } from "./some-module";
// Error: Import declarations in a namespace cannot reference a module

// CORRECT - Type-only import:
import type { SomeType } from "./some-module";

// Also correct - Using import() type syntax:
declare global {
  type MyType = import("./some-module").SomeType;
}

// For third-party modules:
import type { ReactNode } from "react";

declare global {
  type CustomComponentProps = {
    children: ReactNode;
  };
}

// 1. Extending global interfaces (Window, Document, etc.)
// In src/global.d.ts:
declare global {
  interface Window {
    myApp: {
      version: string;
      init(): void;
    };
  }

  interface Document {
    customMethod(): void;
  }
}

// 2. Augmenting Node.js global
// In src/node-global.d.ts:
declare global {
  namespace NodeJS {
    interface Global {
      myGlobalVar: string;
    }

    interface ProcessEnv {
      CUSTOM_ENV_VAR: string;
    }
  }
}

// 3. Module augmentations for third-party libraries
// In src/module-augmentations.d.ts:
declare module "express" {
  interface Request {
    user?: {
      id: string;
      name: string;
    };
  }
}

// 4. Adding types to built-in objects
// In src/builtin-augmentations.d.ts:
interface Array<T> {
  customMethod(): T[];
}

interface String {
  toTitleCase(): string;
}

// BEFORE: src/types.ts (implementation file with only types)
export interface User {
  id: string;
  name: string;
}

export type Status = "active" | "inactive" | "pending";

// Global declaration causing error:
declare module "*.svg" {
  const content: string;
  export default content;
}

// AFTER: src/types.d.ts (declaration file)
export interface User {
  id: string;
  name: string;
}

export type Status = "active" | "inactive" | "pending";

// Global declaration now allowed:
declare module "*.svg" {
  const content: string;
  export default content;
}

# Recommended structure
src/
├── index.ts              # Main entry point
├── global.d.ts           # Global augmentations
├── types/
│   ├── index.d.ts        # Re-export all types
│   ├── user.d.ts         # User-related types
│   ├── api.d.ts          # API types
│   └── module-augmentations.d.ts  # Third-party module types
├── declarations/
│   ├── images.d.ts       # Image module declarations
│   ├── css-modules.d.ts  # CSS module declarations
│   └── env.d.ts          # Environment variable types
└── lib/
    └── types.d.ts        # Library-specific types

# Alternative flat structure
src/
├── types.d.ts            # All type declarations
├── global-augmentations.d.ts
└── module-declarations.d.ts

{
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.d.ts",
    "src/types/**/*.d.ts",
    "src/declarations/**/*.d.ts"
  ]
}