hirogakatageri/svelte-advanced

Svelte 5 — Advanced Techniques

For tasks that go beyond standard component work: animation, DOM integration, packaging, advanced server flows, and PWA features.

Transitions

Apply enter/exit animations to elements that conditionally render.

<script>
  import { fade, fly, slide, scale, blur, draw, crossfade } from 'svelte/transition';
  let visible = $state(true);
</script>

{#if visible}
  <div transition:fade={{ duration: 300 }}>fades both in and out</div>
{/if}

{#if visible}
  <div in:fly={{ y: 20, duration: 200 }} out:fade>independent in/out</div>
{/if}

Built-ins: fade, fly, slide, scale, blur, draw (SVG path), crossfade (paired enter/exit between elements).

A custom transition is a function returning a config:

import { cubicOut } from 'svelte/easing';

export function spin(node: Element, { duration = 400 }) {
  return {
    duration,
    easing: cubicOut,
    css: (t) => `transform: rotate(${t * 360}deg); opacity: ${t}`
  };
}

css runs as a CSS keyframe animation (best perf). Use tick(t, u) for frame-by-frame JS work when CSS isn't enough.

Transitions are local by default (don't play when a parent block toggles). Use transition:fade|global to opt in.

Animations (animate:)

Smoothly reorder items inside a keyed {#each} block.

<script>
  import { flip } from 'svelte/animate';
  let items = $state([...]);
</script>

{#each items as item (item.id)}
  <li animate:flip={{ duration: 300 }}>{item.text}</li>
{/each}

flip (First-Last-Invert-Play) is the standard. Required: the (item.id) key — otherwise Svelte can't track identity through reorders.

Motion Module

svelte/motion provides spring and tween primitives:

<script>
  import { Spring, Tween } from 'svelte/motion';

  const x = new Spring(0, { stiffness: 0.1, damping: 0.4 });
  const opacity = new Tween(1, { duration: 300 });
</script>

<button onclick={() => { x.target = 200; opacity.target = 0; }}>animate</button>
<div style:transform="translateX({x.current}px)" style:opacity={opacity.current}>...</div>

Use prefers-reduced-motion (import { prefersReducedMotion } from 'svelte/motion') and respect it.

Actions (use:)

Functions that run when an element mounts and (optionally) clean up on destroy.

// tooltip.ts
import type { Action } from 'svelte/action';

export const tooltip: Action<HTMLElement, string> = (node, text) => {
  const tip = document.createElement('div');
  tip.textContent = text ?? '';
  // ... attach, position, listen
  return {
    update: (newText) => { tip.textContent = newText ?? ''; },
    destroy: () => { tip.remove(); }
  };
};

<button use:tooltip={'Hello'}>?</button>

For library code in Svelte 5, prefer attachments (next section) — they compose better with snippets and props spreading.

Attachments ({@attach})

Svelte 5's evolution of use:. An attachment is a function that runs on the element after mount.

<script lang="ts">
  import type { Attachment } from 'svelte/attachments';

  const focusOnMount: Attachment = (element) => {
    (element as HTMLElement).focus();
    return () => { /* cleanup if needed */ };
  };
</script>

<input {@attach focusOnMount} />

Attachments can be passed as props and spread, unlike actions. They're the recommended pattern for library authors and any new DOM-integration code in Svelte 5.

Custom Elements (Web Components)

Compile a Svelte component into a real custom element:

<svelte:options customElement="my-counter" />

<script lang="ts">
  let { count = 0 }: { count?: number } = $props();
</script>

<button onclick={() => count++}>{count}</button>

Register globally by importing the file. Inside the element, use $host() to access the host element (useful for dispatchEvent).

For library mode, opt into custom-element output in svelte.config.js via compilerOptions.customElement: true, or use <svelte:options customElement="..." /> per file.

Packaging Libraries

@sveltejs/package produces a publishable package from src/lib/:

npm run package    # → outputs to /dist with .d.ts and svelte field

package.json should expose:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "svelte": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "svelte": "./dist/index.js"
}

Don't bundle Svelte source when publishing — keep .svelte files intact so consumers' compilers can process them.

SvelteKit Hooks (Deep Dive)

Hooks live in src/hooks.server.ts, src/hooks.client.ts, and src/hooks.ts.

handle (server)

Wraps every request. Use for auth, locals population, response headers.

import { sequence } from '@sveltejs/kit/hooks';
import type { Handle } from '@sveltejs/kit';

const auth: Handle = async ({ event, resolve }) => {
  event.locals.user = await getUserFromCookie(event.cookies);
  return resolve(event);
};

const securityHeaders: Handle = async ({ event, resolve }) => {
  const response = await resolve(event);
  response.headers.set('content-security-policy', "default-src 'self'");
  return response;
};

export const handle = sequence(auth, securityHeaders);

resolve(event, opts) accepts:

• transformPageChunk: ({ html }) => html.replace('%lang%', lang) — mutate HTML chunks during streaming.
• filterSerializedResponseHeaders: (name) => true — control which fetch response headers get inlined into SSR HTML.
• preload: ({ type, path }) => true — control which assets get <link rel="modulepreload">.

handleError (server + client)

Catches uncaught errors. Don't redirect or rethrow here — return a serializable error object that becomes page.error.

export const handleError: HandleServerError = ({ error, event, status }) => {
  console.error(error);
  return { message: 'Something went wrong', code: 'UNEXPECTED' };
};

handleFetch (server)

Modifies the fetch provided to load functions.

export const handleFetch: HandleFetch = async ({ event, request, fetch }) => {
  if (request.url.startsWith('https://api.internal/')) {
    request.headers.set('cookie', event.request.headers.get('cookie') ?? '');
  }
  return fetch(request);
};

transport (universal hook in src/hooks.ts)

Custom de/serialization for types beyond devalue's defaults — e.g., Decimal, custom domain classes — so they survive the server→client trip.

Remote Functions

Type-safe RPC between client and server, defined once and callable from components:

// src/routes/posts.remote.ts
import { query, command, form } from '$app/server';
import * as v from 'valibot';
import * as db from '$lib/server/database';

export const getPost = query(v.string(), async (slug) => {
  return await db.getPost(slug);
});

export const likePost = command(v.string(), async (slug) => {
  await db.incrementLikes(slug);
  return { ok: true };
});

export const submitComment = form(
  v.object({ slug: v.string(), text: v.string() }),
  async ({ slug, text }) => {
    await db.addComment(slug, text);
  }
);

<script lang="ts">
  import { getPost, likePost } from './posts.remote';
  let { params } = $props();
  const post = $derived(await getPost(params.slug));
</script>

<h1>{post.title}</h1>
<button onclick={() => likePost(params.slug)}>Like</button>

• query() — read; cached, dedupes, integrates with await in components.
• command() — write; invalidates affected queries.
• form() — <form>-driven mutation; works without JS.
• The validator (e.g. valibot, zod) gates all input.

Enable in svelte.config.js:

kit: { experimental: { remoteFunctions: true } }

(Once stabilized, no flag needed — check the project's SvelteKit version.)

Shallow Routing

Push history entries without changing the page — useful for modal dialogs, image lightboxes, drawer menus that should be back-button-friendly.

<script lang="ts">
  import { pushState } from '$app/navigation';
  import { page } from '$app/state';
</script>

<a
  href="/photos/42"
  onclick={(e) => {
    if (innerWidth < 640) return;       // mobile: full nav
    e.preventDefault();
    pushState('', { showModal: true });
  }}
>
  View
</a>

{#if page.state.showModal}
  <Modal onclose={() => history.back()}>...</Modal>
{/if}

pushState(href, state) and replaceState(href, state) from $app/navigation. Read the state from page.state (typed via App.PageState).

Service Workers

src/service-worker.ts is built and registered automatically. The $service-worker virtual module provides build assets:

/// <reference types="@sveltejs/kit" />
import { build, files, version } from '$service-worker';

const CACHE = `cache-${version}`;
const ASSETS = [...build, ...files];

self.addEventListener('install', (e) =>
  (e as ExtendableEvent).waitUntil(
    caches.open(CACHE).then((c) => c.addAll(ASSETS))
  )
);

self.addEventListener('activate', (e) =>
  (e as ExtendableEvent).waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k)))
    )
  )
);

self.addEventListener('fetch', (e) => {
  // strategy of choice (cache-first, network-first, stale-while-revalidate)
});

Disable via kit.serviceWorker.register = false in svelte.config.js if you want manual control.

View Transitions

Use the View Transitions API for cross-page animations:

// hooks.client.ts
import { onNavigate } from '$app/navigation';

onNavigate((nav) => {
  if (!('startViewTransition' in document)) return;
  return new Promise((resolve) => {
    document.startViewTransition(async () => {
      resolve();
      await nav.complete;
    });
  });
});

CSS view-transition-name: ... per element controls the morph.

<svelte:boundary>

Error and async boundaries inside a component:

<svelte:boundary>
  <FlakyComponent />

  {#snippet failed(error, reset)}
    <p>Something broke: {error.message}</p>
    <button onclick={reset}>Try again</button>
  {/snippet}

  {#snippet pending()}
    <p>Loading…</p>
  {/snippet}
</svelte:boundary>

The pending snippet is shown while async work inside the boundary is unresolved (paired with await expressions in templates). The failed snippet renders on error and receives a reset() to re-run the children.

Special Elements

• <svelte:window>, <svelte:document>, <svelte:body> — bind global events without manual addEventListener.
• <svelte:head> — inject into <head>.
• <svelte:element this={tag}> — render a tag chosen at runtime.
• <svelte:options> — per-component compiler options (customElement, runes, accessors, namespace).
• <svelte:self> — recursive component reference (e.g., for tree views).

Reactive Built-ins

svelte/reactivity exports proxy-aware Map, Set, Date, URL, URLSearchParams. Use these instead of the native versions when you want their state mutations to be tracked:

import { SvelteMap, SvelteSet, SvelteDate, SvelteURL } from 'svelte/reactivity';

const selected = new SvelteSet<string>();
selected.add('foo');                 // triggers reactivity

svelte/reactivity/window exposes reactive window properties (innerWidth, innerHeight, scrollX, etc.) so you don't need to wire up listeners manually.