Relax package.json#imports prefix

[bmeck]

What is the problem this feature will solve?

Tools such as rspack, bun, typescript, remix, and turbo are all looking at using tsconfig.json#compilerOptions.paths . This is in part due to constraints on package.json#imports and it lacking the ability to fully alias the entire import space. These also seem to have differing constraints and some are doing something outside the standard TS behavior on purpose.

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

The package.json#imports field seems sufficient from reading some twitter threads involving a few maintainers from remix or rspack except for the prefix # constraint. I propose getting feedback from these tools on removing the constraint if that would be sufficient for their users’ general needs. If it is sufficient we could encourage people to use a single way of doing this allowing tooling to avoid divergence and interop woes.

This would not cover global aliasing which already can be covered with policy redirects but likely is not desirable/sufficient for some subset of users. My hope is that subset is small enough to avoid the issue blocking this entirely.

What alternatives have you considered?

Supporting tsconfig.json in a limited subset to alleviate the user needs.

cc @nodejs/loaders @nodejs/modules

[hardfist]

As a maintainer of Rspack, I find our users(webpack | rspack users) choose tsconfig paths over subpaths imports for the following reasons:

• education: it seems subpaths imports are little known, very few materials talking about this features(not everyone like reading NodeJS docs carefully especially it's a little section of docs)
• typescript support: people perfer tsconfig paths other than config webpack resolve.alias manually because it's the single source of truth about alias, it both affects vscode intelligence and bundle alias behavior
• migration cost: https://github.com/dividab/tsconfig-paths-webpack-plugin is well known and most of users choose custom alias prefix like ~/components and @/components and since subpaths force choose # as alias prefix, it will cause large migration cost especially for large monorepo
• monorepo support: there're some wepack plugins supports nest alias and tsconfig paths itself supports composite mode, so you can use different alias for different package
• multi tools support: both vite、webpack、bun、esbuild supports tsconfig paths( either out of box or by well known plugin)

[bmeck]

@hardfist

I think the main goal of removing the prefix would be to reduce the migration costs here. You could still use whatever prefix you desire such as ~ or @ if we remove the current self imposed constraint of always requiring a # prefix for local aliasing.

An additional desire might be to move a single source of truth since TS and bundlers also support tsconfig in various plugin/etc scenarios but the runtime does not. Making runtime and bundler behave the same is a big maintenance burden quite often. I'm open to alternative that solve this but it seems removing the prefix would solve this use case including monorepos at the cost of a tooling update.

[hardfist]

TBH tsconfig paths is not an ideal way to treat as single source of truth because it's super complex and the parsing work is very high(json comment support, extends support, project reference support), but since it's the only alias configuration typescript recognize, I can't think of a better alternative, maybe @andrewbranch have better suggestions?

[Andarist]

Personally, I very much like that there is an enforced prefix there. It makes it obvious what this import specifier is about and it also clearly defines where I should look for the "manifest" of how this specifier might be resolved.

To address some of the @hardfist's points:

• education: ye, this is a problem. Clearly, most people don't realize that package.json#imports is a thing. Tools can encourage the "standard" convention though (over tsconfig paths) and with time people should gain a herd knowledge about this stuff
• typescript support: package.json#imports are supported by TS just fine. However, you need to enable new moduleResolution modes to opt-into them. This is unfortunate and maybe could somehow be reconsidered. I understand the risk related to enabling package.json#exports support by default (eg. many pkgs are misconfigured when it comes to how they point to types so it would create problems for many, the situation should get better with time). Right now I can't even ship a package with those specifiers used in declaration files because many users won't be able to resolve them when they use moduleResolution: node. Auto-imports don't work for those but there is a PR that aims to fix this: Add auto-import for the package.json imports field microsoft/TypeScript#55015
• single source of truth: I think this is somewhat misguided. While some tools might handle tsconfig paths automatically, many just won't do that. So once you start considering multiple test runners, lower-level bundlers etc you end up re-configuring tsconfig path aliases all over the place. package.json#imports can actually act as that single source of truth because they are part of the standard~ resolution algorithm. In most cases, it should be enough to configure them for all of the tools to just pick them up.
• migration cost: sure, there is that. I think though that in the long run it's worth it. The requirement to use this out of the box is using modern tools. And with older tools, the gap can usually be filled in - if you can source those aliases from tsconfig paths then you can "manually" source them from package.json#imports as well. Other than that the cost is to run a quite simple find+replace over the whole codebase.
• monorepo support: I'd love to hear more about this use case since I'm not sure if I understand what it is about.
• multi tools support: that's the beauty of package.json#imports though... they are already supported by all of them!

[ljharb]

I think the enforced prefix is critically important for clarity.

Aesthetics aren't what's important here, and eventually the long tail of tools that have done things their own way for a decade will catch up to doing what node does, as they've always done, and people will migrate to the built-in approach.

[bmeck]

@ljharb this isn't purely aesthetics, these are being used to alias bare specifiers like package names which is a different capability than what we currently allow.

[andrewbranch]

If I had to guess, I would say that the # prefix is not the reason people use tsconfig paths when they could use package.json imports. People are using tsconfig paths because they predate imports by many years and have a long history of bundlers reading them into their own config. The issue isn’t a single character restriction; it’s that any change is burdensome and hard to justify when something isn’t actively broken. If every new bundler supports tsconfig paths out of the box, nobody is going to migrate to package.json imports for their bundled apps, regardless of whether or not they can do so without changing module specifiers in existing source code.

I think things would be marginally better if modern tools didn’t adopt tsconfig paths, but clearly it’s up to each tool’s maintainers to know their users. From my perspective, it seems like there were good reasons to want to avoid reading paths, and for the work it took to implement, they could have implemented a migration tool instead. But I’m not convinced that changing imports will make a meaningful impact toward convincing users to transition off of paths.

I personally like the # prefix because a human reader knows what’s going on at a glance. (Less importantly, I also like the subtle connection to #private class fields.)

[ljharb]

@bmeck npm already has overrides for that.

[hardfist]

from new tool point of view，migration cost is the key point of new tools adoption，if users can migrate to subpath import without changing code，we can sugget users do that，but if they need to modify tons of code，new tool has to find new way to meet users needs to reduce migration cost other than ask users to change their code to meet standard

[GeoffreyBooth]

Unless I’m misremembering, the #-as-first-character requirement was to disambiguate from bare specifiers and npm scopes (that start with @). Maybe that doesn’t need to be a concern, that we can lift the restriction and it becomes “try "imports" first and if no match found, then try the rest of the current resolution algorithm” but I think it would be helpful to dig up the notes from when "imports" was first designed to understand why these decisions were made.

There’s also self-referencing a package by its name, which is a different, even less well-known feature. You can do something similar to what you’re discussing above, relative to the root of the project. For example, with a package.json like this:

{
  "name": "~",
  "type": "module",
  "exports": {
    "./*": "./*"
  }
}

and a foo.js like export const num = 3, you could then write:

import { num } from '~/foo.js'

And the num here would be 3. This is because the package.json "name" field is ~, and because we’ve defined the "exports" field.

You could also use the "exports" mapping to do stuff like move the root one level down:

{
  "name": "~",
  "type": "module",
  "exports": {
    "./*": "./src/*"
  }
}

Then if you move foo.js to src/foo.js, you would be able to import it via import { num } from '~/foo.js'.

It doesn’t need to be ~, either; any string that’s valid as a package name will work.