Cookie-based toast notification system for Next.js. Use when user asks to "show toast", "toast notification", "user feedback after action", "toast after redirect", "success message", "error message after form submit", "setToastCookie", "notify user", "flash message", "toast from server action", "show notification after redirect", "display toast after delete".

Toast Notifications Skill

Cookie-based toast notification system for server-to-client messaging.

Reference Files:

architecture.md - How the system works

patterns.md - Usage patterns

examples.md - Practical examples

Project Configuration

The toast system is located in lib/toast/:

lib/toast/
├── constants.ts       # Cookie name and max age
├── types.ts           # ToastType, ToastMessage
├── server/
│   └── toast.cookie.ts  # Server-side cookie setter
└── components/
    └── toast-handler.tsx  # Client-side toast display

Quick Start

Show Toast After Server Action

// features/budget/server/actions/create-budget.ts
"use server";

import { redirect } from "next/navigation";
import { setToastCookie } from "~/lib/toast/server/toast.cookie";

export async function createBudget(data: FormData): RedirectAction {
  const [error, budget] = await createBudgetInDb(data);

  if (error) {
    await setToastCookie("Failed to create budget", "error");
    return { success: false, error: error.message };
  }

  await setToastCookie("Budget created successfully!", "success");
  return redirect(`/budgets/${budget.id}`);
}

Toast Types

import { setToastCookie } from "~/lib/toast/server/toast.cookie";

// Success (green)
await setToastCookie("Operation completed!", "success");

// Error (red)
await setToastCookie("Something went wrong", "error");

// Warning (yellow)
await setToastCookie("Please review your input", "warning");

// Info (blue)
await setToastCookie("New features available", "info");

Custom Duration

// Default duration is ~5 seconds
await setToastCookie("Quick message", "info");

// Custom duration in milliseconds
await setToastCookie("This stays longer", "info", 10000); // 10 seconds

How It Works

Server Action calls setToastCookie() with message and type
Cookie is set with JSON payload: { type, message, duration }
Redirect happens (or response returns)
Client renders new page with ToastHandler component
ToastHandler reads cookie on pathname change
Toast is displayed using design system's Toaster
Cookie is immediately removed

Key Concepts

Why Cookies?

Server Actions often redirect after completion. Since the response is a redirect, we can't pass data directly. Cookies persist across the redirect and can be read on the next page load.

Toast Handler Placement

The ToastHandler is included in components/providers.tsx:

// components/providers.tsx
// import { Toaster } from "your-toast-library"; // sonner, react-hot-toast, etc.
import { ToastHandler } from "~/lib/toast/components/toast-handler";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <YourToaster />   {/* Your toast library's container component */}
      <ToastHandler />  {/* Reads cookie on route change, triggers toasts */}
    </>
  );
}

Pathname-Based Triggering

ToastHandler watches pathname changes using usePathname():

const pathname = usePathname();

React.useEffect(() => {
  // Check and display toast on route change
}, [pathname]);

This ensures toasts appear after navigation.

API Reference

setToastCookie

async function setToastCookie(
  message: string,
  type: ToastType = "success",
  duration?: number,
): Promise<void>;

Parameter	Type	Default	Description
`message`	string	required	Toast message text
`type`	ToastType	"success"	Toast variant
`duration`	number	undefined	Display duration in ms

ToastType

type ToastType = "success" | "error" | "info" | "warning";

ToastMessage

interface ToastMessage {
  type: ToastType;
  message: string;
  duration?: number;
}

File Locations

Purpose	Location
Server cookie setter	`lib/toast/server/toast.cookie.ts`
Client handler	`lib/toast/components/toast-handler.tsx`
Types	`lib/toast/types.ts`
Constants	`lib/toast/constants.ts`
Providers	`components/providers.tsx`

Related Skills

server-actions - Using toasts with server actions
clerk-auth-proxy - Toast after auth operations

toast-notifications