👋🏻 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).