Sheet 03Server / Client BoundaryNext.js 16.2.10Rev. 2026-07-13

Firing a toast
across the seam

No toast library ships a server entrypoint. The queue is client memory in all three. A server mutation can only describe a toast and hand it across the boundary — and which channel it hands it through is decided by one question.

Scale1 : 1 code

Sources25 cited

Depthsurvey

A module carrying the directive — and everything it imports — is bundled and evaluated on the client ^[6]. All three libraries ship it as the first line of their ESM bundle, verified against the published dist. So <Toaster /> drops into a Server Component layout unchanged — but toast(), the imperative queue-push, is a client reference. A Server Function cannot call it.

Practical reading: "RSC-safe" is table stakes and means less than it sounds. The directive buys you a <Toaster /> in app/layout.tsx without a hand-rolled wrapper. It does not make toast() callable from server code. Every server-origin toast is therefore a serialization problem, not a library feature — which is why the reference implementation is a blog post, not an API ^[1].

Client-boundary cost is the toaster subtree, not the layout: 4.8–9.7 kB gzip, evaluated once, no dependency drag. This is not a reason to pick between them.

useActionState(action, initialState) returns [state, formAction, isPending]; the state is whatever the action returned, redelivered through the RSC payload ^[5].

'use server'
import { revalidatePath } from 'next/cache'

export type ActionState =
  | { status: 'success' | 'error'; message: string; at: number }1
  | null

export async function savePost(
  _prev: ActionState,
  formData: FormData,
): Promise<ActionState> {
  const title = String(formData.get('title') ?? '')
  if (!title) return { status: 'error', message: 'Title is required', at: Date.now() }

  await db.post.create({ data: { title } })
  revalidatePath('/posts')2
  return { status: 'success', message: `Saved “${title}”`, at: Date.now() }
}

'use client'
import { useActionState, useEffect, useRef } from 'react'
import { toast } from 'sonner'
import { savePost, type ActionState } from './actions'

export function PostForm() {
  const [state, formAction, isPending] = useActionState<ActionState, FormData>(savePost, null)
  const lastToasted = useRef(0)3

  useEffect(() => {
    if (!state || state.at === lastToasted.current) return4
    lastToasted.current = state.at
    const fire = state.status === 'success' ? toast.success : toast.error
    fire(state.message)
  }, [state])

  return (
    <form action={formAction}>
      <input name="title" />
      <button disabled={isPending}>Save</button>
    </form>
  )
}

• 1at is not decoration — it is the pattern. It is the nonce. Remove it and the code breaks in two opposite directions at once (callouts 2 and 4).
• 2Stale re-toast. revalidatePath re-renders the tree; state deserializes into a new object with the same contents, the effect's dependency changes by identity, and the old message toasts again with no new submission. Robin Wieruch: “If the component re-renders, it might show an old toast message even if no new action was triggered” ^[2]. Next's own docs state the mechanism: “The UI is not unmounted, but effects that depend on data coming from the server will re-run” ^[4].
• 3A ref, not state. Refs survive StrictMode's simulated remount, so the guard doubles as the StrictMode fix — see the strip below.
• 4Missing toast (the opposite failure). Submit the same invalid form twice and the action returns a structurally identical object. Without a nonce nothing in the deps array changed → no second toast → the user thinks the button is dead.

If you don't need progressive enhancement, the effect is pure ceremony. await the action and toast in the same tick.

'use client'
import { useTransition } from 'react'
import { toast } from 'sonner'
import { deletePost } from './actions'

export function DeleteButton({ id }: { id: string }) {
  const [isPending, startTransition] = useTransition()

  return (
    <button
      disabled={isPending}
      onClick={() =>
        startTransition(async () => {
          const res = await deletePost(id) // plain serializable result, never throws to the client
          res.ok ? toast.success('Post deleted') : toast.error(res.message)5
        })
      }
    >
      Delete
    </button>
  )
}

• 5No effect, no nonce, no StrictMode double-fire, no stale replay. This is the “direct promise awaiting” answer the Next.js discussion converges on ^[7] ⭐ 141k. The cost: the button needs JS (no no-JS form fallback), and the action must not redirect().

next-safe-action ⭐ 3.0k packages this with typed callbacks, so the toast site is declarative rather than an effect ^[25]:

const { execute } = useAction(createPost, {
  onSuccess: ({ data }) => toast.success(`Created: ${data.name}`),
  onError:   ({ error }) => toast.error(error.serverError ?? 'Invalid input'),
})

Ref: next-safe-action · useAction ^[22]

redirect() throws a NEXT_REDIRECT error and terminates rendering of the segment; in a Server Action it serves a 303 ^[3]. Three consequences, all fatal to Channels A and B:

• 1The action never returns → useActionState state never updates → the effect never fires ^[7] ⭐ 141k.
• 2The client component that owns the effect is unmounted by the navigation anyway.
• 3Because it throws, redirect() must be called outside any try block — a try/catch around your mutation will swallow the redirect ^[3].

The workaround the ecosystem settled on — and the one Next's own discussion threads recommend — is to set a cookie before redirecting and read it on the next render ^[9] ⭐ 141k ^[8]. Cookies are the only channel that survives a 303, a hard reload, and a new tab ^[1].

import 'server-only'
import { cookies } from 'next/headers'

export type Flash = { status: 'success' | 'error'; message: string }

export async function setFlash(flash: Flash) {
  const store = await cookies()
  // random name, not a fixed key: two flashes in one request must not overwrite each other
  store.set(`flash-${crypto.randomUUID()}`, JSON.stringify(flash), {6
    path: '/',
    maxAge: 60,
    httpOnly: true,
    sameSite: 'lax',
  })
}

export async function readFlash() {
  const store = await cookies()
  return store
    .getAll()
    .filter((c) => c.name.startsWith('flash-') && c.value)
    .map((c) => ({ id: c.name, ...(JSON.parse(c.value) as Flash) }))
}

'use server'
import { redirect } from 'next/navigation'
import { setFlash } from '@/lib/flash'

export async function createPost(formData: FormData) {
  const post = await db.post.create({ data: { title: String(formData.get('title')) } })
  await setFlash({ status: 'success', message: 'Post created' })
  redirect(`/posts/${post.id}`) // last statement — it throws7
}

import { Toaster } from 'sonner'
import { readFlash } from '@/lib/flash'
import { FlashToaster } from './flash-toaster'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const flashes = await readFlash()8
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
        <FlashToaster flashes={flashes} />
      </body>
    </html>
  )
}

'use client'
import { useEffect, useRef } from 'react'
import { toast } from 'sonner'
import { clearFlash } from './flash-actions' // 'use server'

export function FlashToaster({ flashes }: { flashes: Array<{ id: string } & Flash> }) {
  const fired = useRef(new Set<string>())

  useEffect(() => {
    for (const f of flashes) {
      if (fired.current.has(f.id)) continue
      fired.current.add(f.id)
      ;(f.status === 'success' ? toast.success : toast.error)(f.message)
      void clearFlash(f.id) // must be a Server Function; see below9
    }
  }, [flashes])

  return null
}

• 6The random suffix (rather than a single flash key) is Build UI's trick — it lets multiple messages queue in one request without clobbering each other ^[1].
• 7redirect() is the last statement, outside any try. Everything after it is unreachable — it throws.
• 8⚠ The buried bill. Reading cookies() here opts every route into dynamic rendering — cookies is a request-time API: “Using it in a layout or page will opt a route into dynamic rendering” ^[4]. A static-first app that reads flash cookies in app/layout.tsx is no longer static-first.
• 9You cannot cookies().delete() while rendering a Server Component: “HTTP does not allow setting cookies after streaming starts, so you must use .set in a Server Function or Route Handler” — .delete likewise ^[4]. So the drain must be a client-triggered Server Function, not part of the read. Build UI hides the latency with useOptimistic ^[1].

Same tension — the mutation runs on the server, the toast is client state — but the framework has a first-class channel, inherited from Rails: a value written with session.flash(key, value) is deleted the first time it is read ^[19].

export async function action({ request }: Route.ActionArgs) {
  const session = await getSession(request.headers.get('Cookie'))
  const post = await createPost(await request.formData())

  session.flash('toast', { status: 'success', message: 'Post created' })

  return redirect(`/posts/${post.id}`, {
    headers: { 'Set-Cookie': await commitSession(session) },10
  })
}

export async function loader({ request }: Route.LoaderArgs) {
  const session = await getSession(request.headers.get('Cookie'))
  const toast = session.get('toast')            // reading consumes it11
  return data({ toast }, { headers: { 'Set-Cookie': await commitSession(session) } })
}

Structurally identical to Channel C — a cookie carrying the message across a redirect — with three differences that matter:

• 10Explicit headers. You must re-commitSession in the loader or the deletion never reaches the browser. ⚠ And the docs warn about nested routes: “When using session.flash() or session.unset(), you need to be sure no other loaders in the request are going to want to read that, otherwise you'll get race conditions… if another loader wants a flash message, use a different key” ^[19].
• 11Self-destructing. The flash is consumed on read, so the “who deletes the cookie” problem that forces Next into a client-triggered Server Function ^[4] simply does not arise. Reload cannot re-toast ^[20] ⭐ 57k.
• 12Still a useEffect on the client. The root component watches loaderData.toast and calls toast() — same StrictMode double-fire, same need for a dedupe key. remix-toast ⭐ 262 packages the whole loop (redirectWithSuccess, getToast returning { toast, headers }) for React Router v7 ^[21].

01Build UI — Toast messages in RSCThe reference implementation: uuid-named cookies 02Robin Wieruch — useActionState + toastThe stale re-toast, and the nonce fix 03Next.js docs — redirect()NEXT_REDIRECT · 303 · call outside try/catch 04Next.js docs — cookies().set/.delete only in a Server Function · dynamic rendering 05React docs — useActionState[state, dispatchAction, isPending] 06React docs — 'use client'The module boundary itself 07next.js #67660 ⭐ 141kDuplicate/stale toasts · await the promise directly 08next.js #77389 ⭐ 141kThe three canonical redirect-toast options · no maintainer answer 09next.js #57118 ⭐ 141kReturn-JSON and redirect() are mutually exclusive 10sonner #322 ⭐ 13kStrictMode double-toast · closed as expected 11Sonner — getting started<Toaster/> may live in a server layout.tsx 12sonner@2.0.7 dist'use client' — line 1 13react-hot-toast@2.6.0 dist'use client' — line 1 14react-toastify@11.1.0 dist'use client' — line 1 15shadcn/ui #8173 ⭐ 119kDirective-less re-export erases the boundary 16Bundlephobia — sonner 2.0.734.2 kB min · 9.4 kB gzip · 0 deps 17Bundlephobia — react-hot-toast 2.6.012.2 kB min · 4.8 kB gzip 18Bundlephobia — react-toastify 11.1.034.4 kB min · 9.7 kB gzip 19React Router — sessions & cookiessession.flash() · deleted on first read · nested-loader races 20react-router #11872 ⭐ 57kFlash beats URL params — refreshes re-trigger those 21remix-toast ⭐ 262redirectWithSuccess · getToast → { toast, headers } 22next-safe-action — useActiononSuccess / onError / onSettled callbacks 23React docs — StrictModesetup → cleanup → setup, in development only 24Next.js — hydration errorThe risk is the payload, not the empty toaster 25next-safe-action ⭐ 3.0kType-safe Server Actions with hooks and callbacks