Add explicit typings location to support use in TypeScript ESM modules

[hiebj]

The question and answer here describes the situation in detail and is exactly identical to the current situation in the dom-accessibility-api package.

In short, TypeScript modules which are marked as type: "module" with moduleResolution: "node16" cannot consume this package because while an explicit entrypoint is specified for esm (./dist/index.mjs), there is no corresponding typings file. In this case, TypeScript will look for such a typings file at the location ./dist/index.d.mts by default, and this file does not exist.

The simplest fix for this, which is the entirety of my PR, is to provide a hint to TypeScript that types should always be resolved at ./dist/index.d.ts regardless of whether the importer is esm or cjs. This is a one-line change which will fix the problem; I have tested this in both commonjs and esm consumers by modifying the package.json in the installed version of dom-accessibility-api.

Another, slightly more invasive approach would be to restructure your package.json to follow the structure they recommend in "TypeScript v4.7 Release Notes":

// package.json
{
    "name": "my-package",
    "type": "module",
    "exports": {
        ".": {
            // Entry-point for `import "my-package"` in ESM
            "import": {
                // Where TypeScript will look.
                "types": "./types/esm/index.d.ts",

                // Where Node.js will look.
                "default": "./esm/index.js"
            },
            // Entry-point for `require("my-package") in CJS
            "require": {
                // Where TypeScript will look.
                "types": "./types/commonjs/index.d.cts",

                // Where Node.js will look.
                "default": "./commonjs/index.cjs"
            },
        }
    },

    // Fall-back for older versions of TypeScript
    "types": "./types/index.d.ts",

    // CJS fall-back for older versions of Node.js
    "main": "./commonjs/index.cjs"
}

However I think my minimal change is sufficient and works for both commonjs and esm consumers (tested in TypeScript 5.1.3 but should work for any version which supports exports) and will not affect older consumers which do not recognize exports.

Since your package does not have alternate typings for any export, this is correct in any case and cannot break anyone downstream (as far as I can tell, there are no special cases where certain customers should receive different types who will be broken now).

[changeset-bot]

🦋 Changeset detected

Latest commit: d99169b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
dom-accessibility-api	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[domarmstrong]

👍 I was just about to open this myself

[eps1lon]

How did you test this change? Could you share something that I could use to verify?

[hiebj]

StackBlitz showing the error

Unfortunately, this sort of thing is pretty tough to reproduce and test, because the only true test is to actually publish a package with the change and see that it works.

Locally, what I did to test was to install your package into multiple downstream consumers (commonjs and module) and manually modified the package.json within the install path (./node_modules/dom-accessibility-api/package.json) to include my change. It worked in all cases that I tried. I tried my current version of TypeScript (5.1.3) in both commonjs and module packages with moduleResolution of both node and node16.

Unfortunately, no amount of hackery using StackBlitz or CodeSandbox appears to allow me to make this sort of patch change to your package in-situ. In my own library, I added a script to prepare which patches it for me:

"prepare": "npx json -I -f ./node_modules/dom-accessibility-api/package.json -e \"this.exports.types='./dist/index.d.ts'\"",

That doesn't seem to work on either CodeSandbox or StackBlitz, which I attribute to the fact that they aren't truly running an environment for me with those files. Even CodeSandbox's new Cloud VM mode seems not to do the trick. It's possible you could setup some crazy rube goldberg machine with patch-package to do it but I am pretty skeptical.

The most bulletproof way to do this would be for you to issue a prerelease version (0.6.2-rc.0 or something) with the change and verify that it works. This will not affect consumers and you can test it in as many downstream consumers and environments as you'd like. If you did that, we could even create a CodeSandbox or StackBlitz which would be able to demonstrate the fix as well.

[eps1lon]

Unfortunately, this sort of thing is pretty tough to reproduce and test, because the only true test is to actually publish a package with the change and see that it works.

That's what the ci/codesandbox is for. It creates a package that can be installed e.g. https://pkg.csb.dev/eps1lon/dom-accessibility-api/commit/d5e189d4/dom-accessibility-api (see https://ci.codesandbox.io/status/eps1lon/dom-accessibility-api/pr/978/builds/410011)

[eps1lon]

Thanks!

[eps1lon]

I think this needs to come first: #996