Remix Utilities

Common errors

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

  cause 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

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Version 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.
• breaking Upgrading 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.
• gotcha Many 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.
• gotcha Several 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.
• breaking In 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.
• gotcha The `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.

Install

• npm install remix-utils npm
• yarn add remix-utils yarn
• pnpm add remix-utils pnpm

Imports

• promiseHash
  wrong:

  import { promiseHash } from 'remix-utils';

  correct:

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

  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
  wrong:

  import { timeout } from 'remix-utils';

  correct:

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

  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
  wrong:

  import { cacheAssets } from 'remix-utils';

  correct:

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

  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)
  wrong:

  import { json } from 'remix-utils';

  correct:

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

  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.

Quickstart

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 });
  }
}