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

code

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

typescript

// 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

typescript

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

typescript

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

typescript

// components/providers.tsx
import { Toaster } from "@szum-tech/design-system";
import { ToastHandler } from "~/lib/toast/components/toast-handler";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <Toaster />
      <ToastHandler />
    </>
  );
}

Pathname-Based Triggering

ToastHandler watches pathname changes using usePathname():

typescript

const pathname = usePathname();

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

This ensures toasts appear after navigation.

API Reference

setToastCookie

typescript

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

typescript

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

ToastMessage

typescript

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