Remix Utils

This package contains simple utility functions to use with Remix.run.

Installation

npm install remix-utils

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

• @remix-run/react (also @remix-run/router but you should be using the React one)
• @remix-run/node or @remix-run/cloudflare or @remix-run/deno (actually it's @remix-run/server-runtime but you should use one of the others)
• crypto-js
• 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:

npm add crypto-js is-ip intl-parse-accept-language zod

React and the @remix-run/* packages should be already installed in your project.

Upgrade from Remix Utils v6

If you used Remix Utils before, you will notice some changes.

1. The package is published as ESM only
2. Every util now has a specific path in the package, so you need to import them from remix-utils/.
3. All dependencies are now optional, so you need to install them yourself.

Usage with CJS

Since v7 of Remix Utils the package is published as ESM-only (plus type definitions). This means if you're using Remix with CJS you need to configure it to bundle Remix Utils.

In your remix.config.js file, add this:

module.exports = {
	serverDependenciesToBundle: [
		/^remix-utils.*/,
		// If you installed is-ip optional dependency you will need these too
		"is-ip",
		"ip-regex",
		"super-regex",
		"clone-regexp",
		"function-timeout",
		"time-span",
		"convert-hrtime",
		"is-regexp",
	],
};

If you're not sure if your app uses ESM or CJS, check if you have serverModuleFormat in your remix.config.js file to know.

In case you don't have one, if you're using Remix v1 it will be CJS and if you're using Remix v2 it will be ESM.

If you're using Vite, but still building to CJS, you will need to add this package to noExternal, so it's bundled with your server code. Therefore, add the following to defineConfig() in vite.config.ts:

ssr: {
      noExternal: ["remix-utils"],
    },

> Note > Some of the optional dependencies in Remix Utils may still be published as CJS, so you may need to add them to serverDependenciesToBundle too.

Another thing to consider if you did the upgrade from Remix v1 to Remix v2 is that in your tsconfig.json you will need to set "moduleResolution": "Bundler", otherwise TS will not resolve the new import paths.

Updated Import Paths

You will need to change your imports to use the correct one. So instead of doing:

import { eventStream, useEventSource } from "remix-utils";

You need to change it to:

import { eventStream } from "remix-utils/sse/server";
import { useEventSource } from "remix-utils/sse/react";

This adds more lines but enables the next change.

Optional Dependencies

Before, Remix Utils installed some dependencies like Zod that you may never used.

Current version marks every dependency as optional, so you need to install them yourself.

While this is more works it means the package can keep using more dependencies as needed without increasing the bundle size for everyone. Only if you use the dependency that depends on Zod you will install and include Zod in your bundle.

Every util mentions what dependencies it requires and the Installation section mentions the whole list in case you want to install them all upfront.

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.

import { promiseHash } from "remix-utils/promise";

export async function loader({ request }: LoaderFunctionArgs) {
	return json(
		await promiseHash({
			user: getUser(request),
			posts: getPosts(request),
		}),
	);
}

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

import { promiseHash } from "remix-utils/promise";

export async function loader({ request }: LoaderFunctionArgs) {
	return json(
		await promiseHash({
			user: getUser(request),
			posts: promiseHash({
				list: getPosts(request),
				comments: promiseHash({
					list: getComments(request),
					likes: getLikes(request),
				}),
			}),
		}),
	);
}

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.

import { timeout } from "remix-utils/promise";

try {
	let result = await timeout(fetch("https://example.com"), { ms: 100 });
} catch (error) {
	if (error instanceof TimeoutError) {
		// Handle timeout
	}
}

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.

import { timeout } from "remix-utils/promise";

try {
	let controller = new AbortController();
	let result = await timeout(
		fetch("https://example.com", { signal: controller.signal }),
		{ ms: 100, controller },
	);
} catch (error) {
	if (error instanceof TimeoutError) {
		// Handle timeout
	}
}

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:

import { cacheAssets } from "remix-utils/cache-assets";

cacheAssets().catch((error) => {
	// do something with the error, or not
});

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.

import { cacheAssets } from "remix-utils/cache-assets";

cacheAssests({ cacheName: "assets", buildPath: "/build/" }).catch((error) => {
	// do something with the error, or not
});

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.

import { ClientOnly } from "remix-utils/client-only";

export default function Component() {
	return (
		}>
			{() => }
		
	);
}

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.

import { ServerOnly } from "remix-utils/server-only";

export default function Component() {
	return (
		}>
			{() => }
		
	);
}

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 `