Remove Relative Imports in Favor of Node's imports config in package.json

[kentcdodds]

A few days ago we removed path aliases. We're only kinda bringing that back. Instead, we're utilizing the Node.js standard package.json "imports" config to get the same thing:

import { GeneralErrorBoundary } from '../../../components/error-boundary.tsx'
import { GeneralErrorBoundary } from '#app/components/error-boundary.tsx'

Note
If you're thrown by #app instead of #/app, or # instead of ~, please read the decision doc!

Read the decision document here: https://github.com/epicweb-dev/epic-stack/blob/main/docs/decisions/031-imports.md

The commit is here: 4989782

[GeoffreyBooth]

One interesting requirement for imports is that they must start with the # character to disambiguate from other imports. This is a bit annoying, but it’s something that’s not difficult to get used to. They also must not start with #/. So you have to do #app instead of #/app. This is also a bit odd, but again it’s just a matter of familiarity.

There’s also self-referencing a package by its name, which is a different, even less well-known feature than "imports". Set your package.json "name" field to whatever you want to represent your app root, like ~, and define "exports":

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

Then you can import a foo.js at the top level like import '~/foo.js'.

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 from '~/foo.js'.

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

[kentcdodds]

That's an interesting idea too! Not sure I like the idea of the weird package name though so I think we'll stick with this approach instead. Thanks though!

[GeoffreyBooth]

They’re not mutually exclusive. You could use "imports" to define specific paths like #components/ and also use "name": "~" or "name": "app" or whatever to create a reference to the root. Then within the same app you could have import '~/entry.js' and import '#components/button.js'.

The package.json for an app, as opposed to a library, doesn’t really have a use for the name field; nothing is importing this “package.” I don’t think there’s much reason for it to be something readable; the description field or readme file could be used for that purpose.

[kentcdodds]

Thanks, but I'd prefer to not have more than one way to do the same thing and if we supported ~ then you could do ~/app/components and #components to get the same thing. I'm pretty happy with the current solution :)

[sergiodxa]

Does this work without config everywhere? Like this work on Remix and Vitest? Because for TS path aliases you need a plugin in Vitest, will this work without that too?

[GeoffreyBooth]

I don’t know, you’ll need to test. But it’s a core Node feature like "imports", around since Node 12.16.0, so they should support it if they don’t already.

[kentcdodds]

I know this works with vitest and eslint. Just tested with remix and it failed on an import of an .svg file, so I'm thinking it's close, but not quite.

[mattfysh]

This sounds like a great approach for smaller projects! If you start to see some growth in the size of the repo, I'd recommend using a monorepo, which comes with added benefits such as import control (e.g. UI packages are prevented from importing business logic packages). One thing I like especially is in nx where you can tag your packages (akin to root-level folders in your current setup) and then setup rules e.g. I started noticing telemetry/tracing libraries (like Sentry) creeping into areas where they shouldn't be, so a simple one liner can get things back into shape quickly