start-toast

Use this if: you're building with TanStack Start (TSS) and need server-set flash toasts — staging a toast from a server function and having it surface after redirect. Equivalent to remix-toast for the TSS server-fn / h3-cookie model. Headless: bring your own toast UI.

Keywords: TanStack Start, TSS, toast, flash message, notification, server function, cookie flash, redirect-with-success, headless toast, remix-toast-equivalent.

Server-set toast notifications for TanStack Start. A 1:1 adaptation of remix-toast for TanStack Start's server-fn / cookie-bridge model. Published on npm as react-start-toast.

If you've used remix-toast, you already know the API — setFlashToast, redirectWithSuccess, consumeFlashToast, etc. — they work the same way. This lib closes the equivalent gap for TanStack Start.

Community library by @stevan-borus. Built for TanStack Start; not maintained by the TanStack team. Expect breaking changes on 0.x minor bumps until 1.0.0.

Features

Headless — bring your own toast UI (sonner, react-toastify, your own). The lib only fires notify(toast) and lets you render the rest.
Type-safe — every export is fully typed; the wire format is a zod schema.
Strict server/client split — server helpers ship under /server; only the React adapter touches the client bundle.
Composable — orthogonal helpers (setFlashToast, redirectWithError, <ToastProvider>) compose inside your own server fns.
Footgun-proofed — <ToastProvider> bakes in the source-order rule so subscribe-on-mount toast UIs receive the event.

Install

pnpm add react-start-toast

The lib peer-depends on @tanstack/react-router, @tanstack/react-start, react, and react-dom.

Setup

The lib has two entrypoints, by design:

Import path	Use from	Provides
`react-start-toast`	Client-bundled files	`FlashToastEffect`, `ToastProvider`, type re-exports
`react-start-toast/server`	Server-only files	`setFlashToast`, `consumeFlashToast`, `setFlashCookieOptions`, `redirectWith`, `replaceWith`

Why the split: the /server entry imports h3's getCookie/setCookie (which pull node:async_hooks). If the renderer and the server helpers shared one entry, any consumer who bundled the renderer for the browser would crash hydration with AsyncLocalStorage is not a constructor. Splitting keeps server-only code purely server-side.

1. Set the cookie secret

Set START_TOAST_SECRET (≥32 characters) in your server environment. That's the only required setup.

For runtime-resolved secrets (Vault, AWS Secrets Manager, etc.), call setFlashCookieOptions once at app boot from a server-bundled file:

// In e.g. src/server.ts (anywhere server-only)
import { setFlashCookieOptions } from 'react-start-toast/server'

setFlashCookieOptions({
  name: 'my-flash',
  maxAge: 30,
  secret: () => myVault.read('flash-secret'),
})

Precedence: explicit config > env var > throw.

2. Add a `.server.ts` re-export

Create one local file in your source tree that re-exports the server-only helpers you'll use. The .server.ts extension activates TanStack Start's import-protection plugin (matches **/*.server.*), which tells Vite to externalize anything imported from this file from the client bundle.

// src/flash-toast-bridge.server.ts
export {
  consumeFlashToast,
  redirectWithError,
  redirectWithSuccess,
  setFlashToast,
  // ...whichever helpers you actually use
} from 'react-start-toast/server'

Every server-only import in the rest of your app goes through this file at the top level — no dynamic-import ceremony needed at call sites. See Why a .server.ts re-export? below for why this matters.

3. Define a local server fn that reads the cookie

consumeFlashToastFn is the one RPC seam the bridge needs — your __root.tsx loader calls it to surface the staged toast. It's not published from the lib (TSS's compiler only strips server-fn handler bodies for files in your source tree, not pre-built lib files), so each consumer defines it locally:

// src/flash-toast.functions.ts
import { createServerFn } from '@tanstack/react-start'
import type { FlashToast } from 'react-start-toast'
import { consumeFlashToast } from './flash-toast-bridge.server'

export const consumeFlashToastFn = createServerFn({ method: 'POST' }).handler(
  async (): Promise<FlashToast | null> => consumeFlashToast(),
)

4. Wire the renderer in `__root.tsx`

import { createRootRoute, Outlet, Scripts } from '@tanstack/react-router'
import { ToastProvider } from 'react-start-toast'
import { Toaster, toast } from 'sonner'
import { consumeFlashToastFn } from '../flash-toast.functions'

export const Route = createRootRoute({
  loader: async () => ({ flashToast: await consumeFlashToastFn() }),
  component: RootComponent,
})

function RootComponent() {
  const { flashToast } = Route.useLoaderData()
  return (
    <ToastProvider
      toaster={<Toaster />}
      toast={flashToast}
      notify={(t) => toast[t.type](t.message, t)}
    >
      <Outlet />
    </ToastProvider>
  )
}

<ToastProvider> mounts the toaster first, then the bridge, so subscribe-on-mount UIs (sonner, react-toastify, etc.) are listening before the bridge fires notify. If you compose the pieces yourself with <FlashToastEffect>, the same source-order rule applies — see Source-order constraint.

5. Stage toasts from server fns

Top-level imports from your .server.ts bridge work everywhere — no per-handler dynamic imports, no special handling.

// src/auth.functions.ts
import { createServerFn } from '@tanstack/react-start'
import { redirectWithSuccess } from './flash-toast-bridge.server'

export const loginFn = createServerFn({ method: 'POST' }).handler(async () => {
  await myAuth.signIn(/* ... */)
  return redirectWithSuccess('/dashboard', 'Welcome back!')
})

Or stage without redirecting:

import { setFlashToast } from './flash-toast-bridge.server'

// ...inside any server fn handler:
await setFlashToast({ message: 'Saved', type: 'success' })
return data

6. Trigger from a full navigation

Flash toasts work via a cookie set on one response and read on the next request. That two-request handshake means the trigger has to be a full page navigation — not a client-side router transition.

The patterns that already are full navigations:

HTML form submissions (login, signup, settings save, etc.)
OAuth callback redirects
Email verification link clicks
Sign-out forms

If you trigger a redirectWith* from a client-side <Link> click or a useMutation callback, the destination loader's consume-fetch races the browser's cookie commit and the toast is silently dropped — no error, just nothing. The user clicks, sees the destination page, never knows a toast was meant to fire. For client-side actions, fire your toast UI directly in the mutation's onSuccess — toast.success('Saved') straight to sonner, no cookie involved. The cookie bridge exists for full-navigation flows; if your trigger is already in client land, you don't need it.

<!-- ✅ Form submission — full navigation, cookie commits, toast fires -->
<form method="POST" action="/login">...</form>

// ✅ Client mutation — fire your toast UI directly, no cookie bridge
const mutation = useMutation({
  mutationFn: () => loginFn({ data }),
  onSuccess: () => toast.success('Welcome back!'),
})

// ❌ <Link> through a redirect-throwing loader — toast silently dropped
<Link to="/trigger">Go</Link>

The example app's index page is a form submission to demonstrate the cookie-bridge path exactly.

API reference

`/server` (server-only)

Export	Signature	Notes
`setFlashToast`	`(input: FlashToastInput, defaultType?: FlashToastType) => Promise<void>`	Stage a toast on the response cookie. Last write wins.
`consumeFlashToast`	`() => Promise<FlashToast \| null>`	Read + clear the staged toast. Returns `null` if none.
`setFlashCookieOptions`	`(opts: FlashCookieOptions) => void`	Override defaults: `name`, `maxAge`, `secret`, `path`, `sameSite`, `secure`, `httpOnly`.
`redirectWithToast`	`(href: string, input: FlashToastInput) => Promise<never>`	Stage + `throw redirect(href)`. Defaults `type: 'info'`.
`redirectWithSuccess`	same	Defaults `type: 'success'`.
`redirectWithError`	same	Defaults `type: 'error'`.
`redirectWithInfo`	same	Defaults `type: 'info'`.
`redirectWithWarning`	same	Defaults `type: 'warning'`.
`replaceWith*` (5 of)	`(href, input) => Promise<never>`	Same as `redirectWith*` but `replace: true` — back button skips the trigger page.

Root entry (client-safe)

Export	Signature	Notes
`<FlashToastEffect>`	`{ toast: FlashToast \| null, notify: (t: FlashToast) => void }`	Effect-only renderer. Dedupes by `_id` in `sessionStorage`.
`<ToastProvider>`	`{ toaster, toast, notify, children }`	Composes `<Toaster>` + `<FlashToastEffect>` in safe source order.
`FlashToast` (type)	`{ message, type, _id, description?, duration? }`	The wire format.
`FlashToastInput`	`string \| { message, type?, description?, duration? }`	What `setFlashToast` and `redirectWith*` accept.
`FlashToastType`	`'info' \| 'success' \| 'error' \| 'warning'`

Why a `.server.ts` re-export?

A direct top-level import from react-start-toast/server from a route file or root layout — e.g. import { consumeFlashToast } from 'react-start-toast/server' at the top of __root.tsx — crashes the production build with:

[plugin vite:resolve] Module "node:async_hooks" has been externalized for browser compatibility,
imported by ".../start-server-core/.../request-response.js"

Reason: route files don't go through TanStack Start's server-fn handler-stripping transform, so any top-level import is just a regular module import. react-start-toast/server transitively imports h3 (getCookie/setCookie), which transitively imports node:async_hooks. The whole chain ends up in the client graph and Vite refuses to bundle the Node-only module.

The same import inside a server-fn module (*.functions.ts) sometimes works because TSS's compile-time transform replaces the handler body with a fetch wrapper — and if the only reference to the imported binding is inside that body, the import gets tree-shaken on the client. But that's a fragile guarantee: a single component-level reference to the binding, or a different file shape, breaks it. Empirically we've seen leaks from non-route files too.

The .server.ts extension on a local re-export file fixes this categorically: TSS's import-protection plugin matches the **/*.server.* glob and tells Vite to externalize the module from client bundles entirely, regardless of what file imports it or how. Your other files import from the bridge with normal top-level import statements — the boundary is enforced by the .server.ts filename, not by per-call-site discipline or per-file luck.

The example app includes a Playwright bundle-leak guard that fails CI if AsyncLocalStorage (or any other server-only marker) ever appears in a client asset. Worth copying if you publish your own consumer of this lib.

Alternative — dynamic import inside the handler. If you can't use a .server.ts filename for some reason (custom build configs, restricted file naming), you can move the import inside the server-fn handler body where it becomes part of the dead body the transform removes:
.handler(async () => {
  const { consumeFlashToast } = await import('react-start-toast/server')
  return consumeFlashToast()
})
Works, but you pay the ceremony at every call site. The .server.ts re-export is the recommended pattern.

Source-order constraint

Subscribe-on-mount toast UIs (sonner, react-toastify, sonner-react, custom) buffer events that arrive before they've subscribed but don't replay them. React commits sibling effects in source order, so:

// ✅ Correct — toaster mounts first, subscribes, then the bridge fires
<Toaster />
<FlashToastEffect toast={t} notify={notify} />

// ❌ Wrong — bridge fires before toaster subscribes; toast is silently dropped
<FlashToastEffect toast={t} notify={notify} />
<Toaster />

<ToastProvider> bakes the correct order in. Reach for <FlashToastEffect> directly only if you need explicit control.

Example app

A working end-to-end example lives in examples/react/basic:

One flash-toast-bridge.server.ts re-export, two thin *.functions.ts files, top-level imports throughout
All 10 helpers exercised through real navigation (HTML form submission)
Playwright e2e suite (12 tests) verifying every helper through SSR + hydration + DOM assertions, plus a bundle-leak guard that fails CI if any client asset references AsyncLocalStorage

cd examples/react/basic
pnpm install
START_TOAST_SECRET=$(openssl rand -hex 32) pnpm dev

Package

Published as a single package on npm: react-start-toast. The repo also contains a start-toast-core workspace-internal package — the framework-agnostic primitives (schema, seal/unseal, ID gen) — but it is bundled into the React adapter at build time and is not published independently. Future framework adapters (Solid, etc.) would do the same: depend on start-toast-core via the workspace, bundle it into their own tarball.

Get involved

File issues at github.com/stevan-borus/start-toast/issues
Open a PR — see docs/adr/0001-roadmap.md for the design target before adding new exports

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

start-toast

Features

Install

Setup

1. Set the cookie secret

2. Add a `.server.ts` re-export

3. Define a local server fn that reads the cookie

4. Wire the renderer in `__root.tsx`

5. Stage toasts from server fns

6. Trigger from a full navigation

API reference

`/server` (server-only)

Root entry (client-safe)

Why a `.server.ts` re-export?

Source-order constraint

Example app

Package

Get involved

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

start-toast

Features

Install

Setup

1. Set the cookie secret

2. Add a .server.ts re-export

3. Define a local server fn that reads the cookie

4. Wire the renderer in __root.tsx

5. Stage toasts from server fns

6. Trigger from a full navigation

API reference

/server (server-only)

Root entry (client-safe)

Why a .server.ts re-export?

Source-order constraint

Example app

Package

Get involved

License

2. Add a `.server.ts` re-export

4. Wire the renderer in `__root.tsx`

`/server` (server-only)

Why a `.server.ts` re-export?