Icons in SvelteKit

Installation

npm install glyphfox

Es gibt nichts zu konfigurieren. glyphfox/svelte wird unter der Export-Condition svelte bereitgestellt. Daher erkennt vite-plugin-svelte, das jedes SvelteKit-Projekt verwendet, das Paket als Svelte-Bibliothek und kompiliert seine Komponenten für Server und Browser. Die Komponenten setzen Svelte 5 voraus; die Svelte-Anleitung behandelt Komponenten und Props im Detail.

Icon-Namen im Root-Layout registrieren

Komponenten wie HomeIcon registrieren ihre Daten selbst. Namen, die nur in Strings vorkommen, also in Icon, Fusion, MorphIcon oder morphTo, benötigen registerIcons. Der beste Ort dafür ist ein Modul, das das Root-Layout importiert: Es läuft auf dem Server vor dem ersten Rendering und im Browser vor der Hydration.

import { registerIcons } from 'glyphfox/svelte';
import menu from 'glyphfox/icons/menu';
import x from 'glyphfox/icons/x';
import moon from 'glyphfox/icons/moon';
import file from 'glyphfox/icons/file';

registerIcons([menu, x, moon, file]);

<script>
  import '$lib/icons.js';
  import { MorphIcon } from 'glyphfox/svelte';

  let { children } = $props();
  let open = $state(false);
</script>

<header>
  <button type="button" aria-label="Menu" aria-expanded={open} onclick={() => (open = !open)}>
    <MorphIcon name={open ? 'x' : 'menu'} />
  </button>
</header>

{@render children()}

Die Registry ist Modulzustand. Auf dem Server wird sie von allen Anfragen geteilt, was unbedenklich ist, weil sich Icon-Daten nie ändern, und sie wird einmalig befüllt, wenn das Modul zum ersten Mal geladen wird.

Was der Server rendert

Icon-Komponenten erzeugen beim serverseitigen Rendering ihr vollständiges SVG. Die Animationen lebendiger Zustände sind ein Stylesheet im SVG, daher dreht sich ein Spinner bereits im Server-HTML, es sei denn, Besucher bevorzugen reduzierte Bewegung. Morphs sowie die Auslöser für Klick und Hover starten erst nach der Hydration, weil $effect nicht auf dem Server läuft.

Für einen Morph, bei dem Daten bestimmen, an welchem Ende er steht, verwenden Sie trigger="state" mit active. Der Server rendert das passende Ende des Morphs, und die Animation läuft nur, wenn sich der Wert im Browser ändert. Mit dem Standardauslöser (mount) rendert der Server das Ausgangs-Icon, und das Morphing läuft bei jedem Seitenaufruf ab.

export function load({ cookies }) {
  return { theme: cookies.get('theme') ?? 'light' };
}

<script>
  import { SunIcon } from 'glyphfox/svelte';

  let { theme } = $props();
  let dark = $state(theme === 'dark');

  function toggle() {
    dark = !dark;
    document.cookie = `theme=${dark ? 'dark' : 'light'}; path=/; max-age=31536000`;
  }
</script>

<button type="button" aria-label="Dark theme" aria-pressed={dark} onclick={toggle}>
  <SunIcon morphTo="moon" trigger="state" active={dark} />
</button>

Wenn Sie das Theme in einer serverseitigen Load-Funktion aus einem Cookie lesen, starten Server und Browser mit demselben Wert. Rendern Sie den Umschalter im Root-Layout mit <ThemeToggle theme={data.theme} />; moon ist in src/lib/icons.js registriert.

SVG-Dateien aus einem Endpunkt

toSvg aus dem Haupteinstiegspunkt glyphfox rendert jede Spezifikation zu einem String. Damit lässt sich eine +server.js-Route anlegen, die Icons als Dateien ausliefert: ein Favicon, ein Bild für ein E-Mail-Template oder eine Linkvorschau. Mit entries werden die Dateien zur Build-Zeit vorgerendert.

import { error } from '@sveltejs/kit';
import { iconNames, toSvg } from 'glyphfox';

export const prerender = true;

export function entries() {
  return ['fox', 'home', 'search'].map((name) => ({ name }));
}

export function GET({ params }) {
  if (!iconNames.includes(params.name)) error(404, 'Unknown icon');
  const svg = toSvg(params.name, { size: 32, color: '#ff7a1a', variant: 'duotone' });
  return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
}

<link rel="icon" href="/icons/fox.svg" type="image/svg+xml" />

Eine eigenständige SVG-Datei hat kein Elternelement, von dem sie eine Farbe erben könnte. Übergeben Sie daher color: Der Wert wird am svg-Element gesetzt, und die Striche mit currentColor übernehmen ihn. Damit jedes Icon vorgerendert wird, lassen Sie entries den Ausdruck iconNames.map((name) => ({ name })) zurückgeben.

Der Haupteinstiegspunkt enthält die Daten aller Icons. In +server.js- und +page.server.js-Dateien, die nie den Browser erreichen, ist das unproblematisch; in eine Komponente importiert, würde toSvg das gesamte Set an den Client ausliefern.

Rein serverseitiges Markup mit {@html}

Eine Load-Funktion in +page.server.js kann gerenderte Strings zurückgeben, die die Seite mit {@html} einfügt. Der Browser erhält das Markup im HTML und in den serialisierten Seitendaten, aber keinen Icon-Code.

import { toSvg } from 'glyphfox';

const features = [
  { icon: 'zap', title: 'Fast' },
  { icon: 'shield-check', title: 'Safe' },
  { icon: 'accessibility', title: 'Accessible' },
];

export function load() {
  return {
    features: features.map((f) => ({ ...f, svg: toSvg(f.icon, { size: 28, weight: 1.5 }) })),
  };
}

<script>
  let { data } = $props();
</script>

<ul class="features">
  {#each data.features as feature (feature.icon)}
    <li>{@html feature.svg} {feature.title}</li>
  {/each}
</ul>

{@html} ist hier sicher, weil die Strings aus Ihrem eigenen Servercode stammen und nie aus Benutzereingaben. Ohne title werden die Icons mit aria-hidden gerendert, was neben einer sichtbaren Beschriftung genau richtig ist.

adapter-static und Prerendering

Mit adapter-static oder mit export const prerender = true in einer beliebigen Route werden Seiten zur Build-Zeit gerendert und die Icons in die HTML-Dateien geschrieben. Die Regeln des serverseitigen Renderings gelten auch zur Build-Zeit: Ein Name, den der Build nicht auflösen kann, wird als leeres SVG geschrieben.

import adapter from '@sveltejs/adapter-static';

export default {
  kit: { adapter: adapter() },
};

export const prerender = true;

Für Seiten, die kein JavaScript benötigen, ergänzen Sie export const csr = false: Die Icons bleiben statisches SVG, und es wird kein Komponentencode übertragen. CSS-Animationen laufen weiterhin, Morphs und die Auslöser für Klick oder Hover hingegen, die JavaScript benötigen, bewirken nichts.

Namen in Produktions-Builds

In der Entwicklung bündelt Vite das Paket vorab, daher scheint jeder Name zu funktionieren. Im Produktions-Build bündelt Vite den On-Demand-Loader nicht, den glyphfox in node_modules mitbringt, weil Vite dynamische Importe mit Variablen in Abhängigkeiten überspringt, und nicht registrierte Namen bleiben leer. Registrieren Sie diese Namen, oder lassen Sie Vite den Loader bündeln, der dann pro Icon einen kleinen Chunk erzeugt:

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit()],
  build: {
    dynamicImportVarsOptions: { exclude: [/node_modules\/(?!glyphfox\/)/] },
  },
});

Diese Chunks helfen nur im Browser nach der Hydration. Das serverseitige Rendering wartet nicht auf sie, daher bleibt die Registrierung der Weg, ein Icon ins HTML zu bringen.

Props

SvelteKit verwendet die Komponenten aus glyphfox/svelte, daher gelten die gemeinsamen Props in camelCase.

Stolperfallen

Registrierung in onMount oder in reinem Browser-Code

Code in onMount, in $effect oder hinter if (browser) läuft erst, nachdem der Server gerendert hat. Das HTML enthält dann leere Icons, die erst nach der Hydration auftauchen. Registrieren Sie in einem Modul, das das Root-Layout importiert.

Ein anderes Icon auf dem Server als im Browser

Der Inhalt des svg-Elements wird mit {@html} eingefügt, und Svelte behält das Server-Markup eines {@html}-Blocks bei, wenn das erste Rendering im Client davon abweicht (in der Entwicklung warnt Svelte dann mit hydration_html_changed). Ein Icon, das anhand von localStorage oder window gewählt wird, kann daher bis zur nächsten Änderung falsch bleiben. Leiten Sie den ersten Wert aus Daten ab, die auch der Server hat, etwa aus einem Cookie, das in einer Load-Funktion gelesen wird.

toSvg in einer universellen Komponente

Wenn Sie toSvg aus glyphfox in einer .svelte-Datei importieren, gelangen die Daten aller Icons ins Client-Bundle. Verwenden Sie es nur in Server-Dateien, oder greifen Sie auf die Komponenten zurück.

Ein vorgerenderter Morph im falschen Zustand

Mit dem Auslöser mount zeigt das vorgerenderte HTML das Ausgangs-Icon, und das Morphing läuft nach der Hydration ab. Verwenden Sie trigger="state" für alles, was in seinem Endzustand vorgerendert werden soll.