🗺️ RFC: Improve how we expose and name types

[chaance]

Summary

This is a proposal to audit, simplify and improve the way we define and expose many of our types.

Example of bugs caused by duplicated types

• After upgrading to Remix 1.12.0: TypeError: Cannot read properties of undefined (reading 'remixRequestHandlerPath') #5428

Motivation

Given the modularity of Remix's design, we expose various types from different packages depending on the context in which they are used. This makes sense at first: LoaderFunction describes a server function, so you get that from your server adapter's package. MetaFunction returns a set of props that are passed into <meta /> components that are rendered by React, so that type is imported from @remix-run/react. A future @remix-run/vue package would need to expose its own MetaFunction type adapted for Vue components.

This becomes a problem for two reasons:

1. It's potentially confusing for users because some types are named the same but have different meanings depending on the package they're imported from. For example, MetaFunction is also described in @remix-run/server-runtime because we still reference the meta object in runtime functions, but only a subset of its properties exist in that package.
2. In practice, many functions and objects in @remix-run/react are extensions of other objects in @remix-run/server-runtime, but because neither package is a dependency of the other, we essentially need to copy/paste types from one package to the other. This is a maintenance burden, makes it difficult to keep the types in sync, and because we use the same names across packages, it's not clear which types users are supposed use (and intellesense often chooses the wrong type).

Proposal

A big hurdle to solving this problem is that there is no common dependency between many Remix packages. This is by design, but in truth there is always and underlying set of functions that make Remix what it is, and that is its router.

Since Remix was built on top of React Router, all of the routing logic exists in @remix-run/react. However with React Router v6.4, we moved its core logic (as well an many Remix features) into a framework-agnostic layer exposed in @remix-run/router. Work is currently ongoing to upgrade Remix to use React Router 6.4, and the router package will be the beating heart of everything else in Remix. It makes perfect sense that it should be a dependency of both the server runtime and framework-specific packages.

With most of the underlying types in the router, each environment-specific package can import and properly extend them. We should also consider renaming those types in the router package to something that is clearly generic and not meant to be used in Remix itself.

I also propose that @remix-run/server-runtime become a dependency of @remix-run/react. Even if only its types are imported, none of Remix really makes much sense without the base runtime.

Once we have shared dependencies, we will need to identify all of the duplicate and ambiguous types, decide on a more consistent naming scheme, and update our exports accordingly.

// @remix-run/router
// prefix types that are designed to be extended with `Router`
export interface RouterLoaderFunction {
  (args: RouterLoaderArgs): Promise<Response> | Response;
}

// @remix-run/server-runtime
// prefix types that are designed to be extended with `Server`
import { RouterLoaderFunction } from "@remix-run/router";
export interface ServerLoaderFunction extends RouterLoaderFunction {
  // ...
}

// @remix-run/react
import { ServerLoaderFunction } from "@remix-run/server-runtime";

// Users would import this one, which is nice because now
// almost all types are imported from the same package
export interface LoaderFunction extends ServerLoaderFunction {
  // ...
}

Drawbacks

With this change we are introducing dependencies that might not otherwise be explicitly necessary if not for TypeScript. IMO this is not an issue in practice because Remix users will always need the router, an adapter built on @remix-run/server-runtime, and a framework adapter to build anything with Remix anyway.

It could be annoying for users who want to experiment with building their own fork of the server-runtime package. That shouldn't really be neccessary as long as their runtime supports proper web APIs (which it definitely should, and I don't know that we intend to work with those that don't).

[jenseng]

Have you considered publishing types-only versions of @remix-run/server-runtime etc.? They wouldn't typically need to be installed directly by end-users, but it could help decouple type dependencies from runtime dependencies. It would make the build toolchain a tad more complex, but would alleviate the drawbacks and facilitate extending Remix IMO.

[chaance]

Oh that's an interesting idea! I don't know that we'll realistically be able to explore it pre-v2, but I dig it. Should probably work with @pcattori on that one.

[pcattori]

I'm hopeful that #4634 might help to untangle our types enough that we don't need anything else, but we can definitely consider the ${name}-types approach as a plan B if there's still more left to untangle.

[chaance]

@pcattori I didn't realize you were writing that so I think we overlapped efforts a bit 😅 Yours looks a bit more in-depth though so happy to move the conversations over there.

[pcattori]

Yea wasn't sure if I should comment on this proposal or make a new one 🤷 . They definitely overlap, but I could imagine that there might be types and values that we need to untangle that aren't related to runtimes (i.e. maybe type and values that are shared across adapters? or renderers once we have more than just React?).

[Download]

Wouldn't it make sense to have a shared library to define the core types of Remix and then have runtime and adapters etc implement / extend those core types?

In general I think you would want to avoid the client code having dependencies on specific adapters etc right? So that the code would be portable?

I am a bit confused that the examples I see of loaders directly import code from@remix-run/node, even though the docs for that say:

Most of the time you will never be importing from this package directly as it's used internally by adapters such as @remix-run/express.

Looking at the examples, I will be importing from that package all the time, as it contains type LoaderFunction and helper function json and other 'core' types and utilities... So I am confused about this. See also @remix-run/node confusion #4650.