Code Monkey home page Code Monkey logo

example-subpath-exports-ts-compat's Introduction

TypeScript-friendly strategies for package.json subpath exports compatibility

Many npm libraries are eager to use subpath exports, but support is not universal. This repository demonstrates three strategies for libraries that wish to use subpath exports while providing fallbacks for module resolvers that don’t support them. Each is compatible with TypeScript under --moduleResolution node and --moduleResolution node16 (as well as nodenext at the time of writing).

Why care about old module resolvers?

Support for subpath exports is included in Node versions 12 and later. While many library authors are fine with dropping support for Node 11 and earlier, many TypeScript users on more recent versions of Node have not yet updated their moduleResolution setting, and are still type-checking their projects as if it will run on Node 11 or earlier.

Moreover, bundler users who write TypeScript are typically unable to use --moduleResolution node16 due to significant differences between bundler resolution and Node 16 resolution, and an appropriate moduleResolution option for bundlers does not exist yet.

TypeScript is working on these problems, but library authors can ease a lot of compatibility pain by employing one of these strategies in the meantime.

Finally, at least two still-widely-used bundlers, Parcel and Browserify, do not support subpath exports, so any library that relies on them without a fallback strategy will be unusable by users of these bundlers, whether they use TypeScript or not.

How this repository is structured

The examples directory contains two small TypeScript projects, compiled under different moduleResolution settings, that consume three hand-written libraries in examples/node_modules. Each of these three libraries is named for the subpath exports fallback strategy it uses, and has a nested README that discusses the strategy in detail:

Each of the two TypeScript projects successfully type checks with npm run build, demonstrating which types are found for each import. The output can be run in Node with npm start, where a series of assertions prove which implementation files Node finds. These projects also have nested READMEs:

Strategy support matrix

Note that the types-versions-wildcard fallback strategy is only fallback for TypeScript, so it does not help users who are on Node 11 or other runtimes/bundlers that lack exports support. It is included because it is the only method that offers an analog to * wildcards in subpath exports.

extensionless package-json-redirects types-versions-wildcards
TypeScript --moduleResolution node16 ✅ via exports ✅ via exports ✅ via exports
TypeScript --moduleResolution node ✅ via fallback ✅ via fallback ✅ via fallback
Node 12+ ✅ via exports ✅ via exports ✅ via exports
Node 11 ✅ via fallback ✅ via fallback
Most bundlers ✅ via exports ✅ via exports ✅ via exports
Parcel, Browserify ✅ via fallback ✅ via fallback

example-subpath-exports-ts-compat's People

Contributors

andrewbranch avatar djgrant avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

example-subpath-exports-ts-compat's Issues

Import completion in VSCode

After implementing the package-json-redirects strategy in a larger project I found VSCode import suggestions were having suggesting the wrong files. This repository seemed like a great way to test with a small example, but I haven't been able to complete one or two and see suggested imports any of the three packages from the node-11-resolution or node-16-resolution projects.

Do you happen to know what I might be doing wrong, or why these projects don't complete for me?

Clarify separate types for CJS and ESM in package.json redirect strategy

The package-json-redirect README describes separate types for CJS and ESM files also being possible with the package.json redirect strategy.

Note that the separate handling of ESM and CJS, as well as the decision to present a unified set of types for the two, is orthogonal to the subpath exports demonstration. (Including separate types for CJS and ESM files, as extensionless does, is often a better choice, and is compatible with this strategy.)

How is this compatible, with just one types field of the package.json would that be accomplished with two sets of types in a redirected-to directory with .d.mts and .d.ts extensions? And the types field should have no extension?

When I type it out it seems obvious, I guess my confusion was around which file extensions tricks were unique to the "extensionless" approach.

VSCode completion issues inherent to package.json redirect strategy?

I was having trouble getting import suggestions to show up in VSCode for the Node11 package so don't have a repro here (feel free to close), but in another project following the package-json-redirects strategy I found that I still needed to use something like the types-versions-wildcards approach

"typesVersions": {
  "*": {
    "entrypoint1": "./dist/types/entrypoint
    ...
}

to get reasonable import completion in VSCode.

Without this, I was getting import completions to the types files themselves, things like import {something} from "packagename/dist/something".

If there's something to understand it would be useful to add it to the matrix, is there anything obvious about how VSCode might be confused by package-json-redirects? Again I did not repro this in this repo, so this is likely my mistake — but I wasn't able to rule it out because I didn't get import completion working in the Node11 package.

How to publish plain JS+JSDoc library for TypeScript consumers?

Once this question gets answered,

https://stackoverflow.com/questions/77856692/how-to-publish-plain-jsjsdoc-library-for-typescript-consumers

it will be nice to put an example here.

There is also not enough information to figure how to achieve it in these two TS doc pages:

It will be nice to update those too.

Include example with TS 5.0 `--moduleResolution bundler`

Hello,

With the arrival of TS 5.0 option --moduleResolution bundler, could you add an example using this value? I am mainly confused on what to put in package.json field main and equivalent exports since we are not producing .js files?

Regards,
Bruno

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.