How to fix Interface 'X' is not compatible with declaration file in TypeScript

// Example error:
// Interface 'Window' is not compatible with declaration file.
//   Types of property 'myCustomProp' are incompatible.
//     Type 'string' is not assignable to type 'number'.

// Check what the declaration file expects
// For global interfaces, check lib.dom.d.ts or @types packages
// For third-party modules, check node_modules/@types/package-name/index.d.ts

// BEFORE: Type mismatch
declare global {
  interface Window {
    myCustomProp: string;  // Error: expects number
  }
}

// AFTER: Match the expected type
declare global {
  interface Window {
    myCustomProp: number;  // Correct: now matches declaration
  }
}

// If you need to support multiple types, use a union:
declare global {
  interface Window {
    myCustomProp: string | number;  // Union type works if declaration allows it
  }
}

// For optional properties, match optionality:
declare global {
  interface Window {
    optionalProp?: string;  // ? makes it optional
    requiredProp: string;   // No ? means required
  }
}

// BEFORE: Incorrect - trying to redeclare the module
declare module "some-library" {
  interface SomeInterface {
    newProp: string;
  }
}

// AFTER: Correct module augmentation
declare module "some-library" {
  // Extend the existing interface
  interface SomeInterface {
    newProp: string;  // This adds to the existing interface
  }
}

// For adding to exported classes/functions:
declare module "express" {
  interface Request {
    user?: User;  // Add custom property to Express Request
  }
}

// Make sure you're augmenting the right module:
// Check node_modules/some-library/package.json for the main entry point
// Or check @types/some-library/index.d.ts for type definitions

// Readonly properties: Can't make readonly properties writable
declare global {
  interface Document {
    // WRONG: document.location is readonly
    location: string;  // Error: location is readonly in lib.dom.d.ts

    // CORRECT: Keep it as Location object
    location: Location;  // Must match original type
  }
}

// Method signatures: Must be compatible
declare global {
  interface Array<T> {
    // WRONG: Incompatible method signature
    map<U>(callback: (value: T) => U): U[];  // Missing index and array parameters

    // CORRECT: Match the original signature
    map<U>(
      callback: (value: T, index: number, array: T[]) => U,
      thisArg?: any
    ): U[];
  }
}

// For adding new methods (not overriding):
declare global {
  interface Array<T> {
    // This is fine - new method doesn't conflict
    customMethod(): void;
  }
}

// Check method compatibility:
// - Same number of parameters
// - Parameter types must be assignable
// - Return type must be assignable
// - Optional parameters must match

// Test if your extension is compatible
type IsCompatible = YourInterface extends OriginalInterface ? true : false;

// Option 1: Type assertions (use with caution)
declare global {
  interface Window {
    myProp: any;  // Use 'any' as last resort
  }
}

// Then cast when using:
const value = (window as any).myProp as string;

// Option 2: Use intersection types instead of extension
type ExtendedWindow = Window & {
  myCustomProp: string;
};

// Then use ExtendedWindow type instead of augmenting Window globally
function useWindow(win: ExtendedWindow) {
  console.log(win.myCustomProp);
}

// Option 3: Create a wrapper interface
interface MyWindowExtensions {
  myCustomProp: string;
}

// Use both types together
function processWindow(win: Window & MyWindowExtensions) {
  // Access both Window properties and your custom properties
}

// Option 4: Use declaration files with proper merging
// Create a file: src/types/window.d.ts
declare global {
  interface Window {
    myCustomProp: string;
  }
}
export {}; // This makes it a module for proper merging

// Option 5: Check if you're extending the right interface
// Sometimes the error means you should extend a different interface
// or create a new interface instead of extending

// tsconfig.json
{
  "compilerOptions": {
    // Include type definitions
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "types": ["node", "express"], // Explicitly include types

    // Declaration file settings
    "declaration": true,
    "declarationMap": true,

    // Module resolution
    "moduleResolution": "node",
    "esModuleInterop": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts", // Include your .d.ts files
    "types/**/*.d.ts"
  ],
  "exclude": ["node_modules"]
}