In this release, we have decided on what we think is a better way to implement or to import our modules in your Remix projects. What exactly does this mean?
Upcoming changes to module imports
You may have noticed in the package.json
of your Remix projects that you depend on a few different packages under the @remix-run
scope, regardless of where you deploy. But in your code you are importing your modules from the core remix
module. This is a simple interface for developers using our modules, what are all of the other packages doing here?
But why?
Behind the scenes, we are actually doing a bit of ✨ magic ✨; the remix setup
script that runs in the postinstall
book actually copies all of the modules you need from the various Remix packages in your node_modules
into the core remix
package. Before this script runs, the remix
package isn't actually doing anything.
We called this the "magic imports" feature, and we thought it was a pretty great way to simplify the experience for you. This way you don't need to know where specific modules come from. Sounds nice, right?
However, this has caused a number of problems. Various deploy targets use node_modules
differently, and getting things to "just work" has created issues with deploying to those platforms. It also adds a great deal of complexity that otherwise wouldn't exist. In addition, this approach breaks package managers such as pnpm and Yarn PnP.
It also obscures where the modules you're importing actually come from and where they end up in your source code. If you need to debug a confusing error about server code ending up in your client bundle, it's not always obvious if you're are using a module that's intended for the server in the wrong place. So while the developer experience might feel simpler when initially authoring the code, the downside is that debugging issues can become much more difficult and time consuming.
We have decided that this is not the best approach, so we now advise importing from the source packages themselves. While you do need to know a few more package names and what modules they expose, we think the benefit is worth it for everyone. That said, IDEs these days can do most of the heavy lifting with features like auto-imports and code completion.
What do I do next?
First off, this release doesn't break your existing code. Your old imports are still supported. But to prepare for future changes we have introduced a migrate
script which will do most of the refactoring work for you. Based on your deploy target, this script will know how to rewrite all of your imports so you shouldn't have to touch them. It will also update your package JSON to remove dependencies you don't need, and when the script is complete it will outline any required additional work that might be needed. From there, you're off to the races. Your code is more future proof, more resilient, and less ✨ magic ✨ than before.
To execute the script in your project:
- Upgrade the
@remix-run/dev
to v1.4.0 (should be in yourdevDependencies
) - Run
npx @remix-run/dev@latest migrate
from your project root and follow the prompts
What's Changed
✨ Features
@remix-run/dev
: Introduce themigrate
command to replaceremix
imports with specific@remix-run
modules (#2670)
🐛 Bug fixes
- Auto-detect package manager when installing via
create-remix
(#2562) - Fix Remix templates
create-remix
when the conflict with local files with the same name (#2733)
💅 Enhancements
- Improvements to
remix-serve
to prevent crashing on various Node signals (#2528, #1822) - Make
getDependenciesToBundle
more resilient to misconfiguredpackages.json
(#2593)
New Contributors
- @XiNiHa made their first contribution in #2695
- @amorriscode made their first contribution in #2717
- @athongsavath made their first contribution in #2721
- @bolchowka made their first contribution in #2705
- @accidentaldeveloper made their first contribution in #2710
- @jodygeraldo made their first contribution in #2727
- @gmaliar made their first contribution in #1822
- @illright made their first contribution in #2562
Full Changelog: v1.3.5...v1.4.0