Repository: TypeScript
Issue: Improve dom types for server side rendering environments
Labels: Suggestion,Awaiting More Feedback

# Suggestion

<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms

<!--
  💡 Did you know? TypeScript has over 2,000 open suggestions!
  🔎 Please search thoroughly before logging new feature requests as most common ideas already have a proposal in progress.
  The "Common Feature Requests" section of the FAQ lists many popular requests: https://github.com/Microsoft/TypeScript/wiki/FAQ#common-feature-requests

  Replace the text below:
-->

DSG, SSG, SSR, Server Side Rendering, NextJS GatsbyJS React, DOM type definitions, environment tsconfig, lib.dom

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

<!-- A summary of what you'd like to see added or changed -->

I envision this as an option for `lib`:
```json
{
  "compilerOptions": {
    "lib": ["dom.ssr", "DOM.Iterable"]
  }
}
```
that would load any DOM apis optionally, as if window was typed as `Window | undefined`, which would require developers to include type checks when accessing those apis.

Typescript might also be able to check for "use client" directives to narrow the type of window automatically.

## 📃 Motivating Example

<!--
  If you were announcing this feature in a blog post, what's a short explanation that shows
  a developer why this feature improves the language?
-->

Catch errors that could cause server side rendering to fail!

Somewhere in your react code, you may write:
```ts
// accessing browser apis and constants could cause uncaught runtime errors!
const lastLogin = localStorage.getItem("lastLogin"); // <— 'localStorage' is possibly 'undefined'
const resolution = devicePixelRatio; // <— 'devicePixelRatio' is possibly 'undefined'
const screenWidth = window.innerWidth // <— 'window' is possibly 'undefined'

// correct usage, with type checks
const lastLogin = isBrowser() && localStorage.getItem("lastLogin");
const resolution = typeof devicePixelRatio === "number" ? devicePixelRatio : 1
const screenWidth = typeof window !== "undefined" && window.innerWidth;
```

## 💻 Use Cases

<!--
  What do you want to use this for?
  What shortcomings exist with current approaches?
  What workarounds are you using in the meantime?
-->

As server side rendering is growing in popularity, web application code needs to safely run in both browser and node environments. Accidentally accessing DOM apis without checking them first is a common source of crashes in these types of apps. Debugging these issues is often more time consuming than it should be, and requires reading logs to determine what went wrong.

Currently, the best approach I've found is to use [eslint-plugin-ssr-friendly](https://www.npmjs.com/package/eslint-plugin-ssr-friendly) to catch errors, but this sort of approach only catches surface level errors. (It's entirely based on scope. i.e. you can never use globals in some scopes even with type checks, and you can always use globals in other scopes even if they're dangerous).