remix-utils

library9.3.1jsnpmunverified

remix-utils is a comprehensive collection of modular utility functions designed to extend the capabilities of applications built with the Remix framework and React Router. As of version 9.3.1, this library offers a wide array of tools covering both server-side and client-side concerns. Its utilities range from advanced data loading patterns like `promiseHash` for concurrent fetches and `timeout` for resilient API calls, to server-side middleware for handling common web challenges such as client IP detection, CORS, CSRF protection, request ID generation, and server timing. Client-side enhancements include functions like `cacheAssets` for efficient browser caching of build artifacts. The package maintains an `active` and consistent release cadence, frequently pushing out minor and patch updates to introduce new features, resolve bugs, and ensure seamless compatibility with the evolving Remix and React Router ecosystems. A key distinguishing factor is its highly modular design, which allows developers to selectively install and import only the specific utilities needed, thereby keeping bundles lean. Many components can even be installed via a shadcn-like registry for simplified management. This approach differentiates it from monolithic utility libraries, promoting a more focused and performant integration within Remix projects.

web-framework http-networking auth-security observability serialization

npm install remix-utils

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REMIX-UTILS

remix-utils

web-frameworkjavascriptv9.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

promiseHash

✓ import { promiseHash } from 'remix-utils/promise';

✗ import { promiseHash } from 'remix-utils';

Many utilities are exposed via subpath exports; `promiseHash` is located under the 'promise' subpath. This is a common pattern for modular libraries to avoid bloating the main bundle.

timeout

✓ import { timeout, TimeoutError } from 'remix-utils/promise';

✗ import { timeout } from 'remix-utils';

The `timeout` utility and its associated `TimeoutError` are also found in the 'promise' subpath. Always import the error type if you plan to catch specific timeout exceptions.

cacheAssets

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

✗ import { cacheAssets } from 'remix-utils';

This function is specifically designed for client-side execution within `entry.client`. Importing it from the root or attempting to run it on the server will result in errors.

json (middleware helper)

✓ import { json } from 'remix-utils/json';

✗ import { json } from 'remix-utils';

Utility functions or middleware like `json` are often found under specific subpaths. Always check the documentation or the library's `package.json` exports for the exact import path.

This example demonstrates using `promiseHash` to concurrently fetch multiple data sources in a Remix loader and applies `timeout` to an external API call to prevent long-running requests from blocking the response, handling potential `TimeoutError`s gracefully.

import { json } from "@remix-run/node"; import { promiseHash, timeout, TimeoutError } from "remix-utils/promise"; // Mock API calls async function getUser(request: Request): Promise<{ id: string; name: string }> { await new Promise(resolve => setTimeout(resolve, Math.random() * 50)); return { id: "user-123", name: "John Doe" }; } async function getPosts(request: Request): Promise<{ id: string; title: string }[]> { await new Promise(resolve => setTimeout(resolve, Math.random() * 150)); return [{ id: "post-a", title: "My First Post" }, { id: "post-b", title: "Another One" }]; } // A potentially slow external service async function getExternalData(request: Request): Promise<string> { await new Promise(resolve => setTimeout(resolve, 200)); // Simulating a slow API return "External data loaded!"; } export async function loader({ request }: { request: Request }) { try { const { user, posts, externalData } = await promiseHash({ user: getUser(request), posts: getPosts(request), // Attach a timeout to a potentially slow external call externalData: timeout(getExternalData(request), { ms: 100, message: "External data timed out" }) }); return json({ user, posts, externalData }); } catch (error) { if (error instanceof TimeoutError) { console.error("Loader timeout error:", error.message); return json({ error: "One or more external services timed out. Please try again." }, { status: 504 }); } console.error("Loader error:", error); return json({ error: "An unexpected error occurred." }, { status: 500 }); } }

Debug

Known issues

breakingVersion 9.0.0 removed `Typed Session Storage` and its dependency on Zod v3. If your application relied on these features for schema-validated sessions, significant refactoring is required.

fix

Migrate session validation to use `@standard-schema/spec` as introduced in v8.8.0, or implement custom validation logic. Review the v8.x to v9.x upgrade guides.

affects: >=9.0.0

breakingUpgrading from v6 to v7 introduced breaking changes that require following a specific upgrade guide. Subsequent major version upgrades (e.g., v8 to v9) also often contain breaking changes due to alignment with Remix and React Router versions.

fix

Always consult the release notes and upgrade guides in the documentation (e.g., `./docs/v6-to-v7.md`) before performing major version upgrades.

affects: >=7.0.0

gotchaMany utilities in `remix-utils` are exposed as deeply nested or subpath exports (e.g., `remix-utils/promise`, `remix-utils/cache-assets`). Importing directly from `remix-utils` for these specific utilities will lead to module not found errors.

fix

Always refer to the package documentation or the `package.json`'s `exports` field to determine the correct subpath for the specific utility you intend to use.

affects: >=1.0.0

gotchaSeveral utilities depend on optional peer dependencies that are not automatically installed with `remix-utils`. Forgetting to install these specific dependencies will lead to runtime errors when using the associated features.

fix

Check the documentation for each utility you use and ensure all listed optional dependencies (e.g., `@oslojs/crypto` for CSRF, `is-ip` for client IP detection) are explicitly installed in your project.

affects: >=1.0.0

breakingIn v9.0.0, the type for the `middleware` context was marked as read-only. This change impacts middleware functions that attempted to directly mutate the context object.

fix

Refactor middleware logic to avoid direct mutation of the context. Instead, return new context objects or use other patterns for state management within middleware pipelines.

affects: >=9.0.0

gotchaThe `cacheAssets` utility is strictly client-side and must only be executed within your `entry.client` file. Attempting to call it in a server-side context (e.g., a loader or action) will result in a runtime error indicating a non-browser environment.

fix

Ensure `cacheAssets` is placed exclusively within your Remix `entry.client.ts` or `entry.client.tsx` file to guarantee it runs in a browser environment.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'remix-utils/my-utility' from '/path/to/your/app'

Incorrect import path for a specific utility. Many utilities are located under subpath exports, not directly from the root `remix-utils` package.

fix

Correct the import statement to use the specific subpath, e.g., `import { promiseHash } from 'remix-utils/promise';` or `import { cacheAssets } from 'remix-utils/cache-assets';`.

TypeError: (0 , _remix_utils_csrf.createCSRF) is not a function

A required optional peer dependency for the specific utility is missing. For example, the CSRF middleware requires `@oslojs/crypto`.

fix

Identify the missing dependency by checking the documentation for the specific utility. Install it using `npm add <dependency-name>`, e.g., `npm add @oslojs/crypto`.

ReferenceError: Zod is not defined

Attempting to use `Typed Session Storage` or related Zod-based features after upgrading to `remix-utils` v9.0.0 or later, where these features were removed.

fix

Refactor your session management. For typed sessions, consider migrating to patterns supported by `@standard-schema/spec` as introduced in v8.8.0, or use standard Remix session storage.

Invariant failed: Expected a browser environment

The `cacheAssets` utility was called in a server-side context (e.g., a Remix loader, action, or `entry.server`).

fix

Move the `cacheAssets()` call exclusively into your `app/entry.client.ts` or `app/entry.client.tsx` file.

Upgrade

Version history

9.3.1latest on npm

Audit

Dependencies

reactrequiredCore React dependency for all UI utilities and Remix.

react-routerrequiredCore routing dependency for all UI utilities and Remix.

@edgefirst-dev/batcheroptionalRequired for specific batching utilities.

@edgefirst-dev/jwtoptionalRequired for JWT-related middleware.

@edgefirst-dev/server-timingoptionalRequired for server timing middleware.

@oslojs/cryptooptionalRequired for cryptographic operations, e.g., CSRF middleware.

is-ipoptionalRequired for client IP detection utilities.

@standard-schema/specoptionalUsed for schema validation, especially after removal of Zod-based typed sessions.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sergiodxa/remix-utils ↗

packagehttps://www.npmjs.com/package/remix-utils ↗

homepagehttps://remix-utils.com ↗