highlight.js types don't get loaded with TypeScript's nodenext resolution

[DanielRosenwasser]

Recently, TypeScript has added a new resolution mode for Node ESM files. This mode is enabled when running with --moduleResolution nodenext. Under this mode, ESM files respect rules like the exports field on packages. Any .mts or .mjs file is an ES module, and any .ts and .js file is ESM if a containing package.json contains the field "type": "module".

When trying to consume highlight.js under this mode, it currently doesn't pick up on the types being shipped. I can't seem to find the package.json contents that have been shipped on npm (https://unpkg.com/browse/highlight.js@11.4.0/package.json) but this is because each exports field needs to have its own types field as well; otherwise, TypeScript will prefer to look for a corresponding .d.ts file wherever the require or import fields point to.

I believe that the correct solution is to provide the following fields in your package.json.

    ".": {
      "types": "./types/index.d.ts",
      "require": "./lib/index.js",
      "import": "./es/index.js"
    },
    "./*" {
      "types": "./types/index.d.ts"
    }

[joshgoebel]

. I can't seem to find the package.json contents that have been shipped on npm

Nor will you, they are auto-generated at build time. See build_node.js, line ~104.

---

Someone is welcome to make a PR here, but I feel like it may need some testing, the exports stuff has already proven annoying in several ways and seems as if it may continue to be. :-)

Our main shipping node.js package is still commonsjs, not module... only the es folder has a stub package.json with module to make Node happy to understand the js files there as mjs...

So the first question is which package.json actually needs to be changed? I assume adding the exports to the top-level package.json would be correct, but I'm just guessing.

If it's really a two line patch then adding ./* to the list and modifying dual to take an optional list of params with type that gets merged into the generated exports might get the job done here... ?

[joshgoebel]

Good first issue IF someone is familiar with TypeScript's nodenext resolution and export maps in general.

[weswigham]

Technically, if the shapes are different, every entrypoint should have a separate types entry. So, more like

    ".": {
      "require": {
        "types": "./lib/types/index.d.ts",
        "default": "./lib/index.js"
      },
      "import": {
        "types": "./es/types/index.d.ts",
        "default": "./es/index.js"
      }
    },

@DanielRosenwasser 's proposed entry,

    ".": {
      "types": "./types/index.d.ts",
      "require": "./lib/index.js",
      "import": "./es/index.js"
    },

points TS at the CJS package types for both the cjs and esm entrypoint, which may be enough to muddle through, but is fundamentally inaccurate (the default when importing from esm, will be wrong, as an example).

[joshgoebel]

We do not really desire to have separate ESM/CJS type files... (doubly so when we know CJS is on it's way out in the future anyways)

We only took control of the types file to keep it better up-to-date with the library, but unfortunately that's proved more effort than imagined and it seems there are few people who know the "best practices" of maintaining such a file simply inside a larger JS (not TS) project... if supporting it continues to become more and more effort then I'm inclined to just stop shipping it and turn it back over to DefinitelyTyped. 😕

I'm inclined to do the simplest thing possible to fix this if it gets us 90% of the way there... should just adding types as the original poster suggested accomplish that?

[weswigham]

If you're not generating your types from your js (which ts does support) and you're not actively testing your types (as is done on DT), DT is probably a better place for community members to maintain the types.

[joshgoebel]

testing your types

If they are auto-generated from source, what would you be testing?

If you're not generating your types from your js (which ts does support)

Related #3157. This has been suggested before but I have no idea the full amount of effort to actually do this or maintain it on a long term basis. Haven't had the time to look into it.

DT is probably a better place for community members to maintain the types.

Perhaps, just they weren't really maintained so well before though was kind of the problem IIRC.

[joshgoebel]

which may be enough to muddle through

What would be the potential problems? We improved our CJS/ESM support a while back to make it more robust, ie CJS now exports top-level and exports.default, etc... is that some of what you're talking about?

@DanielRosenwasser Are we certain "./*" is going to work? We have a lot of different paths that we list out by hand now... is just adding types to a SINGLE "./*" entry (and "." entry) truly going to cover everything? I'm not familiar with how exports is aggregated.

We need to figure this out soonish if we care about it being in the 11.5 release.

[joshgoebel]

Ping.

[joshgoebel]

Ping again.