Improve dom types for server side rendering environments

[RJWadley]

Suggestion

🔍 Search Terms

DSG, SSG, SSR, Server Side Rendering, NextJS GatsbyJS React, DOM type definitions, environment tsconfig, lib.dom

✅ Viability Checklist

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.

⭐ Suggestion

I envision this as an option for lib:

{
  "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

Catch errors that could cause server side rendering to fail!

Somewhere in your react code, you may write:

// 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

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 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).

[lanwin]

Wouldnt it be a good idea to allow to just use globalThis in this case where globalThis.innerWidth is number|undefined but innerWidth.window.innerWidth is number but innerWidth.window is Window|undefined.

[fabb]

The global navigator object would need to have a special type too because node.js 21 introduced it too with only a subset of available keys: https://github.com/nodejs/node/issues/50269