remix-utils

What is remix-utils?

The remix-utils package provides a collection of utilities to enhance the development experience with Remix, a React framework for building web applications. These utilities cover various aspects such as data loading, error handling, and session management.

What are remix-utils's main functionalities?

Data Loading

The json utility helps in creating JSON responses in loaders and actions, making it easier to handle data fetching and responses.

import { json } from 'remix-utils';

export let loader = async () => {
  let data = await fetchData();
  return json(data);
};

Error Handling

The useCatch hook allows you to handle errors in a more structured way, providing a mechanism to catch and display errors in your components.

import { useCatch } from 'remix-utils';

export function CatchBoundary() {
  let caught = useCatch();
  return (
    <div>
      <h1>{caught.status} {caught.statusText}</h1>
      <p>{caught.data}</p>
    </div>
  );
}

Session Management

The createCookieSessionStorage utility helps in managing sessions using cookies, providing methods to get, commit, and destroy sessions.

import { createCookieSessionStorage } from 'remix-utils';

let { getSession, commitSession, destroySession } = createCookieSessionStorage({
  cookie: {
    name: '__session',
    secrets: ['s3cr3t'],
    sameSite: 'lax',
  },
});

Other packages similar to remix-utils

react-router

React Router is a standard library for routing in React. It provides a collection of navigational components that compose declaratively with your application. While it doesn't offer the same utilities for data loading and session management, it is a core part of the routing mechanism in Remix.

express-session

Express-session is a middleware for managing sessions in Express applications. It provides similar session management capabilities as remix-utils but is designed for use with Express rather than Remix.

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides functionalities for making HTTP requests and handling responses, similar to the data loading utilities in remix-utils, but it is not specific to Remix.

README

Remix Utils

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

To install it you need to have a valid Remix license

Installation

yarn add remix-utils
npm install remix-utils

Remember you need to also install remix, @remix-run/node, @remix-run/react and react. For the first three you need a paid Remix license.

Imports

import { redirectBack, parseBody, json } from "remix-utils";
import type {
  LoaderArgs,
  LoaderReturn,
  ActionArgs,
  ActionReturn,
  LinksArgs,
  LinksReturn,
  MetaArgs,
  MetaReturn,
  HeadersArgs,
  HeadersReturn,
} from "remix-utils";

API

redirectBack

This function is a wrapper of the redirect helper from Remix, contrarian to Remix's version this one receives the whole request object as 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.

import { redirectBack } from "remix-utils";
import type { ActionArgs, ActionReturn } from "remix-utils";

export function action({ request }: ActionArgs): ActionReturn {
  return redirectBack(request, { fallback: "/" });
}

This helper is more useful when used in an action so you can send the user to the same URL it was before.

parseBody

This function receives the whole request and returns a promise with an instance of URLSearchParams, and the body of the request already parsed.

import { parseBody, redirectBack } from "remix-utils";
import type { ActionArgs, ActionReturn } from "remix-utils";

import { updateUser } from "../services/users";

export function action({ request, params }: ActionArgs): ActionReturn {
  const body = await parseBody(request);
  await updateUser(params.id, { username: body.get("username") });
  return redirectBack(request, { fallback: "/" });
}

This is a simple wrapper over doing new URLSearchParams(await request.text());.

json

This function is a typed version of the json helper provided by Remix, it accepts a generic (defaults to unknown) and ensure at the compiler lever that the data you are sending from your loader matches the provided type. It's more useful when you create a type or interface for your whole route so you can share it between json and useRouteData to ensure you are not missing or adding extra parameters to the response.

import { useRouteData } from "remix";
import { json } from "remix-utils";
import type { LoaderArgs, LoaderReturn } from "remix-utils";

import { getUser } from "../services/users";
import type { User } from "../types";

interface RouteData {
  user: User;
}

export async function loader({ request }: LoaderArgs): LoaderReturn {
  const user = await getUser(request);
  return json<RouteData>({ user });
}

export default function View() {
  const { user } = useRouteData<RouteData>();
  return <h1>Hello, {user.name}</h1>;
}

Types

This package exports a list of useful types together with the utility functions, you can import them with

import type {
  LoaderArgs,
  LoaderReturn,
  ActionArgs,
  ActionReturn,
  LinksArgs,
  LinksReturn,
  MetaArgs,
  MetaReturn,
  HeadersArgs,
  HeadersReturn,
} from "remix-utils";

This types are generated from the LoaderFunction, ActionFunction, LinksFunction, MetaFunction and HeadersFunction exported by Remix itself, this ensure they will be up to date with your Remix version.

All the *Args types are the first argument of the equivalent *Funtion type. All the *Return types are the return type of the equivalent *Funtion type.

They are exported in case you don't want to use arrow functions (like me) and still want the types so instead of doing:

export const loader: LoaderFunction = async (args) => {};

You can do:

export async function loader(args: LoaderArgs): LoaderReturn {}

Since all of them are TypeScript types they will not impact your bundle size in case you prefer to use the normal *Function types from Remix.

Author

• Sergio Xalambrí

License

• MIT License