From b5ac2ffa25d09ffbb924535abbfbc71c050deba6 Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Mon, 3 Jul 2023 17:07:18 +0200 Subject: [PATCH] Add 'Module resolution' section --- node/npm_specifiers.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/node/npm_specifiers.md b/node/npm_specifiers.md index 798968fb..bb1c0cff 100644 --- a/node/npm_specifiers.md +++ b/node/npm_specifiers.md @@ -48,6 +48,33 @@ package: import express from "npm:express@^4.17"; ``` +### Module resolution + +The official TypeScript compiler `tsc` supports different +[moduleResolution](https://www.typescriptlang.org/tsconfig#moduleResolution) +settings. Deno only supports the modern `node16` resolution. Unfortunately many +NPM packages fail to correctly provide types under node16 module resolution, +which can result in `deno check` reporting type errors, that `tsc` does not +report. + +If a default export from an `npm:` import appears to have a wrong type (with the +right type seemingly being available under the `.default` property), it's most +likely that the packaged types do not support node16. You can verify this by +checking if the error also occurs with `tsc --module node16` and +`"type": "module"` in `package.json` or by consulting the +[Are the types wrong?](https://arethetypeswrong.github.io/) website +(particularly the "node16 from ESM" row). + +If you want to use a package that doesn't support TypeScript's node16 module +resolution, you can: + +1. Open an issue at the issue tracker of the package about the problem. (And + perhaps contribute a fix :) +2. Use a [CDN](./cdns.md), that rebuilds the packages for Deno support, instead + of an `npm:` identifier. +3. Ignore the type errors you get in your code base with `// @ts-expect-error` + or `// @ts-ignore`. + ### Including Node types Node ships with many built-in types like `Buffer` that might be referenced in an