Server-Side Toast Notifications for Remix

Common errors

• TypeError: (0 , remix_toast_middleware__WEBPACK_IMPORTED_MODULE_2__.getToast) is not a function

  cause Incorrect import path for `getToast` or `unstable_toastMiddleware`.
  fix Ensure `getToast` and `unstable_toastMiddleware` are imported from `remix-toast/middleware` and not directly from `remix-toast`.

• Error: Your Remix application must be using React Router v7 to use remix-toast v2.0.0+

  cause Using `remix-toast` v2.0.0 or higher with an incompatible (older) version of `react-router`.
  fix Upgrade your `react-router` dependency to v7 or higher, or downgrade `remix-toast` to v1.x if you're stuck on an older `react-router` version.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an ESM-only environment, or vice-versa.
  fix Use ESM `import` statements for `remix-toast` as it's designed for modern Remix projects which are typically ESM. If forced to use CJS, configure your build system to transpile or adjust imports accordingly.

Warnings

• breaking The `json*` utilities (e.g., `jsonSuccess`) were renamed to `data*` (e.g., `dataSuccess`) to align with React Router v7 conventions.
  Fix: Update all instances of `jsonSuccess`, `jsonError`, etc., to `dataSuccess`, `dataError` respectively.
• breaking Version 3.0.0 introduced a new 'Middleware mode' for global toast management. This requires changes to `root.tsx` to import `getToast` and `unstable_toastMiddleware` from `remix-toast/middleware` and pass the toast to the client side.
  Fix: Implement the middleware setup in your `root.tsx` as described in the v3.0.0 changelog, specifically importing from `remix-toast/middleware` and handling `getToast` in your root loader.
• gotcha The `unstable_toastMiddleware` API was stabilized for `react-router` v7.9+ in version 3.3.0. Using older versions of `react-router` might lead to unexpected behavior or API mismatches when relying on the middleware.
  Fix: Ensure your `react-router` peer dependency is at least `7.9.0` (or higher if specified by `remix-toast`) to guarantee stable middleware functionality.
• breaking Version 4.0.0 upgraded the internal dependency `zod` to v4. While this is primarily an internal change, if your application directly relies on `zod` and has specific version constraints, this upgrade might cause conflicts or require you to also upgrade your `zod` dependency.
  Fix: Review your project's direct `zod` dependencies and upgrade them to v4 if conflicts arise or if you encounter type mismatches related to `zod` schemas used in conjunction with `remix-toast`.
• gotcha When setting toasts, the `duration` parameter was made optional and can be set to zero. Older versions might not correctly handle a `duration` of zero or might require it to be a positive number.
  Fix: Update to `remix-toast` v3.4.0 or newer if you intend to use a `duration` of zero to control toast visibility programmatically without auto-hiding.

Install

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

Imports

• createToast
  wrong:

  const { createToast } = require('remix-toast');

  correct:

  import { createToast } from 'remix-toast';

  Primary utility for creating toast messages in Remix actions/loaders. Package is ESM-first.
• getToast
  wrong:

  import { getToast } from 'remix-toast';

  correct:

  import { getToast } from 'remix-toast/middleware';

  Used to extract the toast message from the request context, requires specific middleware path since v3.0.0.
• unstable_toastMiddleware
  wrong:

  import { unstable_toastMiddleware } from 'remix-toast';

  correct:

  import { unstable_toastMiddleware } from 'remix-toast/middleware';

  Enables global toast management, allowing toasts to be set anywhere. Path is critical and the 'unstable' prefix indicates potential future API changes. Stabilized for RR v7.9+ in v3.3.0.
• useToast
  wrong:

  const useToast = require('remix-toast').useToast;

  correct:

  import { useToast } from 'remix-toast';

  React hook for accessing toast data in client-side components. ESM import required.

Quickstart

This quickstart demonstrates how to set up server-side toast notifications in a Remix application using `remix-toast`. It covers configuring a session storage, initializing the `toast` utility, extracting and displaying toasts in a `loader` and `action`, and rendering them on the client-side.

import { createCookieSessionStorage, redirect } from '@remix-run/node';
import { createToast, getToast, unstable_toastMiddleware } from 'remix-toast/middleware';
import { json } from '@remix-run/react';
import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';

// 1. Configure a session storage (replace with your actual session store)
const { getSession, commitSession } = createCookieSessionStorage({
  cookie: {
    name: '__session',
    httpOnly: true,
    maxAge: 60 * 60 * 24 * 7, // 1 week
    secrets: [process.env.SESSION_SECRET ?? 'super-secret'],
    secure: process.env.NODE_ENV === 'production',
  },
});

// 2. Setup toast middleware
export const { toast, flash } = createToast(getSession, commitSession);

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { toast, headers } = await getToast(request);
  // Simulate fetching some data
  const data = { message: 'Welcome back!' };
  return json({ data, toast }, { headers });
};

export const action = async ({ request }: ActionFunctionArgs) => {
  const formData = await request.formData();
  const email = formData.get('email');

  if (email === 'error@example.com') {
    return await toast.error(redirect('/'), { message: 'Invalid email address.' });
  }

  return await toast.success(redirect('/'), { message: 'Subscription successful!' });
};

export default function Index() {
  const { toast } = useLoaderData<typeof loader>();

  return (
    <div>
      {toast && (
        <div style={{ padding: '10px', background: toast.type === 'error' ? 'red' : 'green', color: 'white' }}>
          {toast.message}
        </div>
      )}
      <h1>Remix Toast Example</h1>
      <form method="post">
        <input type="email" name="email" placeholder="Enter email" />
        <button type="submit">Subscribe</button>
      </form>
    </div>
  );
}