astro-svelte

---
name: astro-svelte
description: Use Svelte in Astro islands — integration setup, .svelte components, props and slots, stores, and Svelte 5 runes considerations. Use when adding Svelte components to an Astro project or debugging Svelte islands.
license: Apache-2.0
---

# Astro Svelte

## Purpose

Integrate Svelte components into Astro as islands: setup, props/slots, compile-time reactivity, stores, and Svelte-version considerations.

## When to Use

Activate when the task involves:

- adding Svelte to an Astro project
- `.svelte` components used from `.astro`
- Svelte props, slots, stores, or runes inside islands
- debugging Svelte islands

## When Not to Use

Do not use this skill for:

- framework selection — see `astro-ui-framework-selection`
- hydration directives — see `astro-islands`
- generic Svelte app development

## Core Workflow

1. Install: `npx astro add svelte`.
2. Write `.svelte` components; use from `.astro` with `client:*` directives.
3. Pass serializable props; slots for composition (named slots map to Svelte slots).
4. Use stores (or runes in Svelte 5) for state inside the island.
5. Verify hydration in production output.

## Decision Rules

- Svelte compiles away most runtime — small islands by default.
- Svelte 5 uses runes (`$state`, `$props`, `$derived`); Svelte 4 uses `export let` props and stores — match the installed version's syntax.
- Stores can be shared across islands in the same way as signals (framework-agnostic module state) — see `astro-islands` shared-state patterns.
- Props and slots cross the boundary as serializable values/markup only.

## Common Patterns

- **Lightweight widgets:** menus, counters, toggles — compile-time reactivity keeps bundles small.
- **Stores for shared client state** across a few islands.
- **Animations inside islands** where Svelte transitions shine.

## Anti-Patterns

- Svelte for static content.
- Runes syntax on Svelte 4 (or legacy syntax on Svelte 5) — version-aware authoring required.
- Store modules that mutate server-side state (import-time side effects).

## Edge Cases

- **Hydration mismatch:** Svelte's `{#if}` and stores must render deterministically server and client.
- **SSR of browser-only APIs:** guard or use `client:only="svelte"`.
- **Svelte version vs integration:** pin compatible versions (`astro-version-awareness`).
- **Accessibility warnings:** Svelte warns on a11y issues at compile time — treat them as errors.

## Verification

1. `astro check` passes.
2. Production build hydrates islands; markup matches between server and client.
3. Console clean; interactions, slots, and stores work.
4. Bundle size measured (compile-time framework = small runtime).