docs: replace {runtime} in imports with concrete server runtime (#3072

)

so that our example are actual code and is less confusing to newcomers

fixes #3007

docs/api/conventions.md

@@ -263,7 +263,7 @@ import { useParams } from "@remix-run/react";
 import type {
   LoaderFunction,
   ActionFunction,
-} from "@remix-run/{runtime}";
+} from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader: LoaderFunction = async ({
   params,
@@ -426,7 +426,7 @@ import { useParams } from "@remix-run/react";
 import type {
   LoaderFunction,
   ActionFunction,
-} from "@remix-run/{runtime}";
+} from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader: LoaderFunction = async ({
   params,
@@ -488,7 +488,7 @@ import { renderToString } from "react-dom/server";
 import type {
   EntryContext,
   HandleDataRequestFunction,
-} from "@remix-run/{runtime}";
+} from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { RemixServer } from "@remix-run/react";
 
 export default function handleRequest(
@@ -549,7 +549,7 @@ export default function SomeRouteComponent() {
 Each route can define a "loader" function that will be called on the server before rendering to provide data to the route.
 
 ```js
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader = async () => {
   // The `json` function converts a serializable object into a JSON response
@@ -560,8 +560,8 @@ export const loader = async () => {
 
 ```ts
 // Typescript
-import { json } from "@remix-run/{runtime}";
-import type { LoaderFunction } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
+import type { LoaderFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader: LoaderFunction = async () => {
   return json({ ok: true });
@@ -573,7 +573,7 @@ This function is only ever run on the server. On the initial server render it wi
 Using the database ORM Prisma as an example:
 
 ```tsx lines=[1-2,6-8,11]
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { useLoaderData } from "@remix-run/react";
 
 import { prisma } from "../db";
@@ -684,7 +684,7 @@ export const loader: LoaderFunction = async () => {
 Using the `json` helper simplifies this so you don't have to construct them yourself, but these two examples are effectively the same!
 
 ```tsx
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader: LoaderFunction = async () => {
   const users = await fakeDb.users.findMany();
@@ -695,7 +695,7 @@ export const loader: LoaderFunction = async () => {
 You can see how `json` just does a little of the work to make your loader a lot cleaner. You can also use the `json` helper to add headers or a status code to your response:
 
 ```tsx
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader: LoaderFunction = async ({
   params,
@@ -724,7 +724,7 @@ Along with returning responses, you can also throw Response objects from your lo
 Here is a full example showing how you can create utility functions that throw responses to stop code execution in the loader and move over to an alternative UI.
 
 ```ts filename=app/db.ts
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import type { ThrownResponse } from "@remix-run/react";
 
 export type InvoiceNotFoundResponse = ThrownResponse<
@@ -742,7 +742,7 @@ export function getInvoice(id, user) {
 ```
 
 ```ts filename=app/http.ts
-import { redirect } from "@remix-run/{runtime}";
+import { redirect } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 import { getSession } from "./session";
 
@@ -838,7 +838,7 @@ Actions have the same API as loaders, the only difference is when they are calle
 This enables you to co-locate everything about a data set in a single route module: the data read, the component that renders the data, and the data writes:
 
 ```tsx
-import { json, redirect } from "@remix-run/{runtime}";
+import { json, redirect } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { Form } from "@remix-run/react";
 
 import { fakeGetTodos, fakeCreateTodo } from "~/utils/db";
@@ -971,7 +971,7 @@ Note that you can also add headers in your `entry.server` file for things that s
 ```tsx lines=[16]
 import { renderToString } from "react-dom/server";
 import { RemixServer } from "@remix-run/react";
-import type { EntryContext } from "@remix-run/{runtime}";
+import type { EntryContext } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export default function handleRequest(
   request: Request,
@@ -1000,7 +1000,7 @@ Just keep in mind that doing this will apply to _all_ document requests, but doe
 The meta export will set meta tags for your html document. We highly recommend setting the title and description on every route besides layout routes (their index route will set the meta).
 
 ```tsx
-import type { MetaFunction } from "@remix-run/{runtime}";
+import type { MetaFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const meta: MetaFunction = () => {
   return {
@@ -1030,7 +1030,7 @@ As a last option, you can also pass an object of attribute/value pairs as the va
 Examples:
 
 ```tsx
-import type { MetaFunction } from "@remix-run/{runtime}";
+import type { MetaFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const meta: MetaFunction = () => ({
   // Special cases
@@ -1081,7 +1081,7 @@ export const meta: MetaFunction = ({ data, params }) => {
 The links function defines which `<link>` elements to add to the page when the user visits a route.
 
 ```tsx
-import type { LinksFunction } from "@remix-run/{runtime}";
+import type { LinksFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const links: LinksFunction = () => {
   return [
@@ -1115,7 +1115,7 @@ The `links` export from a route should return an array of `HtmlLinkDescriptor` o
 Examples:
 
 ```tsx
-import type { LinksFunction } from "@remix-run/{runtime}";
+import type { LinksFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 import stylesHref from "../styles/something.css";
 
@@ -1392,7 +1392,7 @@ Any files inside the `app` folder can be imported into your modules. Remix will:
 It's most common for stylesheets, but can used for anything.
 
 ```tsx filename=app/routes/root.tsx
-import type { LinksFunction } from "@remix-run/{runtime}";
+import type { LinksFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 import styles from "./styles/app.css";
 import banner from "./images/banner.jpg";

docs/api/remix.md

@@ -33,7 +33,7 @@ These components are to be used once inside of your root route (`root.tsx`). The
 import type {
   LinksFunction,
   MetaFunction,
-} from "@remix-run/{runtime}";
+} from "@remix-run/node"; // or "@remix-run/cloudflare"
 import {
   Links,
   LiveReload,
@@ -331,7 +331,7 @@ In order to avoid (usually) the client-side routing "scroll flash" on refresh or
 This hook returns the JSON parsed data from your route loader function.
 
 ```tsx lines=[2,9]
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { useLoaderData } from "@remix-run/react";
 
 export async function loader() {
@@ -349,7 +349,7 @@ export default function Invoices() {
 This hook returns the JSON parsed data from your route action. It returns `undefined` if there hasn't been a submission at the current location yet.
 
 ```tsx lines=[2,11,20]
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { useActionData, Form } from "@remix-run/react";
 
 export async function action({ request }) {
@@ -377,7 +377,7 @@ export default function Invoices() {
 The most common use-case for this hook is form validation errors. If the form isn't right, you can simply return the errors and let the user try again (instead of pushing all the errors into sessions and back out of the loader).
 
 ```tsx lines=[22, 31, 39-41, 45-47]
-import { redirect, json } from "@remix-run/{runtime}";
+import { redirect, json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { Form, useActionData } from "@remix-run/react";
 
 export async function action({ request }) {
@@ -522,7 +522,7 @@ Returns the function that may be used to submit a `<form>` (or some raw `FormDat
 This is useful whenever you need to programmatically submit a form. For example, you may wish to save a user preferences form whenever any field changes.
 
 ```tsx filename=app/routes/prefs.tsx lines=[2,14,18]
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { useSubmit, useTransition } from "@remix-run/react";
 
 export async function loader() {
@@ -1433,8 +1433,8 @@ function SomeForm() {
 This is a shortcut for creating `application/json` responses. It assumes you are using `utf-8` encoding.
 
 ```ts lines=[2,6]
-import type { LoaderFunction } from "@remix-run/{runtime}";
-import { json } from "@remix-run/{runtime}";
+import type { LoaderFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const loader: LoaderFunction = async () => {
   // So you can write this:
@@ -1470,8 +1470,8 @@ export const loader: LoaderFunction = async () => {
 This is shortcut for sending 30x responses.
 
 ```ts lines=[2,8]
-import type { ActionFunction } from "@remix-run/{runtime}";
-import { redirect } from "@remix-run/{runtime}";
+import type { ActionFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
+import { redirect } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const action: ActionFunction = async () => {
   const userSession = await getUserSessionOrWhatever();
@@ -1651,7 +1651,7 @@ Most of the time, you'll probably want to proxy the file stream to a file host.
 **Example:**
 
 ```tsx
-import type { UploadHandler } from "@remix-run/{runtime}";
+import type { UploadHandler } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import type {
   UploadApiErrorResponse,
   UploadApiOptions,
@@ -1739,8 +1739,8 @@ Your job is to do whatever you need with the `stream` and return a value that's
 We have the built-in `unstable_createFileUploadHandler` and `unstable_createMemoryUploadHandler` and we also expect more upload handler utilities to be developed in the future. If you have a form that needs to use different upload handlers, you can compose them together with a custom handler, here's a theoretical example:
 
 ```tsx filename=file-upload-handler.server.tsx
-import type { UploadHandler } from "@remix-run/{runtime}";
-import { unstable_createFileUploadHandler } from "@remix-run/{runtime}";
+import type { UploadHandler } from "@remix-run/node"; // or "@remix-run/cloudflare"
+import { unstable_createFileUploadHandler } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { createCloudinaryUploadHandler } from "some-handy-remix-util";
 
 export const standardFileUploadHandler =
@@ -1781,7 +1781,7 @@ Let's say you have a banner on your e-commerce site that prompts users to check
 First, create a cookie:
 
 ```js filename=app/cookies.js
-import { createCookie } from "@remix-run/{runtime}";
+import { createCookie } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 export const userPrefs = createCookie("user-prefs", {
   maxAge: 604_800, // one week
@@ -1793,7 +1793,7 @@ Then, you can `import` the cookie and use it in your `loader` and/or `action`. T
 **Note:** We recommend (for now) that you create all the cookies your app needs in `app/cookies.js` and `import` them into your route modules. This allows the Remix compiler to correctly prune these imports out of the browser build where they are not needed. We hope to eventually remove this caveat.
 
 ```tsx filename=app/routes/index.tsx lines=[4,8-9,15-16,20]
-import { json, redirect } from "@remix-run/{runtime}";
+import { json, redirect } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { useLoaderData } from "@remix-run/react";
 
 import { userPrefs } from "~/cookies";
@@ -1913,7 +1913,7 @@ export async function loader({ request }) {
 Creates a logical container for managing a browser cookie from the server.
 
 ```ts
-import { createCookie } from "@remix-run/{runtime}";
+import { createCookie } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 const cookie = createCookie("cookie-name", {
   // all of these are optional defaults that can be overridden at runtime
@@ -1935,7 +1935,7 @@ To learn more about each attribute, please see the [MDN Set-Cookie docs](https:/
 Returns `true` if an object is a Remix cookie container.
 
 ```ts
-import { isCookie } from "@remix-run/{runtime}";
+import { isCookie } from "@remix-run/node"; // or "@remix-run/cloudflare"
 const cookie = createCookie("user-prefs");
 console.log(isCookie(cookie));
 // true
@@ -2027,7 +2027,7 @@ This is an example of a cookie session storage:
 
 ```js filename=app/sessions.js
 // app/sessions.js
-import { createCookieSessionStorage } from "@remix-run/{runtime}";
+import { createCookieSessionStorage } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 const { getSession, commitSession, destroySession } =
   createCookieSessionStorage({
@@ -2059,7 +2059,7 @@ You'll use methods to get access to sessions in your `loader` and `action` funct
 A login form might look something like this:
 
 ```tsx filename=app/routes/login.js lines=[4,7-9,11,16,20,26-28,39,44,49,54]
-import { json, redirect } from "@remix-run/{runtime}";
+import { json, redirect } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import { useLoaderData } from "@remix-run/react";
 
 import { getSession, commitSession } from "../sessions";
@@ -2186,7 +2186,7 @@ TODO:
 Returns `true` if an object is a Remix session.
 
 ```js
-import { isSession } from "@remix-run/{runtime}";
+import { isSession } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 const sessionData = { foo: "bar" };
 const session = createSession(sessionData, "remix-session");
@@ -2201,7 +2201,7 @@ Remix makes it easy to store sessions in your own database if needed. The `creat
 The following example shows how you could do this using a generic database client:
 
 ```js
-import { createSessionStorage } from "@remix-run/{runtime}";
+import { createSessionStorage } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 function createDatabaseSessionStorage({
   cookie,
@@ -2258,7 +2258,7 @@ The main advantage of cookie session storage is that you don't need any addition
 The downside is that you have to `commitSession` in almost every loader and action. If your loader or action changes the session at all, it must be committed. That means if you `session.flash` in an action, and then `session.get` in another, you must commit it for that flashed message to go away. With other session storage strategies you only have to commit it when it's created (the browser cookie doesn't need to change because it doesn't store the session data, just the key to find it elsewhere).
 
 ```js
-import { createCookieSessionStorage } from "@remix-run/{runtime}";
+import { createCookieSessionStorage } from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 const { getSession, commitSession, destroySession } =
   createCookieSessionStorage({
@@ -2282,7 +2282,7 @@ This storage keeps all the cookie information in your server's memory.
 import {
   createCookie,
   createMemorySessionStorage,
-} from "@remix-run/{runtime}";
+} from "@remix-run/node"; // or "@remix-run/cloudflare"
 
 // In this example the Cookie is created separately.
 const sessionCookie = createCookie("__session", {
@@ -2464,7 +2464,7 @@ Now we can read the message in a loader.
 <docs-info>You must commit the session whenever you read a `flash`. This is different than you might be used to where some type of middleware automatically sets the cookie header for you.</docs-info>
 
 ```jsx
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import {
   Meta,
   Links,
@@ -2551,7 +2551,7 @@ This component is a wrapper around React Router's Outlet with the ability to pas
 Here's a practical example of when you may want to use this feature. Let's say you've got a list of companies that have invoices and you want to display those companies in an accordion. We'll render our outlet in that accordion, but we want the invoice sorting to be controlled by the parent (so changing companies preserves the invoice sorting). This is a perfect use case for `<Outlet context>`.
 
 ```tsx filename=app/routes/companies.tsx lines=[5,28-31,36-44,53-57,68]
-import { json } from "@remix-run/{runtime}";
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import {
   useLoaderData,
   useParams,
@@ -2636,8 +2636,8 @@ This hook returns the context from the `<Outlet />` that rendered you.
 Continuing from the `<Outlet context />` example above, here's what the child route could do to use the sort order.
 
 ```tsx filename=app/routes/companies/$companyId.tsx lines=[5,8,25,27-30]
-import type { LoaderFunction } from "@remix-run/{runtime}";
-import { json } from "@remix-run/{runtime}";
+import type { LoaderFunction } from "@remix-run/node"; // or "@remix-run/cloudflare"
+import { json } from "@remix-run/node"; // or "@remix-run/cloudflare"
 import {
   useLoaderData,
   useOutletContext,