The issue at hand

Upon deciding to update your compiler version, it's important to note that major software version updates often introduce API changes which can potentially break existing code.

While the recommended approach to resolving compatibility issues and preventing compiler errors is by adjusting your source code accordingly, you expressed a preference for modifying the compiler configuration instead of making direct modifications to your code.

It's crucial to understand that attempting to override types in the lib.dom.d.ts file through new type declarations is not feasible. TypeScript will generate additional errors even if type-checking is disabled for the new declaration file, leading to incompatible merges of declarations. The only viable solution is to exclude the default DOM library and provide a customized version.

Here are the steps to accomplish this:

Getting Started with TSConfig

Without access to your specific tsconfig.json file, here is a base example assuming that your source code is organized within the src/ directory in your repository:

Note: Enabling "strict": true also activates

"strictNullChecks": true

{
  "compilerOptions": {
    "isolatedModules": true,
    "lib": [
      "esnext",
      "dom",
      "dom.iterable"
    ],
    "module": "esnext",
    "outDir": "dist",
    "strict": true,
    "target": "esnext"
  },
  "include": [
    "./src/**/*"
  ]
}

Creating a Customized lib.dom.d.ts Library

1. Download the lib.dom.d.ts file matching your TypeScript version (4.4.3) from: https://github.com/microsoft/TypeScript/blob/v4.4.3/lib/lib.dom.d.ts

2. Place the downloaded file in your project under src/types/lib.dom.d.ts

3. Remove the triple-slash reference on line 18 by deleting the entire line to continue using other built-in libraries.

4. Update line 17286 from:

   readonly top: WindowProxy | null;
   

   to:

   readonly top: WindowProxy;
   

5. Modify line 18350 from:

   declare var top: WindowProxy | null;
   

   to:

   declare var top: WindowProxy;
   

6. Save the updated file

Adjusting Your TSConfig Settings

After replacing the default DOM library with your modified version, make the following modifications in your compiler settings:

{
  "compilerOptions": {
    // ...
    "lib": [
      "esnext",
      "dom", // Remove this entry
      "dom.iterable"
    ],
    // ...
    // Add the following array property
    "typeRoots": [
      "./node_modules/@types",
      "./src/types"
    ]
  },
  // ...
}

Your updated tsconfig.json should now resemble the following:

{
  "compilerOptions": {
    "isolatedModules": true,
    "lib": [
      "esnext",
      "dom.iterable"
    ],
    "module": "esnext",
    "outDir": "dist",
    "strict": true,
    "target": "esnext",
    "typeRoots": [
      "./node_modules/@types",
      "./src/types"
    ]
  },
  "include": [
    "./src/**/*"
  ]
}

Final Thoughts

By following these instructions, you should be able to compile your program seamlessly without encountering any compiler errors related to window.top or global top. Consider whether this strategy of customization is more sustainable than making direct changes to your source code upon future TypeScript upgrades.

Before I share this solution, I want to emphasize the importance of addressing errors properly rather than taking shortcuts. It is recommended to use null coalescing or not null assertion to fix the issues in your project. For example:

window.top!.scrollTo()
top!.scrollTo()
window.top?.scrollTo()
top?.scrollTo()
// and so on..

Although there are around 1500 errors, you can potentially address a large number of them through regular expression matching for quicker resolution. Here are some alternative approaches:

I must clarify that I have not tried this method in a production environment and it may lead to unforeseen complications; my testing has been minimal.

The basic idea is to duplicate the lib.dom.ts file and manually make the necessary modifications.

1. Create a copy of

   ./node_modules/typescript/lib/lib.dom.d.ts

   within your project directory, such as ./lib.dom.modified-4.4.3.d.ts
2. Edit the copied file to eliminate the null type from window.top and top declarations

   // before
   // readonly top: WindowProxy | null;
   // after
   readonly top: WindowProxy;
   
   ...
   
   // before
   // declare var top: WindowProxy | null;
   // after
   declare var top: WindowProxy;
   

3. Update your tsconfig.json to exclude dom from the libraries and include it in the types section

{
  "compilerOptions": {
    "lib": [
      "ES6"
    ],
    "strictNullChecks": true,
    "module": "commonjs",
    "target": "ES6",
    "types": [
      "./lib.dom.modified-4.4.3"
    ]
  },
  "include": [
    "src/**/*"
  ]
}

You now possess a customized dom library with the top property set as non-nullable

Alternatively, you could generate a patch for lib-dom using git and apply it after installation. Further instructions on how to achieve this can be found in various responses to the query here How to overwrite incorrect TypeScript type definition installed via @types/package

To begin, make sure you have set up a version control system (VCS) if you haven't already done so. Then

• Identify the location of the error in your code
• Determine what needs to be replaced
• Utilize your preferred tools to replace all instances of the original text with the desired text
• If errors persist, repeat the process

After replacing all instances of the issue, it's important to review your changes using the VCS. For Git users, use the command

git diff

Examine all modifications and investigate any suspicious ones to ensure the automatic changes are accurate. If not, take necessary actions to correct the code.

Thoroughly test everything. Consider creating a separate versioning branch dedicated to testing before deploying the changes to production.

Instead of using the ! operator, TypeScript disregards the possibility that the value could be null, which is not the case in your situation

const topUrl = top!.window.location.href;

If your ES-LINT is flagging this, you can disable it in the configuration file like so:

module.exports = {
  ...
  rules: {
    ...
    '@typescript-eslint/no-non-null-assertion': 'off'
  },
  ...
}

When using iframes frequently in my projects to load sub-pages on the same domain, I often access properties of top.

top may be null...

However, this is not a concern thanks to my 'X-Frame-Options' being set to 'sameorigin', preventing my website from loading in a cross-origin iframe.

If you believe that's not possible, then...

function getTop(): NonNullable<typeof top> {
    if (!top) throw new Error('global var top is null');
    return top;
}

...simply replace any instance of top.example with getTop().example to consolidate all potential 'null' issues.

While it may not be the most straightforward solution, it certainly offers the highest level of security.

When posed with your query, you mentioned:

While I could implement the suggested fixes to address the 'Object is possibly 'null' issue, I would rather avoid it due to the sheer size of my project and the minimal benefits it provides.

let topUrl = top?.window.location.href || '';

I understand the laborious nature of this task, but if TypeScript is a requirement, I strongly recommend utilizing this solution. It is crucial when working with TypeScript.

If faced with a similar predicament, one approach I often take is utilizing the search/replace feature in my code editor or IDE. For instance, I rely on Visual Studio Code, which enables me to locate and replace specific text within my project files. This includes support for Regex searching, as well as filtering files to include or exclude. Most code editors and IDEs offer comparable functionalities.