Feature: package.json "imports" field

[huntie]

👋🏻 Good First Issue

• An issue or task that is ideal for new open source contributors.
• Please reach out to the issue creator before claiming an issue to discuss design.

Description

Similar to the "exports" field, the package.json "imports" field is a mapping of private import specifiers (from any modules in that package) to a given target.

Unlike "exports", a target in this case can be either a subpath to a file contained within a package, OR a bare import specifier — therefore we can treat this value as a new import specifier to resolve() relative to the package path.

// package.json
{
  "imports": {
    "#dep": {
      "node": "dep-node-native",
      "default": "./dep-polyfill.js"
    }
  }
} 

• https://nodejs.org/docs/latest-v19.x/api/packages.html#subpath-imports
• https://nodejs.org/api/esm.html#resolver-algorithm-specification

Rough design

This is a significant new feature(!), but is well-described by the spec and relatively isolated. If picking up this task, @huntie and a backup Metro team member will be available to support via DM throughout the time spent on this feature.

Most of the implementation for "imports" should live inside metro-resolver.

• Add a new experimental config option, resolver.unstable_enablePackageImports. Update: Ideally we can skip this, and add as one PR with decent test coverage.
• Update the PackageJson type to accept an optional imports property. This should be of type ExportMap.
• Update the resolver to handle import specifiers beginning with #. This should call new logic in a PackageImportsResolve.js module (that follows the PACKAGE_IMPORTS_RESOLVE function in the Node Resolution Algorithm).
  • The result of this function should return the target import specifier, or a PackageImportNotDefinedError.
  • The calling context in resolve.js should then return the result of resolve(target).

Notes:

• Conditional "imports" should be handleable with the existing config options and reduceExportMap() function.
• Tests should be added for all functionality (package-exports-test.js can be copied as a starting point).

[siddarthkay]

Hello @huntie
I would love to work on adding this feature when you add some more description on the requirement and expectations :)

[huntie]

Hey @siddarthkay! I've added a description now. If you're still happy to take this on, let me know :) (and feel free to DM me on Twitter).

[siddarthkay]

@huntie : thanks for the detailed description, for now its good enough to get me started! for more questions I'll paste comments here!
Could you please assign this issue to me?

[jameslawson]

@huntie From the discussion in the linked pull request, I think this issue is up for grabs? (cc: @kraenhansen ) Or maybe @kraenhansen was interested in picking it up?

Either way, I've had a go at this myself here: #1302 – please feel free to check it out and see if the changes there are on the right path 😄 - I managed to get some basic tests to pass 🎉