🗺️ Use the remix package

[ryanflorence]

Background

When importing from @remix-run/{runtime} (@remix-run/node, etc.), you're often importing the same code regardless of the runtime. This complicates the docs, third party package development, and shared code across an organization deploying Remix multiple places.

When Remix first started we had never seen anybody create adapters for multiple hosting platforms around the Web Fetch Request/Response APIs. We originally designed it so that the @remix-run/{runtime} packages were responsible for polyfilling the environment with the web APIs needed, which led to apps importing server things from @remix-run/{runtime}. We anticipated the types and implementations would all be dependent on the specific polyfill so it seemed reasonable.

Through the course of building Remix, we started moving shared runtime things into the internal dependency @remix-run/server-runtime. By the time we were done, the types did not actually end up being the types for the polyfill due to TS constraints, and the majority of a runtime packages were just re-exporting from @remix-run/server-runtime.

This not only makes upgrading, documenting, and using Remix more complicated than it needs to be, it makes building third-party packages for Remix more complicated too.

Fast forward three years and lots of runtimes now have the fetch API. Polyfilling isn't as needed and may soon not be needed at all. In v2 we took advantage of this and moved the responsibility to polyfill to the app, rather than the @remix-run/{runtime} packages.

In the beginning of Remix, we also wanted to leave the door open for making the rendering library pluggable, hence @remix-run/react.

Fast forward three years again and we've seen nearly every rendering lib implement their own remix-like framework with loaders, actions, adapters, nested routes, etc. We were interested in collaborating as a shared framework, but not interested in competing directly (we wish them well, they've done great work).

We also really like the core ideas behind RSC in React. Making the rendering lib pluggable would prove to be a huge challenge and make Remix with React vs. something else very different. This is no longer a goal of the project.

Considering all of this, we can now move all shared code from both @remix-run/server-runtime and @remix-run/react to remix and simplify the package structure for apps and third party packages.

Proposal

• Move all shared code from @remix-run/server-runtime to remix
• Move all code from @remix-run/react to remix
• Third party packages can stop depending on @remix-run/server-runtime and simply declare remix as a peerDependency.

This means the vast majority of imports in an app will be from "remix" because they work everywhere:

import {
  useLoaderData,
  Form,
  Link,
  NavLink,
  json,
  redirect,
  createCookieSessionStorage,
} from "remix";

Only runtime specific things will be imported from a runtime or adapter package:

import { createKVSessionStorage } from "@remix-run/cloudflare";

In practice, some apps won't even need a runtime package if they don't use anything specific to that runtime.

Strategy

Moving a bunch of code around at once would basically force a code freeze and invalidate every PR we've got. We'll take an iterative approach instead:

• Initially the remix package will simply re-export everything from @remix-run/react and all runtime agnostic APIs from @remix-run/server-runtime (just like runtime packages do today)
• After that PR, we can move things piece by piece into the remix package to not disrupt the codebase too much. At this point the runtime package will re-export it from the "remix" package. We may need a third, temporary and silly internal package to avoid circular dependencies.
• We may also find that we keep both @remix-run/server-runtime and @remix-run/react, for organizational reasons, but they would not be dependencies of a Remix app, but internal dependencies of remix.
• Sometime before the v3 release, we'll add a deprecation warning for apps importing from the wrong place so they can update their code before the exports disappear.

[tylerhcarter]

Absolutely love the introspection here and movement towards simplicity. With many of the recent RFCs, its been refreshing to see the project adapt and move away from old decisions/patterns with the focus on delivering a quality framework.

Big thumbs up from me, and keep them coming!

[JClackett]

Love it!

[kiliman]

I've been using a script that re-exports the Remix API, so this will eliminate the need for that.

https://github.com/kiliman/rmx-cli#-gen-remix

[jrestall]

This is great, we've been importing from react-router-dom so that code can be shared between our React Router and Remix sites. So SPA mode combined with this will make everything nicely consistent.

[brophdawg11]

I think you're probably aware, but just for other who may come along and read this...

This will work most of the time, but not all of the time. Most stuff is directly re-exported from RR through @remix-run/react so it doesn't matter where you import from. But some things need to have Remix specific implementations:

• Remix has it's own Link that wraps the RR Link and adds prefetch support
• Remix's useLoaderData/useActionData/useFetcher are small wrappers adding the TS generics that know how to unwrap a Response

We hope to decrease this divergence more as time goes on, but it's a good thing to be aware of at the moment.

[jrestall]

Thanks for the important callout Matt, am aware and am looking forward to migrate the react-router sites to Remix SPA target to simplify this.

[sergiodxa]

As a package developer, this will be much appreciated, right now I need to import from the server-runtime package and that means things like createCookie doesn't work because they're not exported from there, even if they work the same.

And because the internal nature of the package sometimes there are breaking changes on exported types and functions that I have to work with and become breaking changes for my packages. This will help solve that.

[AlemTuzlak]

I'm in the same boat, this would be AMAZING for package development

[mryechkin]

This makes a lot of sense. Love it!

[franklinjavier]

This will greatly simplify things. Sometimes I'm unsure which package to import for a certain method/type (I didn't know that some things were the same regardless of the package).

[alexanderson1993]

Fast forward three years again and we've seen nearly every rendering lib implement their own remix-like framework with loaders, actions, adapters, nested routes, etc. We were interested in collaborating as a shared framework, but not interested in competing directly (we wish them well, they've done great work).
We also really like the core ideas behind RSC in React. Making the rendering lib pluggable would prove to be a huge challenge and make Remix with React vs. something else very different.

What does this imply about the potential for a Preact adapter, or the "Remix sans-React" framework that Ryan talks about on Twitter sometimes? Are those not even possibilities in the future?

[sergiodxa]

I understand that that will not happen anymore, Remix will be a React framework.

[huw]

I think you could probably also collapse runtime-specific packages into remix by using package.json#exports, no? The WinterCG Runtime Keys proposal has at least been drafted up and I suspect the big ones (workerd, deno) won’t change anytime soon. You’d probably still have to keep @remix-run/express and other server-related ones I guess 🤷

[jpsc]

This is a great initiative, it will make it much easier to find the correct API's and simplify the documentation.
On the polyfill side of the server using Nitro is a suggestion.

Fast forward three years again and we've seen nearly every rendering lib implement their own remix-like framework with loaders, actions, adapters, nested routes, etc. We were interested in collaborating as a shared framework, but not interested in competing directly (we wish them well, they've done great work).

This is true but I don't think anything is as solid, regarding data revalidation + aborting ongoing requests as remix 🥲

[sergiodxa]

This is true but I don't think anything is as solid, regarding data revalidation + aborting ongoing requests as remix

I think the point is that instead of collaborating each UI framework team/author decided to build its own Remix-like framework, so instead of doing extra work to keep Remix UI agnostic they will go full React and benefit as much as possible for that.

That said, I still think compatibility with Preact would be nice since they are similar, but I'm not sure what will happen once RSC and Server Actions are supported by Remix, and with the Vite support it may be possible to introduce Preact support that way.

[real34]

+1 for exploring Preact and still having it as a target.

[MattyBalaam]

Is this RFC being moved forward?

[jrestall]

#9034

[whiskerside]

This is a really great improvement, especially for newbies.

[AlemTuzlak]

I have a question about this, at the moment there are duplicate exports in @remix-run/react and @remix-run/{runtime}, namely stuff like redirect (for loaders AND client loaders), json (same) etc..

How will this be handled, will it be something like redirect/clientRedirect?

[sergiodxa]

The redirect in the /react and /{runtime} is the same function actually, because it's just a wrapper of Response object and that works the same in the browser and server. They all come from React Router I think.

[setvik]

Like it. Assuming this would also help the "remix" weekly downloads more closely reflect adoption? The flat ~20k weekly downloads for "remix" on npm trends isn't as compelling to folks making framework comparisons as the steadily increasing ~300k downloads for the @remix-run/* packages.