What is a "subpath pattern" in NodeJS

Question

While reading a blog about what's new in Angular 13, I've encountered the following statement:

Node.js versions older than v12.20 are no longer supported, due to Angular packages using the Node.js package exports feature with subpath patterns.

So, I wounder, what does it means "subpath patterns"? The examples will be more than welcome here.

Answer 1

I quote from nodejs.org:

Subpath patterns

Added in: v14.13.0, v12.20.0

For packages with a small number of exports or imports, we recommend explicitly listing each exports subpath entry. But for packages that have large numbers of subpaths, this might cause package.json bloat and maintenance issues.

For these use cases, subpath export patterns can be used instead:

// ./node_modules/es-module-package/package.json
{
  "exports": {
    "./features/*": "./src/features/*.js"
  },
  "imports": {
    "#internal/*": "./src/internal/*.js"
  }
}

* maps expose nested subpaths as it is a string replacement syntax only.

All instances of * on the right hand side will then be replaced with this value, including if it contains any / separators.

import featureX from 'es-module-package/features/x';
// Loads ./node_modules/es-module-package/src/features/x.js

import featureY from 'es-module-package/features/y/y';
// Loads ./node_modules/es-module-package/src/features/y/y.js

import internalZ from '#internal/z';
// Loads ./node_modules/es-module-package/src/internal/z.js

This is a direct static replacement without any special handling for file extensions. In the previous example, pkg/features/x.json would be resolved to ./src/features/x.json.js in the mapping.

The property of exports being statically enumerable is maintained with exports patterns since the individual exports for a package can be determined by treating the right hand side target pattern as a ** glob against the list of files within the package. Because node_modules paths are forbidden in exports targets, this expansion is dependent on only the files of the package itself.

To exclude private subfolders from patterns, null targets can be used:

// ./node_modules/es-module-package/package.json
{
  "exports": {
    "./features/*": "./src/features/*.js",
    "./features/private-internal/*": null
  }
}

import featureInternal from 'es-module-package/features/private-internal/m';
// Throws: ERR_PACKAGE_PATH_NOT_EXPORTED

import featureX from 'es-module-package/features/x';
// Loads ./node_modules/es-module-package/src/features/x.js

---

Update (2023 Aug 15)

response to cmcdragonkai comment, quote from Medium (Maksim Zemskov):

To configure path aliases, you can add a few lines to package.json as described in the documentation. For instance, if you want to allow imports relative to the src directory, add the following imports field to package.json:

{
    "name": "my-awesome-project",
    "imports": {
        "#*": "./src/*"
    }
}

To use the configured alias, imports can be written like this:

import { apiClient } from '#shared/api';
import { ProductView } from '#entities/product/components/ProductView';
import { addProductToCart } from '#features/add-to-cart/actions';