sveltekit-flash-message

When using the browser fetch API instead of SvelteKit's built-in form handling, the flash message store will not update automatically. You must call updateFlash(page) after the fetch completes to sync the state.

<script lang="ts">
  import { updateFlash } from 'sveltekit-flash-message';
  import { page } from '$app/state';

  async function submitForm(e: Event) {
    const form = e.target as HTMLFormElement;
    const body = new FormData(form);

    await fetch(form.action, { method: 'POST', body });
    await updateFlash(page);
  }
</script>

<form method="POST" action="/test" on:submit|preventDefault={submitForm}>
  <button>Submit with fetch</button>
</form>

Install the library as a development dependency using pnpm or npm.

pnpm i -D sveltekit-flash-message
# or
npm i -D sveltekit-flash-message

To enable flash messages, you must wrap your top-level load function in src/routes/+layout.server.ts.

If you don't have a load function, simply export the library's load: export { load } from 'sveltekit-flash-message/server';.

If you already have a load function, wrap it using loadFlash:

Note: Do not call load or loadFlash in any child routes, as the flash cookie is deleted immediately upon its first discovery in the top-level load function.

// src/routes/+layout.server.ts
import { loadFlash } from 'sveltekit-flash-message/server';

export const load = loadFlash(async (event) => {
  const data = { someOther: 'data' };
  return data;
});

In src/app.d.ts, add the flash property to the App.PageData interface. The flash message must be a serializable, JSON-friendly data structure. You can use a simple string or a more complex object like { type: 'success' | 'error'; message: string }.

// src/app.d.ts
declare global {
  namespace App {
    interface PageData {
      flash?: { type: 'success' | 'error'; message: string };
    }
  }
}

export {};

If you are upgrading from version 1.x to 2.x, you must apply the following breaking changes:

1. Rename Functions

• Replace loadFlashMessage with loadFlash.
• initFlash is now primarily used for configuration; you can use getFlash directly in most scenarios.

2. Automatic Navigation Clearing

• The manual beforeNavigate snippet used to clear flash messages after navigation is no longer required. Clearing is now automatic.
• To prevent automatic clearing on navigation, set the clearOnNavigate option to false.

3. Time-based Clearing

• If you previously used a custom snippet to clear messages after a specific duration, remove it and use the clearAfterMs option instead.

The FlashRouter class is responsible for managing the mapping between route IDs and FlashMessage instances. It allows you to associate specific flash messages with specific URL paths or patterns.

Key behaviors:

• Default Route: If no specific route matches, the router falls back to a default route (identified by an empty string '').
• Route Matching: When retrieving a message for a routeId, the router attempts to find an exact match. If no exact match exists, it uses getClosestRoute to find the longest matching prefix among registered routes.
• Lifecycle Management: The router automatically clears any active flash message timeouts when it is destroyed.

To treat flash messages as transient events (like toasts) rather than static page content, use an $effect to trigger a toast library and then clear the flash store.

<script>
  import { getFlash } from 'sveltekit-flash-message';
  import { page } from '$app/state';
  import toast from 'svelte-french-toast';

  const flash = getFlash(page);

  $effect(() => {
    if (!$flash) return;

    toast($flash.message, {
      icon: $flash.type == 'success' ? '✅' : '❌'
    });

    // Clear the flash message to avoid double-toasting.
    $flash = undefined;
  });
</script>

You can send flash messages from server-side load functions, form actions, or endpoints using redirect or setFlash from sveltekit-flash-message/server.

import { redirect } from 'sveltekit-flash-message/server';

// Redirect with a specific location and message (303 redirect)
redirect('/', { type: 'success', message: 'Success!' }, cookies);

// Redirect with a specific status and location
redirect(302, '/login', { type: 'error', message: 'Session expired' }, cookies);

Use getFlash(page) to obtain a Svelte store containing the current flash message. You can then use the $ prefix to access the message in your markup or logic.

<script lang="ts">
  import { getFlash } from 'sveltekit-flash-message';
  import { page } from '$app/state';

  const flash = getFlash(page);
</script>

{#if $flash}
  <div class="flash">{$flash.message}</div>
{/if}

To display a flash message (e.g., for validation errors) without performing a redirect, use setFlash from sveltekit-flash-message/server inside a form action.

import { fail } from '@sveltejs/kit';
import { setFlash } from 'sveltekit-flash-message/server';

export const actions = {
  default: async ({ request, cookies }) => {
    const form = await request.formData();
    if (!form.get('text')) {
      setFlash({ type: 'error', message: 'Please enter text.' }, cookies);
      return fail(400);
    }
  }
};