Improve dom types for server side rendering environments

まず、既存の lib.dom 定義と、issue で説明されている compilerOptions.lib の動作を確認します。提案されている dom.ssr オプションを、現在の DOM の型モデルおよび window、localStorage、devicePixelRatio の例と比較します。設計が解決され、既存の設定を壊すことなく、サーバーレンダリングのコードが有用な型エラーを受け取れる状態になれば完了です。

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:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• 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).