Standardize deprecations in exports maps within package.json

[dzearing]

What is the problem this feature will solve?

Now that exports maps define entry points into a package as a contract, we need a way to identify which paths will be deprecated. Consumers of packages should see in their IDE that the import paths they're referring to are deprecated via strikethrough. Build tools like TypeScript, eslint, esbuild, and Webpack can also leverage these to warn, or fail resolution depending on strictness.

As it is now, we have packages which had accrued years of consumer deep path imports. When these packages roll out a much more constrained list of explicit exports, consumers will break. Libraries can help consumers by providing common deep export entries for backwards compatibility reasons, but list them as deprecated to ween consumers off unsupported deep imports.

To ease transition from unsupported paths to supported ones, an identifier in the standard exports definition could aid tooling to bubble up deprecation warnings when developers use them.

What is the feature you are proposing to solve the problem?

Update docs to add a formal @deprecated flag to exports values, sibling to conditions:

"exports": {
  ".": "./index.js",
  "./foo": {
    "@deprecated": "Use a package import instead.",
    "import": "./foo.js"
  }
}

The value represents a display message for warnings.

This could then be referenced from VS Code when developers reference the bad /foo import and strike it through, showing the tooltip containing the deprecation message like // @deprecated - message comments do today.

What alternatives have you considered?

Should the value be a display message? Alternatively it could represent a replacement path, which could enable fixers to autocorrect paths. Or simply a Boolean.

Should resolution behaviors change with deprecated entries? I don't think so. I can't really think of any changes to behavior of resolve that should care.

Should the @ prefix imply metadata about the export as a standard? I could imagine something like @description could be used to add comments about what the import does, or @owner to list an owner for the particular source entry.

[aduh95]

I think it's a neat idea, but I'm not sure it belongs to this issue tracker: since that would not change anything to Node.js loader mechanism, there's not much that can be done here.
The Node.js docs do have a Community Conditions Definitions list, but Node.js doesn't want to be some kind of authority that decides what goes or not in such list – actually we'd like to move that list away from our docs (see nodejs/loaders#52).

[dzearing]

I think the VSCode folks would be supportive of adding this support if this were the proposed standard, or even if we could come up with an alternative way to add metadata to entries. E.g. maybe we need "exportsMetadata" or some other top level thing so that the map stays simple. But that seems even worse to me.

@aduh95 if I should move this bug over to the loaders repo, I could do that. I'm not sure where the best place for this discussion is, or how to proceed in getting to some sort of consensus.

[github-actions]

There has been no activity on this feature request for 5 months and it is unlikely to be implemented. It will be closed 6 months after the last non-automated comment.

For more information on how the project manages feature requests, please consult the feature request management document.

[github-actions]

There has been no activity on this feature request and it is being closed. If you feel closing this issue is not the right thing to do, please leave a comment.

For more information on how the project manages feature requests, please consult the feature request management document.