remix-toast

library4.0.0jsnpmunverified

remix-toast provides utility functions to manage server-side toast notifications within Remix applications, leveraging web standards like `Set-Cookie` for flash messages. It seamlessly integrates with Remix's `loader` and `action` functions and supports React Router v7. The current stable version is 4.0.0, which includes an upgrade to Zod v4. The package appears to have an active release cadence, with frequent updates (minor and patch releases) to address bug fixes, introduce new features like `replaceWithFlash`, and maintain compatibility with new versions of Remix and React Router (e.g., v7.9+ for `react-router`). Key differentiators include its server-side first approach, middleware support for global toast management, and flexible session storage configuration, allowing custom utility creation with `createToastUtilsWithCustomSession`.

web-framework communication

npm install remix-toast

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REMIX-TOAST

remix-toast

web-frameworkjavascriptv4.0.0

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.

createToast

✓ import { createToast } from 'remix-toast';

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

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

getToast

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

✗ import { getToast } from 'remix-toast';

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

unstable_toastMiddleware

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

✗ import { unstable_toastMiddleware } from 'remix-toast';

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

✓ import { useToast } from 'remix-toast';

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

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

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

Debug

Known issues

breakingThe `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.

affects: >=2.0.0

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

affects: >=3.0.0

gotchaThe `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.

affects: <3.3.0

breakingVersion 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`.

affects: >=4.0.0

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

affects: <3.4.0

Errors

Common errors & fixes

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

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+

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

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

react-routerrequiredPeer dependency for routing context and utilities, specifically `>=7.9.0` for full compatibility with middleware API stabilization.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/forge-42/remix-toast ↗

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

homepagehttps://remix-toast.netlify.app ↗