Package for server runtime agnostic values and types

[pcattori]

Package for server runtime agnostic values and types

Prior Art

• docs(decisions/0003): package for shared server features #3262

Summary

Currently, we tell users to import from their concrete server runtime package rather than from @remix-run/server-runtime:

import { json } from "@remix-run/cloudflare"     ✅
// or
import { json } from "@remix-run/deno"           ✅
// or
import { json } from "@remix-run/node"           ✅

// but not...
import { json } from "@remix-run/server-runtime" ❌

This results in bad DX for Remix users, namely:

• Examples and docs are harder to understand and copy/paste
• App code is less portable
• Hard to detect which imports are portable
• Tools that auto-import may accidentally pull from @remix-run/server-runtime

It also results in bad DX for Remix maintainers that have to maintain consistent re-exports from @remix-run/server-runtime to the concrete server runtime packages.

Context

Right now, @remix-run/server-runtime is doing two things:

1. Providing utilities for authoring Remix runtime packages (e.g. CreateSessionFunction)
2. Providing server runtime-agnostic values and types (e.g. json and LoaderArgs)

API for (1) is not meant to be treated as public nor stable. At some point, we may decide to treat @remix-run/server-runtime as a user-facing package for authors of Remix runtimes outside of the Remix org. But for now, all intended consumers of API for (1) are packages within the remix-run/remix repo.

But API for (2) is meant to be public and stable across all concrete server runtimes. Types and values for (2) are defined in @remix-run/server-runtime and then re-exported by each concrete server runtime. For example, here are the re-exports in the @remix-run/node package.

(I've said "server runtime" a lot, so it might be useful to think of @remix-run/server-runtime as a "Runtime Kit" designed for creating runtime implementations.)

Issues

Issue 1: Examples and docs are harder to understand and copy/paste

In our docs, we try to guide the user towards importing things like json correctly by defaulting to node but adding a comment for cloudflare and deno:

import { json } from "@remix-run/node" // or cloudflare/deno

In most cases, like with json, the thing being imported isn't specific to a particular runtime. But our API demands that the user know what runtime they're using upfront. This can be confusing or at least add unnecessary cognitive overhead.

Additionally, if users copy/paste such an example, they'll have to remember to change the import to match their runtime, assuming they know that. Of course, tools like VS Code can tell the user when the import isn't right, but the user still has to know what to do to correct the issue. This isn't a huge deal, but its incidental complexity that we're adding to the user's experience.

Issue 2: App code is less portable

If I have app code that only imports runtime-agnostic types and values, my app code should be portable to other runtimes.
But because these are imported from a specific server runtime package, all of those imports need to be updated before the app code that is already portable can run in the new runtime.

Issue 3: Hard to detect which imports are portable

Even if I do update all the import declarations from e.g @remix-run/node to @remix-run/cloudflare, I'll know also have to figure out which imports don't exist for cloudflare. For example:

import { json, createFileSessionStorage } from "@remix-run/node"

Since Cloudflare doesn't provide access to a filesystem, this import cannot simply be changed to @remix-run/cloudflare.

To be clear, I'm not suggesting that 100% code portability be a guarantee since there are nuanced cases, but this is adding incidental complexity that is making things even harder.

Issue 4: Auto-importing @remix-run/server-runtime

Tools like VS Code, Typescript, and Eslint have the capacity to auto-import dependencies, which is super convenient!
But since types and values like json are exported from @remix-run/server-runtime and then re-exported by concrete server runtime packages, auto-importing often chooses to import from @remix-run/server-runtime.

// 2. The auto-import can choose server-runtime
import { json } from "@remix-run/server-runtime"

const loader = () => {
  // 1. Writing `json` here can trigger and auto-import
  return json({ hello: "world" })
}

Issue 5: Maintaining remix-run/remix becomes tedious and error-prone

The re-exports from each concrete server runtime are essential as they are part of that packages public API.
But maintaining those re-exports is tedious and error-prone.

I think this is a potential root cause (maybe one of many) for why our internal types are unwieldy.

Proposal

While a good chunk of types and values will be given a better home in @remix-run/router when #4485 lands (e.g. json can probably go there), I think there will still be many types and values in @remix-run/server-runtime causing the same issues.

The proposal is to:

1. Do an audit of types and values being re-exported from @remix-run/server-runtime, discounting any exports that will be moved into @remix-run/router
2. For any remaining types and values that are re-exports, move them to a new package, @remix-run/server (naming TBD)

In essence, @remix-run/server-runtime would be split into two packages:

1. "Runtime Kit" package that provides utilities for authoring Remix runtime packages
2. "Server" package that provides runtime-agnostic

User DX

import { json } from "@remix-run/server" // runtime-agnostic import
import { createFileSessionStorage } from "@remix-run/node" // runtime-specific import

Now it's clear which imports are runtime-agnostic and which are not. Imports that aren't specific to a runtime are automatically portable.

Most imports in our docs and tutorials could then import from @remix-run/serve and/or @remix-run/router. That makes the examples and docs more straightforward, easier to understand, and more copy/paste-able. You can easily write app code that is 100% portable like this.

VS Code (and other tools) now only have one place to import json from and one place to import createFileSessionStorage from, so auto-imports are fixed too!

Remix maintainers DX

No more re-exports to maintain! And a clear interface boundary between stuff for authoring runtimes and stuff that is shared across runtimes.

[kiliman]

I created a script that generates a simple remix.ts file that imports and re-exports the remix packages. This way I can go back to importing everything from a single place.

import { json, useLoaderData, type LoaderArgs } from '~/remix'

This way if I ever need to change backends, I can just change which package to re-export from.

I also added a way to override existing remix exports with my own version. I primarily use this to replace json, useLoaderData, etc. with my remix-typedjson versions.

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

[pcattori]

I think @jacob-ebey was using Node's package.json imports to do something similar. It even let's you simultaneously define mappings for one import to many sources depending on the runtime, which is cool.

I do think that even if we go with something like this that aggregates Remix imports into one place, it'd still be worth it to dedupe our exports internally. Plus using package.json imports or generating remix.ts file does add some complexity or at least more conventions to Remix. I'm not opposed to that, but just think we should definitely address the root cause first i.e. server-runtime housing both an internal API and a public API.