Remix Utils

This package contains simple utility functions to use with React Router.

Installation

1npm install remix-utils

Additional optional dependencies may be needed, all optional dependencies are:

• react-router
• @edgefirst-dev/batcher
• @edgefirst-dev/jwt
• @edgefirst-dev/server-timing
• @oslojs/crypto
• @oslojs/encoding
• is-ip
• intl-parse-accept-language
• react
• zod

The utils that require an extra optional dependency mention it in their documentation.

If you want to install them all run:

1npm add @edgefirst-dev/batcher @edgefirst-dev/jwt @edgefirst-dev/server-timing @oslojs/crypto @oslojs/encoding is-ip intl-parse-accept-language zod

React and React Router packages should be already installed in your project.

Upgrade from Remix Utils v6

Check the v6 to v7 upgrade guide.

API Reference

promiseHash

The promiseHash function is not directly related to Remix but it's a useful function when working with loaders and actions.

This function is an object version of Promise.all which lets you pass an object with promises and get an object with the same keys with the resolved values.

1import { promiseHash } from "remix-utils/promise";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return json(
5    await promiseHash({
6      user: getUser(request),
7      posts: getPosts(request),
8    })
9  );
10}

You can use nested promiseHash to get a nested object with resolved values.

1import { promiseHash } from "remix-utils/promise";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return json(
5    await promiseHash({
6      user: getUser(request),
7      posts: promiseHash({
8        list: getPosts(request),
9        comments: promiseHash({
10          list: getComments(request),
11          likes: getLikes(request),
12        }),
13      }),
14    })
15  );
16}

timeout

The timeout function lets you attach a timeout to any promise, if the promise doesn't resolve or reject before the timeout, it will reject with a TimeoutError.

1import { timeout } from "remix-utils/promise";
2
3try {
4  let result = await timeout(fetch("https://example.com"), { ms: 100 });
5} catch (error) {
6  if (error instanceof TimeoutError) {
7    // Handle timeout
8  }
9}

Here the fetch needs to happen in less than 100ms, otherwise it will throw a TimeoutError.

If the promise is cancellable with an AbortSignal you can pass the AbortController to the timeout function.

1import { timeout } from "remix-utils/promise";
2
3try {
4  let controller = new AbortController();
5  let result = await timeout(
6    fetch("https://example.com", { signal: controller.signal }),
7    { ms: 100, controller }
8  );
9} catch (error) {
10  if (error instanceof TimeoutError) {
11    // Handle timeout
12  }
13}

Here after 100ms, timeout will call controller.abort() which will mark the controller.signal as aborted.

cacheAssets

[!NOTE] This can only be run inside entry.client.

This function lets you easily cache inside the browser's Cache Storage every JS file built by Remix.

To use it, open your entry.client file and add this:

1import { cacheAssets } from "remix-utils/cache-assets";
2
3cacheAssets().catch((error) => {
4  // do something with the error, or not
5});

The function receives an optional options object with two options:

• cacheName is the name of the Cache object to use, the default value is assets.
• buildPath is the pathname prefix for all Remix built assets, the default value is /build/ which is the default build path of Remix itself.

It's important that if you changed your build path in remix.config.js you pass the same value to cacheAssets or it will not find your JS files.

The cacheName can be left as is unless you're adding a Service Worker to your app and want to share the cache.

1import { cacheAssets } from "remix-utils/cache-assets";
2
3cacheAssests({ cacheName: "assets", buildPath: "/build/" }).catch((error) => {
4  // do something with the error, or not
5});

ClientOnly

[!NOTE] This depends on react.

The ClientOnly component lets you render the children element only on the client-side, avoiding rendering it the server-side.

You can provide a fallback component to be used on SSR, and while optional, it's highly recommended to provide one to avoid content layout shift issues.

1import { ClientOnly } from "remix-utils/client-only";
2
3export default function Component() {
4  return (
5    <ClientOnly fallback={<SimplerStaticVersion />}>
6      {() => <ComplexComponentNeedingBrowserEnvironment />}
7    </ClientOnly>
8  );
9}

This component is handy when you have some complex component that needs a browser environment to work, like a chart or a map. This way, you can avoid rendering it server-side and instead use a simpler static version like an SVG or even a loading UI.

The rendering flow will be:

• SSR: Always render the fallback.
• CSR First Render: Always render the fallback.
• CSR Update: Update to render the actual component.
• CSR Future Renders: Always render the actual component, don't bother to render the fallback.

This component uses the useHydrated hook internally.

ServerOnly

[!NOTE] This depends on react.

The ServerOnly component is the opposite of the ClientOnly component, it lets you render the children element only on the server-side, avoiding rendering it the client-side.

You can provide a fallback component to be used on CSR, and while optional, it's highly recommended to provide one to avoid content layout shift issues, unless you only render visually hidden elements.

1import { ServerOnly } from "remix-utils/server-only";
2
3export default function Component() {
4  return (
5    <ServerOnly fallback={<ComplexComponentNeedingBrowserEnvironment />}>
6      {() => <SimplerStaticVersion />}
7    </ServerOnly>
8  );
9}

This component is handy to render some content only on the server-side, like a hidden input you can later use to know if JS has loaded.

Consider it like the <noscript> HTML tag but it can work even if JS failed to load but it's enabled on the browser.

The rendering flow will be:

• SSR: Always render the children.
• CSR First Render: Always render the children.
• CSR Update: Update to render the fallback component (if defined).
• CSR Future Renders: Always render the fallback component, don't bother to render the children.

This component uses the useHydrated hook internally.

CORS

The CORS function let you implement CORS headers on your loaders and actions so you can use them as an API for other client-side applications.

There are two main ways to use the cors function.

1. Use it on each loader/action where you want to enable it.
2. Use it globally on entry.server handleRequest and handleDataRequest export.

If you want to use it on every loader/action, you can do it like this:

1import { cors } from "remix-utils/cors";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let data = await getData(request);
5  let response = json<LoaderData>(data);
6  return await cors(request, response);
7}

You could also do the json and cors call in one line.

1import { cors } from "remix-utils/cors";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let data = await getData(request);
5  return await cors(request, json<LoaderData>(data));
6}

And because cors mutates the response, you can also call it and later return.

1import { cors } from "remix-utils/cors";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let data = await getData(request);
5  let response = json<LoaderData>(data);
6  await cors(request, response); // this mutates the Response object
7  return response; // so you can return it here
8}

If you want to setup it globally once, you can do it like this in entry.server

1import { cors } from "remix-utils/cors";
2
3const ABORT_DELAY = 5000;
4
5export default function handleRequest(
6  request: Request,
7  responseStatusCode: number,
8  responseHeaders: Headers,
9  remixContext: EntryContext
10) {
11  let callbackName = isbot(request.headers.get("user-agent"))
12    ? "onAllReady"
13    : "onShellReady";
14
15  return new Promise((resolve, reject) => {
16    let didError = false;
17
18    let { pipe, abort } = renderToPipeableStream(
19      <RemixServer context={remixContext} url={request.url} />,
20      {
21        [callbackName]: () => {
22          let body = new PassThrough();
23
24          responseHeaders.set("Content-Type", "text/html");
25
26          cors(
27            request,
28            new Response(body, {
29              headers: responseHeaders,
30              status: didError ? 500 : responseStatusCode,
31            })
32          ).then((response) => {
33            resolve(response);
34          });
35
36          pipe(body);
37        },
38        onShellError: (err: unknown) => {
39          reject(err);
40        },
41        onError: (error: unknown) => {
42          didError = true;
43
44          console.error(error);
45        },
46      }
47    );
48
49    setTimeout(abort, ABORT_DELAY);
50  });
51}
52
53export let handleDataRequest: HandleDataRequestFunction = async (
54  response,
55  { request }
56) => {
57  return await cors(request, response);
58};

Options

Additionally, the cors function accepts a options object as a third optional argument. These are the options.

• origin: Configures the Access-Control-Allow-Origin CORS header. Possible values are:
  • true: Enable CORS for any origin (same as "*")
  • false: Don't setup CORS
  • string: Set to a specific origin, if set to "*" it will allow any origin
  • RegExp: Set to a RegExp to match against the origin
  • Array<string | RegExp>: Set to an array of origins to match against the string or RegExp
  • Function: Set to a function that will be called with the request origin and should return a boolean indicating if the origin is allowed or not. The default value is true.
• methods: Configures the Access-Control-Allow-Methods CORS header. The default value is ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"].
• allowedHeaders: Configures the Access-Control-Allow-Headers CORS header.
• exposedHeaders: Configures the Access-Control-Expose-Headers CORS header.
• credentials: Configures the Access-Control-Allow-Credentials CORS header.
• maxAge: Configures the Access-Control-Max-Age CORS header.

CSRF

[!NOTE] This depends on react, @oslojs/crypto, @oslojs/encoding, and React Router.

The CSRF related functions let you implement CSRF protection on your application.

This part of Remix Utils needs React and server-side code.

First create a new CSRF instance.

1// app/utils/csrf.server.ts
2import { CSRF } from "remix-utils/csrf/server";
3import { createCookie } from "react-router"; // or cloudflare/deno
4
5export const cookie = createCookie("csrf", {
6  path: "/",
7  httpOnly: true,
8  secure: process.env.NODE_ENV === "production",
9  sameSite: "lax",
10  secrets: ["s3cr3t"],
11});
12
13export const csrf = new CSRF({
14  cookie,
15  // what key in FormData objects will be used for the token, defaults to `csrf`
16  formDataKey: "csrf",
17  // an optional secret used to sign the token, recommended for extra safety
18  secret: "s3cr3t",
19});

Then you can use csrf to generate a new token.

1import { csrf } from "~/utils/csrf.server";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let token = csrf.generate();
5}

You can customize the token size by passing the byte size, the default one is 32 bytes which will give you a string with a length of 43 after encoding.

1let token = csrf.generate(64); // customize token length

You will need to save this token in a cookie and also return it from the loader. For convenience, you can use the CSRF#commitToken helper.

1import { csrf } from "~/utils/csrf.server";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let [token, cookieHeader] = await csrf.commitToken(request);
5  return json({ token }, { headers: { "set-cookie": cookieHeader } });
6}

[!NOTE] You could do this on any route, but I recommend you to do it on the root loader.

Now that you returned the token and set it in a cookie, you can use the AuthenticityTokenProvider component to provide the token to your React components.

1import { AuthenticityTokenProvider } from "remix-utils/csrf/react";
2
3let { csrf } = useLoaderData<LoaderData>();
4return (
5  <AuthenticityTokenProvider token={csrf}>
6    <Outlet />
7  </AuthenticityTokenProvider>
8);

Render it in your root component and wrap the Outlet with it.

When you create a form in some route, you can use the AuthenticityTokenInput component to add the authenticity token to the form.

1import { Form } from "react-router";
2import { AuthenticityTokenInput } from "remix-utils/csrf/react";
3
4export default function Component() {
5  return (
6    <Form method="post">
7      <AuthenticityTokenInput />
8      <input type="text" name="something" />
9    </Form>
10  );
11}

Note that the authenticity token is only really needed for a form that mutates the data somehow. If you have a search form making a GET request, you don't need to add the authenticity token there.

This AuthenticityTokenInput will get the authenticity token from the AuthenticityTokenProvider component and add it to the form as the value of a hidden input with the name csrf. You can customize the field name using the name prop.

1<AuthenticityTokenInput name="customName" />

You should only customize the name if you also changed it on createAuthenticityToken.

If you need to use useFetcher (or useSubmit) instead of Form you can also get the authenticity token with the useAuthenticityToken hook.

1import { useFetcher } from "react-router";
2import { useAuthenticityToken } from "remix-utils/csrf/react";
3
4export function useMarkAsRead() {
5  let fetcher = useFetcher();
6  let csrf = useAuthenticityToken();
7  return function submit(data) {
8    fetcher.submit(
9      { csrf, ...data },
10      { action: "/api/mark-as-read", method: "post" }
11    );
12  };
13}

Finally, you need to validate the authenticity token in the action that received the request.

1import { CSRFError } from "remix-utils/csrf/server";
2import { redirectBack } from "remix-utils/redirect-back";
3import { csrf } from "~/utils/csrf.server";
4
5export async function action({ request }: ActionFunctionArgs) {
6  try {
7    await csrf.validate(request);
8  } catch (error) {
9    if (error instanceof CSRFError) {
10      // handle CSRF errors
11    }
12    // handle other possible errors
13  }
14
15  // here you know the request is valid
16  return redirectBack(request, { fallback: "/fallback" });
17}

If you need to parse the body as FormData yourself (e.g. to support file uploads) you can also call CSRF#validate with the FormData and Headers objects.

1let formData = await parseMultiPartFormData(request);
2try {
3  await csrf.validate(formData, request.headers);
4} catch (error) {
5  // handle errors
6}

[!WARNING] If you call CSRF#validate with the request instance, but you already read its body, it will throw an error.

In case the CSRF validation fails, it will throw a CSRFError which can be used to correctly identify it against other possible errors that may get thrown.

The list of possible error messages are:

• missing_token_in_cookie: The request is missing the CSRF token in the cookie.
• invalid_token_in_cookie: The CSRF token is not valid (is not a string).
• tampered_token_in_cookie: The CSRF token doesn't match the signature.
• missing_token_in_body: The request is missing the CSRF token in the body (FormData).
• mismatched_token: The CSRF token in the cookie and the body don't match.

You can use error.code to check one of the error codes above, and error.message to get a human friendly description.

[!WARNING] Don't send those error messages to the end-user, they are meant to be used for debugging purposes only.

Existing Search Params

1import { ExistingSearchParams } from "remix-utils/existing-search-params";

[!NOTE] This depends on react and react-router

When you submit a GET form, the browser will replace all of the search params in the URL with your form data. This component copies existing search params into hidden inputs so they will not be overwritten.

The exclude prop accepts an array of search params to exclude from the hidden inputs

• add params handled by this form to this list
• add params from other forms you want to clear on submit

For example, imagine a table of data with separate form components for pagination and filtering and searching. Changing the page number should not affect the search or filter params.

1<Form>
2  <ExistingSearchParams exclude={["page"]} />
3  <button type="submit" name="page" value="1">
4    1
5  </button>
6  <button type="submit" name="page" value="2">
7    2
8  </button>
9  <button type="submit" name="page" value="3">
10    3
11  </button>
12</Form>

By excluding the page param, from the search form, the user will return to the first page of search result.

1<Form>
2  <ExistingSearchParams exclude={["q", "page"]} />
3  <input type="search" name="q" />
4  <button type="submit">Search</button>
5</Form>

External Scripts

[!NOTE] This depends on react, and react-router.

If you need to load different external scripts on certain routes, you can use the ExternalScripts component together with the ExternalScriptsFunction and ScriptDescriptor types.

In the route you want to load the script add a handle export with a scripts method, type the handle to be ExternalScriptsHandle. This interface is let's you define scripts as either a function or an array.

If you want to define what scripts to load based on the loader data, you can use scripts as a function:

1import { ExternalScriptsHandle } from "remix-utils/external-scripts";
2
3type LoaderData = SerializeFrom<typeof loader>;
4
5export let handle: ExternalScriptsHandle<LoaderData> = {
6  scripts({ id, data, params, matches, location, parentsData }) {
7    return [
8      {
9        src: "https://unpkg.com/htmx.org@1.9.6",
10        integrity: "sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni",
11        crossOrigin: 'anonymous"
12      }
13    ];
14  },
15};

If the list of scripts to load is static you can define scripts as an array directly.

1import { ExternalScriptsHandle } from "remix-utils/external-scripts";
2
3export let handle: ExternalScriptsHandle = {
4  scripts: [
5    {
6      src: "https://unpkg.com/htmx.org@1.9.6",
7      integrity: "sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni",
8      crossOrigin: 'anonymous",
9      preload: true, // use it to render a <link rel="preload"> for this script
10    }
11  ],
12};

You can also import ExternalScriptsFunction and ScriptDescriptor interfaces yourself to build a custom handle type.

1import {
2  ExternalScriptsFunction,
3  ScriptDescriptor,
4} from "remix-utils/external-scripts";
5
6interface AppHandle<LoaderData = unknown> {
7  scripts?: ExternalScriptsFunction<LoaderData> | ScriptDescriptor[];
8}
9
10export let handle: AppHandle<LoaderData> = {
11  scripts, // define scripts as a function or array here
12};

Or you can extend the ExternalScriptsHandle interface.

1import { ExternalScriptsHandle } from "remix-utils/external-scripts";
2
3interface AppHandle<LoaderData = unknown>
4  extends ExternalScriptsHandle<LoaderData> {
5  // more handle properties here
6}
7
8export let handle: AppHandle<LoaderData> = {
9  scripts, // define scripts as a function or array here
10};

---

Then, in the root route, add the ExternalScripts component somewhere, usually you want to load it either inside <head> or at the bottom of <body>, either before or after the Remix's <Scripts> component.

Where exactly to place <ExternalScripts /> will depend on your app, but a safe place is at the end of <body>.

1import { Links, LiveReload, Meta, Scripts, ScrollRestoration } from "remix";
2import { ExternalScripts } from "remix-utils/external-scripts";
3
4type Props = { children: React.ReactNode; title?: string };
5
6export function Document({ children, title }: Props) {
7  return (
8    <html lang="en">
9      <head>
10        <meta charSet="utf-8" />
11        <meta name="viewport" content="width=device-width,initial-scale=1" />
12        {title ? <title>{title}</title> : null}
13        <Meta />
14        <Links />
15      </head>
16      <body>
17        {children}
18        <ScrollRestoration />
19        <ExternalScripts />
20        <Scripts />
21        <LiveReload />
22      </body>
23    </html>
24  );
25}

Now, any script you defined in the ScriptsFunction will be added to the HTML.

You could use this util together with useShouldHydrate to disable Remix scripts in certain routes but still load scripts for analytics or small features that need JS but don't need the full app JS to be enabled.

1let shouldHydrate = useShouldHydrate();
2
3return (
4  <html lang="en">
5    <head>
6      <meta charSet="utf-8" />
7      <meta name="viewport" content="width=device-width,initial-scale=1" />
8      {title ? <title>{title}</title> : null}
9      <Meta />
10      <Links />
11    </head>
12    <body>
13      {children}
14      <ScrollRestoration />
15      {shouldHydrate ? <Scripts /> : <ExternalScripts />}
16      <LiveReload />
17    </body>
18  </html>
19);

useGlobalNavigationState

[!NOTE] This depends on react, and react-router.

This hook allows you to read the value of transition.state, every fetcher.state in the app, and revalidator.state.

1import { useGlobalNavigationState } from "remix-utils/use-global-navigation-state";
2
3export function GlobalPendingUI() {
4  let states = useGlobalNavigationState();
5
6  if (state.includes("loading")) {
7    // The app is loading.
8  }
9
10  if (state.includes("submitting")) {
11    // The app is submitting.
12  }
13
14  // The app is idle
15}

The return value of useGlobalNavigationState can be "idle", "loading" or "submitting"

[!NOTE] This is used by the hooks below to determine if the app is loading, submitting or both (pending).

useGlobalPendingState

[!NOTE] This depends on react, and react-router.

This hook lets you know if the global navigation, if one of any active fetchers is either loading or submitting, or if the revalidator is running.

1import { useGlobalPendingState } from "remix-utils/use-global-navigation-state";
2
3export function GlobalPendingUI() {
4  let globalState = useGlobalPendingState();
5
6  if (globalState === "idle") return null;
7  return <Spinner />;
8}

The return value of useGlobalPendingState is either "idle" or "pending".

[!NOTE] This hook combines the useGlobalSubmittingState and useGlobalLoadingState hooks to determine if the app is pending.

[!NOTE] The pending state is a combination of the loading and submitting states introduced by this hook.

useGlobalSubmittingState

[!NOTE] This depends on react, and react-router.

This hook lets you know if the global transition or if one of any active fetchers is submitting.

1import { useGlobalSubmittingState } from "remix-utils/use-global-navigation-state";
2
3export function GlobalPendingUI() {
4  let globalState = useGlobalSubmittingState();
5
6  if (globalState === "idle") return null;
7  return <Spinner />;
8}

The return value of useGlobalSubmittingState is either "idle" or "submitting".

useGlobalLoadingState

[!NOTE] This depends on react, and react-router.

This hook lets you know if the global transition, if one of any active fetchers is loading, or if the revalidator is running

1import { useGlobalLoadingState } from "remix-utils/use-global-navigation-state";
2
3export function GlobalPendingUI() {
4  let globalState = useGlobalLoadingState();
5
6  if (globalState === "idle") return null;
7  return <Spinner />;
8}

The return value of useGlobalLoadingState is either "idle" or "loading".

useHydrated

[!NOTE] This depends on react.

This hook lets you detect if your component is already hydrated. This means the JS for the element loaded client-side and React is running.

With useHydrated, you can render different things on the server and client while ensuring the hydration will not have a mismatched HTML.

1import { useHydrated } from "remix-utils/use-hydrated";
2
3export function Component() {
4  let isHydrated = useHydrated();
5
6  if (isHydrated) {
7    return <ClientOnlyComponent />;
8  }
9
10  return <ServerFallback />;
11}

When doing SSR, the value of isHydrated will always be false. The first client-side render isHydrated will still be false, and then it will change to true.

After the first client-side render, future components rendered calling this hook will receive true as the value of isHydrated. This way, your server fallback UI will never be rendered on a route transition.

useLocales

[!NOTE] This depends on react.

This hook lets you get the locales returned by the root loader. It follows a simple convention, your root loader return value should be an object with the key locales.

You can combine it with getClientLocal to get the locales on the root loader and return that. The return value of useLocales is a Locales type which is string | string[] | undefined.

1import { useLocales } from "remix-utils/locales/react";
2import { getClientLocales } from "remix-utils/locales/server";
3
4// in the root loader
5export async function loader({ request }: LoaderFunctionArgs) {
6  let locales = getClientLocales(request);
7  return json({ locales });
8}
9
10// in any route (including root!)
11export default function Component() {
12  let locales = useLocales();
13  let date = new Date();
14  let dateTime = date.toISOString;
15  let formattedDate = date.toLocaleDateString(locales, options);
16  return <time dateTime={dateTime}>{formattedDate}</time>;
17}

The return type of useLocales is ready to be used with the Intl API.

useShouldHydrate

[!NOTE] This depends on react-router and react.

If you are building a Remix application where most routes are static, and you want to avoid loading client-side JS, you can use this hook, plus some conventions, to detect if one or more active routes needs JS and only render the Scripts component in that case.

In your document component, you can call this hook to dynamically render the Scripts component if needed.

1import type { ReactNode } from "react";
2import { Links, LiveReload, Meta, Scripts } from "react-router";
3import { useShouldHydrate } from "remix-utils/use-should-hydrate";
4
5interface DocumentProps {
6  children: ReactNode;
7  title?: string;
8}
9
10export function Document({ children, title }: DocumentProps) {
11  let shouldHydrate = useShouldHydrate();
12  return (
13    <html lang="en">
14      <head>
15        <meta charSet="utf-8" />
16        <link rel="icon" href="/favicon.png" type="image/png" />
17        {title ? <title>{title}</title> : null}
18        <Meta />
19        <Links />
20      </head>
21      <body>
22        {children}
23        {shouldHydrate && <Scripts />}
24        <LiveReload />
25      </body>
26    </html>
27  );
28}

Now, you can export a handle object with the hydrate property as true in any route module.

1export let handle = { hydrate: true };

This will mark the route as requiring JS hydration.

In some cases, a route may need JS based on the data the loader returned. For example, if you have a component to purchase a product, but only authenticated users can see it, you don't need JS until the user is authenticated. In that case, you can make hydrate be a function receiving your loader data.

1export let handle = {
2  hydrate(data: LoaderData) {
3    return data.user.isAuthenticated;
4  },
5};

The useShouldHydrate hook will detect hydrate as a function and call it using the route data.

getClientIPAddress

[!NOTE] This depends on is-ip.

This function receives a Request or Headers objects and will try to get the IP address of the client (the user) who originated the request.

1import { getClientIPAddress } from "remix-utils/get-client-ip-address";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  // using the request
5  let ipAddress = getClientIPAddress(request);
6  // or using the headers
7  let ipAddress = getClientIPAddress(request.headers);
8}

If it can't find he IP address the return value will be null. Remember to check if it was able to find it before using it.

The function uses the following list of headers, in order of preference:

• X-Client-IP
• X-Forwarded-For
• HTTP-X-Forwarded-For
• Fly-Client-IP
• CF-Connecting-IP
• Fastly-Client-Ip
• True-Client-Ip
• X-Real-IP
• X-Cluster-Client-IP
• X-Forwarded
• Forwarded-For
• Forwarded
• DO-Connecting-IP
• oxygen-buyer-ip

When a header is found that contains a valid IP address, it will return without checking the other headers.

[!WARNING] On local development the function is most likely to return null. This is because the browser doesn't send any of the above headers, if you want to simulate those headers you will need to either add it to the request Remix receives in your HTTP server or run a reverse proxy like NGINX that can add them for you.

getClientLocales

[!NOTE] This depends on intl-parse-accept-language.

This function let you get the locales of the client (the user) who originated the request.

1import { getClientLocales } from "remix-utils/locales/server";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  // using the request
5  let locales = getClientLocales(request);
6  // or using the headers
7  let locales = getClientLocales(request.headers);
8}

The return value is a Locales type, which is string | string[] | undefined.

The returned locales can be directly used on the Intl API when formatting dates, numbers, etc.

1import { getClientLocales } from "remix-utils/locales/server";
2export async function loader({ request }: LoaderFunctionArgs) {
3  let locales = getClientLocales(request);
4  let nowDate = new Date();
5  let formatter = new Intl.DateTimeFormat(locales, {
6    year: "numeric",
7    month: "long",
8    day: "numeric",
9  });
10  return json({ now: formatter.format(nowDate) });
11}

The value could also be returned by the loader and used on the UI to ensure the user's locales is used on both server and client formatted dates.

isPrefetch

This function let you identify if a request was created because of a prefetch triggered by using <Link prefetch="intent"> or <Link prefetch="render">.

This will let you implement a short cache only for prefetch requests so you avoid the double data request.

1import { isPrefetch } from "remix-utils/is-prefetch";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let data = await getData(request);
5  let headers = new Headers();
6
7  if (isPrefetch(request)) {
8    headers.set("Cache-Control", "private, max-age=5, smax-age=0");
9  }
10
11  return json(data, { headers });
12}

Responses

Redirect Back

This function is a wrapper of the redirect helper from Remix. Unlike Remix's version, this one receives the whole request object as the first value and an object with the response init and a fallback URL.

The response created with this function will have the Location header pointing to the Referer header from the request, or if not available, the fallback URL provided in the second argument.

1import { redirectBack } from "remix-utils/redirect-back";
2
3export async function action({ request }: ActionFunctionArgs) {
4  throw redirectBack(request, { fallback: "/" });
5}

This helper is most useful when used in a generic action to send the user to the same URL it was before.

Not Modified

Helper function to create a Not Modified (304) response without a body and any header.

1import { notModified } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return notModified();
5}

JavaScript

Helper function to create a JavaScript file response with any header.

This is useful to create JS files based on data inside a Resource Route.

1import { javascript } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return javascript("console.log('Hello World')");
5}

Stylesheet

Helper function to create a CSS file response with any header.

This is useful to create CSS files based on data inside a Resource Route.

1import { stylesheet } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return stylesheet("body { color: red; }");
5}

PDF

Helper function to create a PDF file response with any header.

This is useful to create PDF files based on data inside a Resource Route.

1import { pdf } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return pdf(await generatePDF(request.formData()));
5}

HTML

Helper function to create a HTML file response with any header.

This is useful to create HTML files based on data inside a Resource Route.

1import { html } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return html("<h1>Hello World</h1>");
5}

XML

Helper function to create a XML file response with any header.

This is useful to create XML files based on data inside a Resource Route.

1import { xml } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return xml("<?xml version='1.0'?><catalog></catalog>");
5}

Plain Text

Helper function to create a TXT file response with any header.

This is useful to create TXT files based on data inside a Resource Route.

1import { txt } from "remix-utils/responses";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  return txt(`
5    User-agent: *
6    Allow: /
7  `);
8}

Typed Cookies

[!NOTE] This depends on zod, and React Router.

Cookie objects in Remix allows any type, the typed cookies from Remix Utils lets you use Zod to parse the cookie values and ensure they conform to a schema.

1import { createCookie } from "react-router";
2import { createTypedCookie } from "remix-utils/typed-cookie";
3import { z } from "zod";
4
5let cookie = createCookie("returnTo", cookieOptions);
6// I recommend you to always add `nullable` to your schema, if a cookie didn't
7// come with the request Cookie header Remix will return null, and it can be
8// useful to remove it later when clearing the cookie
9let schema = z.string().url().nullable();
10
11// pass the cookie and the schema
12let typedCookie = createTypedCookie({ cookie, schema });
13
14// this will be a string and also a URL
15let returnTo = await typedCookie.parse(request.headers.get("Cookie"));
16
17// this will not pass the schema validation and throw a ZodError
18await typedCookie.serialize("a random string that's not a URL");
19// this will make TS yell because it's not a string, if you ignore it it will
20// throw a ZodError
21await typedCookie.serialize(123);

You could also use typed cookies with any sessionStorage mechanism from Remix.

1let cookie = createCookie("session", cookieOptions);
2let schema = z.object({ token: z.string() }).nullable();
3
4let sessionStorage = createCookieSessionStorage({
5  cookie: createTypedCookie({ cookie, schema }),
6});
7
8// if this works then the correct data is stored in the session
9let session = sessionStorage.getSession(request.headers.get("Cookie"));
10
11session.unset("token"); // remove a required key from the session
12
13// this will throw a ZodError because the session is missing the required key
14await sessionStorage.commitSession(session);

Now Zod will ensure the data you try to save to the session is valid removing any extra field and throwing if you don't set the correct data in the session.

[!IMPORTANT] The session object is not really typed so doing session.get will not return the correct type, you can do schema.parse(session.data) to get the typed version of the session data.

You can also use async refinements in your schemas because typed cookies uses parseAsync method from Zod.

1let cookie = createCookie("session", cookieOptions);
2
3let schema = z
4  .object({
5    token: z.string().refine(async (token) => {
6      let user = await getUserByToken(token);
7      return user !== null;
8    }, "INVALID_TOKEN"),
9  })
10  .nullable();
11
12let sessionTypedCookie = createTypedCookie({ cookie, schema });
13
14// this will throw if the token stored in the cookie is not valid anymore
15sessionTypedCookie.parse(request.headers.get("Cookie"));

Finally, to be able to delete a cookie, you can add .nullable() to your schema and serialize it with null as value.

1// Set the value as null and expires as current date - 1 second so the browser expires the cookie
2await typedCookie.serialize(null, { expires: new Date(Date.now() - 1) });

If you didn't add .nullable() to your schema, you will need to provide a mock value and set the expires date to the past.

1let cookie = createCookie("returnTo", cookieOptions);
2let schema = z.string().url().nullable();
3
4let typedCookie = createTypedCookie({ cookie, schema });
5
6await typedCookie.serialize("some fake url to pass schema validation", {
7  expires: new Date(Date.now() - 1),
8});

Typed Sessions

[!NOTE] This depends on zod, and React Router.

Session objects in Remix allows any type, the typed sessions from Remix Utils lets you use Zod to parse the session data and ensure they conform to a schema.

1import { createCookieSessionStorage } from "react-router";
2import { createTypedSessionStorage } from "remix-utils/typed-session";
3import { z } from "zod";
4
5let schema = z.object({
6  token: z.string().optional(),
7  count: z.number().default(1),
8});
9
10// you can use a Remix's Cookie container or a Remix Utils' Typed Cookie container
11let sessionStorage = createCookieSessionStorage({ cookie });
12
13// pass the session storage and the schema
14let typedSessionStorage = createTypedSessionStorage({ sessionStorage, schema });

Now you can use typedSessionStorage as a drop-in replacement for your normal sessionStorage.

1let session = typedSessionStorage.getSession(request.headers.get("Cookie"));
2
3session.get("token"); // this will be a string or undefined
4session.get("count"); // this will be a number
5session.get("random"); // this will make TS yell because it's not in the schema
6
7session.has("token"); // this will be a boolean
8session.has("count"); // this will be a boolean
9
10// this will make TS yell because it's not a string, if you ignore it it will
11// throw a ZodError
12session.set("token", 123);

Now Zod will ensure the data you try to save to the session is valid by not allowing you to get, set or unset data.

[!TIP] Remember that you either need to mark fields as optional or set a default value in the schema, otherwise it will be impossible to call getSession to get a new session object.

You can also use async refinements in your schemas because typed sesions uses parseAsync method from Zod.

1let schema = z.object({
2  token: z
3    .string()
4    .optional()
5    .refine(async (token) => {
6      if (!token) return true; // handle optionallity
7      let user = await getUserByToken(token);
8      return user !== null;
9    }, "INVALID_TOKEN"),
10});
11
12let typedSessionStorage = createTypedSessionStorage({ sessionStorage, schema });
13
14// this will throw if the token stored in the session is not valid anymore
15typedSessionStorage.getSession(request.headers.get("Cookie"));

Server-Sent Events

[!NOTE] This depends on react.

Server-Sent Events are a way to send data from the server to the client without the need for the client to request it. This is useful for things like chat applications, live updates, and more.

There are two utils provided to help with the usage inside Remix:

• eventStream
• useEventSource

The eventStream function is used to create a new event stream response needed to send events to the client. This must live in a Resource Route.

1// app/routes/sse.time.ts
2import { eventStream } from "remix-utils/sse/server";
3import { interval } from "remix-utils/timers";
4
5export async function loader({ request }: LoaderFunctionArgs) {
6  return eventStream(request.signal, function setup(send) {
7    async function run() {
8      for await (let _ of interval(1000, { signal: request.signal })) {
9        send({ event: "time", data: new Date().toISOString() });
10      }
11    }
12
13    run();
14  });
15}

Then, inside any component, you can use the useEventSource hook to connect to the event stream.

1// app/components/counter.ts
2import { useEventSource } from "remix-utils/sse/react";
3
4function Counter() {
5  // Here `/sse/time` is the resource route returning an eventStream response
6  let time = useEventSource("/sse/time", { event: "time" });
7
8  if (!time) return null;
9
10  return (
11    <time dateTime={time}>
12      {new Date(time).toLocaleTimeString("en", {
13        minute: "2-digit",
14        second: "2-digit",
15        hour: "2-digit",
16      })}
17    </time>
18  );
19}

The event name in both the event stream and the hook is optional, in which case it will default to message, if defined you must use the same event name in both sides, this also allows you to emit different events from the same event stream.

For Server-Sent Events to work, your server must support HTTP streaming. If you don't get SSE to work check if your deployment platform has support for it.

Because SSE count towards the limit of HTTP connections per domain, the useEventSource hook keeps a global map of connections based on the provided URL and options. As long as they are the same, the hook will open a single SSE connection and share it between instances of the hook.

Once there are no more instances of the hook re-using a connection, it will be closed and removed from the map.

You can use the <EventSourceProvider /> component to control the map.

1let map: EventSourceMap = new Map();
2return (
3  <EventSourceProvider value={map}>
4    <YourAppOrPartOfIt />
5  </EventSourceProvider>
6);

This way, you can overwrite the map with a new one for a specific part of your app. Note that this provider is optional and a default map will be used if you don't provide one.

Rolling Cookies

[!NOTE] This depends on zod, and React Router.

Rolling cookies allows you to prolong the expiration of a cookie by updating the expiration date of every cookie.

The rollingCookie function is prepared to be used in entry.server exported function to update the expiration date of a cookie if no loader set it.

For document request you can use it on the handleRequest function:

1import { rollingCookie } from "remix-utils/rolling-cookie";
2
3import { sessionCookie } from "~/session.server";
4
5export default function handleRequest(
6  request: Request,
7  responseStatusCode: number,
8  responseHeaders: Headers,
9  remixContext: EntryContext
10) {
11  await rollingCookie(sessionCookie, request, responseHeaders);
12
13  return isbot(request.headers.get("user-agent"))
14    ? handleBotRequest(
15        request,
16        responseStatusCode,
17        responseHeaders,
18        remixContext
19      )
20    : handleBrowserRequest(
21        request,
22        responseStatusCode,
23        responseHeaders,
24        remixContext
25      );
26}

And for data request you can do it on the handleDataRequest function:

1import { rollingCookie } from "remix-utils/rolling-cookie";
2
3export let handleDataRequest: HandleDataRequestFunction = async (
4  response: Response,
5  { request }
6) => {
7  let cookieValue = await sessionCookie.parse(
8    responseHeaders.get("set-cookie")
9  );
10  if (!cookieValue) {
11    cookieValue = await sessionCookie.parse(request.headers.get("cookie"));
12    responseHeaders.append(
13      "Set-Cookie",
14      await sessionCookie.serialize(cookieValue)
15    );
16  }
17
18  return response;
19};

[!NOTE] > Read more about rolling cookies in Remix.

Named actions

[!NOTE] This depends on React Router.

It's common to need to handle more than one action in the same route, there are many options here like sending the form to a resource route or using an action reducer, the namedAction function uses some conventions to implement the action reducer pattern.

1import { namedAction } from "remix-utils/named-action";
2
3export async function action({ request }: ActionFunctionArgs) {
4  return namedAction(await request.formData(), {
5    async create() {
6      // do create
7    },
8    async update() {
9      // do update
10    },
11    async delete() {
12      // do delete
13    },
14  });
15}
16
17export default function Component() {
18  return (
19    <>
20      <Form method="post">
21        <input type="hidden" name="intent" value="create" />
22        ...
23      </Form>
24
25      <Form method="post">
26        <input type="hidden" name="intent" value="update" />
27        ...
28      </Form>
29
30      <Form method="post">
31        <input type="hidden" name="intent" value="delete" />
32        ...
33      </Form>
34    </>
35  );
36}

This function can follow this convention:

You can pass a FormData object to the namedAction, then it will try to find a field named intent and use the value as the action name.

If, in any case, the action name is not found, the actionName then the library will try to call an action named default, similar to a switch in JavaScript.

If the default is not defined it will throw a ReferenceError with the message Action "${name}" not found.

If the library couldn't found the name at all, it will throw a ReferenceError with the message Action name not found

Preload Route Assets

[!CAUTION] This can potentialy create big Link header and can cause extremely hard to debug issues. Some provider's load balancers have set certain buffer for parsing outgoing response's headers and thanks to preloadRouteAssets you can easily reach that in a medium sized application. Your load balancer can randomly stop responding or start throwing 502 error. To overcome this either don't use preloadRouteAssets, set bigger buffer for processing response headers if you own the loadbalancer or use the experimentalMinChunkSize option in Vite config (this does not solve the issue permanently, only delays it)

The Link header allows responses to push to the browser assets that are needed for the document, this is useful to improve the performance of the application by sending those assets earlier.

Once Early Hints is supported this will also allows you to send the assets even before the document is ready, but for now you can benefit to send assets to preload before the browser parse the HTML.

You can do this with the functions preloadRouteAssets, preloadLinkedAssets and preloadModuleAssets.

All functions follows the same signature:

1import {
2  preloadRouteAssets,
3  preloadLinkedAssets,
4  preloadModuleAssets,
5} from "remix-utils/preload-route-assets";
6
7// entry.server.tsx
8export default function handleRequest(
9  request: Request,
10  statusCode: number,
11  headers: Headers,
12  context: EntryContext
13) {
14  let markup = renderToString(
15    <RemixServer context={context} url={request.url} />
16  );
17  headers.set("Content-Type", "text/html");
18
19  preloadRouteAssets(context, headers); // add this line
20  // preloadLinkedAssets(context, headers);
21  // preloadModuleAssets(context, headers);
22
23  return new Response("<!DOCTYPE html>" + markup, {
24    status: statusCode,
25    headers: headers,
26  });
27}

The preloadRouteAssets is a combination of both preloadLinkedAssets and preloadModuleAssets so you can use it to preload all assets for a route, if you use this one you don't need the other two

The preloadLinkedAssets function will preload any link with rel: "preload" added with the Remix's LinkFunction, so you can configure assets to preload in your route and send them in the headers automatically. It will additionally preload any linked stylesheet file (with rel: "stylesheet") even if not preloaded so it will load faster.

The preloadModuleAssets function will preload all the JS files Remix adds to the page when hydrating it, Remix already renders a <link rel="modulepreload"> for each now before the <script type="module"> used to start the application, this will use Link headers to preload those assets.

Safe Redirects

When performing a redirect, if the URL is user provided we can't trust it, if you do you're opening a vulnerability to phishing scam by allowing bad actors to redirect the user to malicious websites.

https://remix.utills/?redirectTo=https://malicious.app

To help you prevent this Remix Utils gives you a safeRedirect function which can be used to check if the URL is "safe".

[!NOTE] In this context, safe means the URL starts with / but not //, this means the URL is a pathname inside the same app and not an external link.

1import { safeRedirect } from "remix-utils/safe-redirect";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let { searchParams } = new URL(request.url);
5  let redirectTo = searchParams.get("redirectTo");
6  return redirect(safeRedirect(redirectTo, "/home"));
7}

The second argumento of safeRedirect is the default redirect which by when not configured is /, this lets you tell safeRedirect where to redirect the user if the value is not safe.

JSON Hash Response

When returning a json from a loader function, you may need to get data from different DB queries or API requests, typically you would something like this

1export async function loader({ params }: LoaderData) {
2  let postId = z.string().parse(params.postId);
3  let [post, comments] = await Promise.all([getPost(), getComments()]);
4  return json({ post, comments });
5
6  async function getPost() {
7    /* … */
8  }
9  async function getComments() {
10    /* … */
11  }
12}

The jsonHash function lets you define those functions directly in the json, reducing the need to create extra functions and variables.

1import { jsonHash } from "remix-utils/json-hash";
2
3export async function loader({ params }: LoaderData) {
4  let postId = z.string().parse(params.postId);
5  return jsonHash({
6    async post() {
7      // Implement me
8    },
9    async comments() {
10      // Implement me
11    },
12  });
13}

It also calls your functions using Promise.all so you can be sure the data is retrieved in parallel.

Additionally, you can pass non-async functions, values and promises.

1import { jsonHash } from "remix-utils/json-hash";
2
3export async function loader({ params }: LoaderData) {
4  let postId = z.string().parse(params.postId);
5  return jsonHash({
6    postId, // value
7    comments: getComments(), // Promise
8    slug() {
9      // Non-async function
10      return postId.split("-").at(1); // get slug from postId param
11    },
12    async post() {
13      // Async function
14      return await getPost(postId);
15    },
16  });
17
18  async function getComments() {
19    /* … */
20  }
21}

The result of jsonHash is a TypedResponse and it's correctly typed so using it with typeof loader works flawlessly.

1export default function Component() {
2  // all correctly typed
3  let { postId, comments, slug, post } = useLoaderData<typeof loader>();
4
5  // more code…
6}

Delegate Anchors to Remix

When using Remix, you can use the <Link> component to navigate between pages. However, if you have a <a href> that links to a page in your app, it will cause a full page refresh. This can be what you want, but sometimes you want to use client-side navigation here instead.

The useDelegatedAnchors hook lets you add client-side navigation to anchor tags in a portion of your app. This can be specially useful when working with dynamic content like HTML or Markdown from a CMS.

1import { useDelegatedAnchors } from "remix-utils/use-delegated-anchors";
2
3export async function loader() {
4  let content = await fetchContentFromCMS();
5  return json({ content });
6}
7
8export default function Component() {
9  let { content } = useLoaderData<typeof loader>();
10
11  let ref = useRef<HTMLDivElement>(null);
12  useDelegatedAnchors(ref);
13
14  return <article ref={ref} dangerouslySetInnerHTML={{ __html: content }} />;
15}

Prefetch Anchors

If additionally you want to be able to prefetch your anchors you can use the PrefetchPageAnchors components.

This components wraps your content with anchors inside, it detects any hovered anchor to prefetch it, and it delegates them to Remix.

1import { PrefetchPageAnchors } from "remix-utils/use-delegated-anchors";
2
3export async function loader() {
4  let content = await fetchContentFromCMS();
5  return json({ content });
6}
7
8export default function Component() {
9  let { content } = useLoaderData<typeof loader>();
10
11  return (
12    <PrefetchPageAnchors>
13      <article ref={ref} dangerouslySetInnerHTML={{ __html: content }} />
14    </PrefetchPageAnchors>
15  );
16}

Now you can see in your DevTools that when the user hovers an anchor it will prefetch it, and when the user clicks it will do a client-side navigation.

Debounced Fetcher and Submit

[!NOTE] This depends on react, and react-router.

[!WARN] These hooks are marked as deprecated, instead of debouncing at the component-level, do it at the route-level. See https://sergiodxa.com/tutorials/debounce-loaders-and-actions-in-react-router.

useDebounceFetcher and useDebounceSubmit are wrappers of useFetcher and useSubmit that add debounce support.

These hooks are based on @JacobParis' article.

1import { useDebounceFetcher } from "remix-utils/use-debounce-fetcher";
2
3export function Component({ data }) {
4  let fetcher = useDebounceFetcher<Type>();
5
6  function handleClick() {
7    fetcher.submit(data, { debounceTimeout: 1000 });
8  }
9
10  return (
11    <button type="button" onClick={handleClick}>
12      Do Something
13    </button>
14  );
15}

Usage with useDebounceSubmit is similar.

1import { useDebounceSubmit } from "remix-utils/use-debounce-submit";
2
3export function Component({ name }) {
4  let submit = useDebounceSubmit();
5
6  return (
7    <input
8      name={name}
9      type="text"
10      onChange={(event) => {
11        submit(event.target.form, {
12          navigate: false, // use a fetcher instead of a page navigation
13          fetcherKey: name, // cancel any previous fetcher with the same key
14          debounceTimeout: 1000,
15        });
16      }}
17      onBlur={() => {
18        submit(event.target.form, {
19          navigate: false,
20          fetcherKey: name,
21          debounceTimeout: 0, // submit immediately, canceling any pending fetcher
22        });
23      }}
24    />
25  );
26}

Derive Fetcher Type

[!NOTE] This depends on @remix-route/react.

Derive the value of the deprecated fetcher.type from the fetcher and navigation data.

1import { getFetcherType } from "remix-utils/fetcher-type";
2
3function Component() {
4  let fetcher = useFetcher();
5  let navigation = useNavigation();
6  let fetcherType = getFetcherType(fetcher, navigation);
7  useEffect(() => {
8    if (fetcherType === "done") {
9      // do something once the fetcher is done submitting the data
10    }
11  }, [fetcherType]);
12}

You can also use the React Hook API which let's you avoid calling useNavigation.

1import { useFetcherType } from "remix-utils/fetcher-type";
2
3function Component() {
4  let fetcher = useFetcher();
5  let fetcherType = useFetcherType(fetcher);
6  useEffect(() => {
7    if (fetcherType === "done") {
8      // do something once the fetcher is done submitting the data
9    }
10  }, [fetcherType]);
11}

If you need to pass the fetcher type around, you can also import FetcherType type.

1import { type FetcherType } from "remix-utils/fetcher-type";
2
3function useCallbackOnDone(type: FetcherType, cb) {
4  useEffect(() => {
5    if (type === "done") cb();
6  }, [type, cb]);
7}

respondTo for Content Negotiation

If you're building a resource route and wants to send a different response based on what content type the client requested (e.g. send the same data as PDF or XML or JSON), you will need to implement content negotiation, this can be done with the respondTo header.

1import { respondTo } from "remix-utils/respond-to";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  // do any work independent of the response type before respondTo
5  let data = await getData(request);
6
7  let headers = new Headers({ vary: "accept" });
8
9  // Here we will decide how to respond to different content types
10  return respondTo(request, {
11    // The handler can be a subtype handler, in `text/html` html is the subtype
12    html() {
13      // We can call any function only really need to respond to this
14      // content-type
15      let body = ReactDOMServer.renderToString(<UI {...data} />);
16      headers.append("content-type", "text/html");
17      return new Response(body, { headers });
18    },
19    // It can also be a highly specific type
20    async "application/rss+xml"() {
21      // we can do more async work inside this code if needed
22      let body = await generateRSSFeed(data);
23      headers.append("content-type", "application/rss+xml");
24      return new Response(body, { headers });
25    },
26    // Or a generic type
27    async text() {
28      // To respond to any text type, e.g. text/plain, text/csv, etc.
29      let body = generatePlain(data);
30      headers.append("content-type", "text/plain");
31      return new Response(body, { headers });
32    },
33    // The default will be used if the accept header doesn't match any of the
34    // other handlers
35    default() {
36      // Here we could have a default type of response, e.g. use json by
37      // default, or we can return a 406 which means the server can't respond
38      // with any of the requested content types
39      return new Response("Not Acceptable", { status: 406 });
40    },
41  });
42}

Now, the respondTo function will check the Accept header and call the correct handler, to know which one to call it will use the parseAcceptHeader function also exported from Remix Utils

1import { parseAcceptHeader } from "remix-utils/parse-accept-header";
2
3let parsed = parseAcceptHeader(
4  "text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, image/*, */*;q=0.8"
5);

The result is an array with the type, subtype and extra params (e.g. the q value). The order will be the same encountered in the header, in the example aabove text/html will be the first, followed by application/xhtml+xml.

This means that the respondTo helper will prioritize any handler that match text/html, in our example above, that will be the html handler, but if we remove it then the text handler will be called instead.67

Form Honeypot

[!NOTE] This depends on react and @oslojs/crypto, and @oslojs/encoding.

Honeypot is a simple technique to prevent spam bots from submitting forms. It works by adding a hidden field to the form that bots will fill, but humans won't.

There's a pair of utils in Remix Utils to help you implement this.

First, create a honeypot.server.ts where you will instantiate and configure your Honeypot.

1import { Honeypot } from "remix-utils/honeypot/server";
2
3// Create a new Honeypot instance, the values here are the defaults, you can
4// customize them
5export const honeypot = new Honeypot({
6  randomizeNameFieldName: false,
7  nameFieldName: "name__confirm",
8  validFromFieldName: "from__confirm", // null to disable it
9  encryptionSeed: undefined, // Ideally it should be unique even between processes
10});

Then, in your app/root loader, call honeypot.getInputProps() and return it.

1// app/root.tsx
2import { honeypot } from "~/honeypot.server";
3
4export async function loader() {
5  // more code here
6  return json({ honeypotInputProps: honeypot.getInputProps() });
7}

And in the app/root component render the HoneypotProvider component wrapping the rest of the UI.

1import { HoneypotProvider } from "remix-utils/honeypot/react";
2
3export default function Component() {
4  // more code here
5  return (
6    // some JSX
7    <HoneypotProvider {...honeypotInputProps}>
8      <Outlet />
9    </HoneypotProvider>
10    // end that JSX
11  );
12}

Now, in every public form you want protect against spam (like a login form), render the HoneypotInputs component.

1import { HoneypotInputs } from "remix-utils/honeypot/react";
2
3function SomePublicForm() {
4  return (
5    <Form method="post">
6      <HoneypotInputs label="Please leave this field blank" />
7      {/* more inputs and some buttons */}
8    </Form>
9  );
10}

[!NOTE] The label value above is the default one, use it to allow the label to be localized, or remove it if you don't want to change it.

Finally, in the action the form submits to, you can call honeypot.check.

1import { SpamError } from "remix-utils/honeypot/server";
2import { honeypot } from "~/honeypot.server";
3
4export async function action({ request }) {
5  let formData = await request.formData();
6  try {
7    honeypot.check(formData);
8  } catch (error) {
9    if (error instanceof SpamError) {
10      // handle spam requests here
11    }
12    // handle any other possible error here, e.g. re-throw since nothing else
13    // should be thrown
14  }
15  // the rest of your action
16}

Sec-Fetch Parsers

[!NOTE] This depends on zod.

The Sec-Fetch headers include information about the request, e.g. where is the data going to be used, or if it was initiated by the user.

You can use the remix-utils/sec-fetch utils to parse those headers and get the information you need.

1import {
2  fetchDest,
3  fetchMode,
4  fetchSite,
5  isUserInitiated,
6} from "remix-utils/sec-fetch";

Sec-Fetch-Dest

The Sec-Fetch-Dest header indicates the destination of the request, e.g. document, image, script, etc.

If the value is empty it means it will be used by a fetch call, this means you can differentiate between a request made with and without JS by checking if it's document (no JS) or empty (JS enabled).

1import { fetchDest } from "remix-utils/sec-fetch";
2
3export async function action({ request }: ActionFunctionArgs) {
4  let data = await getDataSomehow();
5
6  // if the request was made with JS, we can just return json
7  if (fetchDest(request) === "empty") return json(data);
8  // otherwise we redirect to avoid a reload to trigger a new submission
9  return redirect(destination);
10}

Sec-Fetch-Mode

The Sec-Fetch-Mode header indicates how the request was initiated, e.g. if the value is navigate it was triggered by the user loading the page, if the value is no-cors it could be an image being loaded.

1import { fetchMode } from "remix-utils/sec-fetch";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let mode = fetchMode(request);
5  // do something based on the mode value
6}

Sec-Fetch-Site

The Sec-Fetch-Site header indicates where the request is being made, e.g. same-origin means the request is being made to the same domain, cross-site means the request is being made to a different domain.

1import { fetchSite } from "remix-utils/sec-fetch";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let site = fetchSite(request);
5  // do something based on the site value
6}

Sec-Fetch-User

The Sec-Fetch-User header indicates if the request was initiated by the user, this can be used to differentiate between a request made by the user and a request made by the browser, e.g. a request made by the browser to load an image.

1import { isUserInitiated } from "remix-utils/sec-fetch";
2
3export async function loader({ request }: LoaderFunctionArgs) {
4  let userInitiated = isUserInitiated(request);
5  // do something based on the userInitiated value
6}

Timers

The timers utils gives you a way to wait a certain amount of time before doing something or to run some code every certain amount of time.

Using the interval combined with eventStream we could send a value to the client every certain amount of time. And ensure the interval is cancelled if the connection is closed.

1import { eventStream } from "remix-utils/sse/server";
2import { interval } from "remix-utils/timers";
3
4export async function loader({ request }: LoaderFunctionArgs) {
5  return eventStream(request.signal, function setup(send) {
6    async function run() {
7      for await (let _ of interval(1000, { signal: request.signal })) {
8        send({ event: "time", data: new Date().toISOString() });
9      }
10    }
11
12    run();
13  });
14}

Middleware

[!NOTE] This depends on react-router, and spec