cachesdev/svelte-deep-knowledge

Conocimiento profundo de Svelte

Úsalo como un índice de posibles brechas de conocimiento. Verifica las APIs relevantes contra el MCP oficial de Svelte durante la planificación e implementación.

Verificado el 2026-11-01 contra Svelte 5.57.3, SvelteKit 3.1.1 y SvelteKit 2.70.3.

Comienza con las versiones instaladas

1. Inspecciona las versiones de los paquetes y la configuración de Vite. Haz coincidir la guía con la versión mayor de Kit instalada y los indicadores experimentales habilitados.
2. Llama a list-sections del MCP de Svelte, luego obtén las secciones relevantes junto con get-documentation. El MCP y svelte.dev sirven documentación de Kit 3. Para un proyecto de Kit 2, lee la página correspondiente de la rama version-2 de sveltejs/kit en documentation/docs.
3. Para proyectos de Kit 3 y migraciones de Kit 2 → 3, lee la referencia de Kit 3. Para proyectos de Kit 2, lee la referencia de Kit 2.
4. Ejecuta svelte-autofixer en los componentes/módulos Svelte nuevos o editados y resuelve los hallazgos aplicables. Usa las verificaciones del proyecto para integración y tipos.

Para ejemplos de nuevas APIs de Svelte, renderizado asíncrono, adjuntos y herramientas del compilador, lee la referencia de Svelte.

Funciones remotas, límites y await

Para aplicaciones nuevas de SvelteKit que adopten async experimental, prefiere funciones remotas con await directo para los datos de los componentes y límites granulares para la UI de carga/error. Elige la ubicación de svelte:boundary según lo que deba renderizarse en el servidor.

• Habilita experimental.remoteFunctions y compilerOptions.experimental.async juntos. La configuración oficial de funciones remotas requiere ambos indicadores.
• load, acciones de formulario y rutas +server siguen siendo compatibles pero no recomendados. Sigue la arquitectura existente a menos que la tarea incluya migración.
• .loading, .error y .current siguen siendo APIs de consulta compatibles. await directo es el mecanismo preferido.
• Usa await query(args) en contextos de renderizado e imperativos.
• {#await} sigue siendo compatible aunque no recomendado, y tiene su propio comportamiento de estado de promesa. Usa await directo y límites para renderizado asíncrono coordinado; conserva {#await} cuando su comportamiento se ajuste a la tarea.

Verifica con las secciones del MCP kit/remote-functions, svelte/await-expressions y svelte/svelte-boundary.

Comportamiento del renderizado asíncrono

• El await a nivel de componente llegó en Svelte 5.36; SSR asíncrono llegó en 5.39. Await es compatible en el script de nivel superior, $derived y el marcado.
• Svelte coordina las actualizaciones de UI dependientes mientras el trabajo asíncrono se resuelve. Las expresiones await independientes en plantilla se ejecutan concurrentemente. Los awaits secuenciales en script aún crean cascadas; inicia el trabajo independiente antes de esperar sus resultados.
• El fragmento pending de un límite aparece en la creación inicial. Usa $effect.pending() para trabajo posterior en ese límite; su recuento excluye límites hijos.
• Durante SSR, un límite con pending renderiza el marcador de posición y omite su contenido. Las expresiones await fuera de dichos límites se resuelven antes de que await render(...) se complete. Coloca el contenido necesario en el HTML inicial en consecuencia. Esta API aún no proporciona SSR con stream.
• $state.eager(value), añadido en 5.41, expone retroalimentación inmediata mientras las actualizaciones coordinadas esperan. Úsalo para retroalimentación del usuario, como un indicador de navegación activa.
• tick() espera cambios de estado pendientes; settled(), añadido en 5.36, también espera el trabajo asíncrono causado por ellos y las actualizaciones resultantes del DOM.

Límites de error

• <svelte:boundary> soporta failed(error, reset) y onerror(error, reset) para fallos de renderizado/efecto. Maneja errores de manejadores de eventos y asíncronos desconectados en sus sitios de llamada.
• Los fragmentos failed también capturan errores durante SSR, desde Svelte 5.53. En SvelteKit, el error pasa primero por handleError, por lo que el fragmento recibe el App.Error sanitizado. onerror se ejecuta cuando el límite fallido hidrata.
• Kit 3 envía errores de renderizado a través de handleError al +error.svelte más cercano, que actúa como un límite. Un handleError asíncrono de cliente necesita compilerOptions.experimental.async. Kit 2.54+ necesita experimental.handleRenderingErrors para la misma integración.
• La nota anterior "desde 5.51" en la documentación del límite entra en conflicto con el changelog publicado. Usa 5.53 como la versión de introducción y verifica los parches actuales al diagnosticar problemas de SSR/hidratación.

Características de plantilla

Tags de declaración, Svelte 5.56+

• Prefiere {let ...} y {const ...} para variables locales del marcado. {@const} está documentado como legado y sigue disponible para proyectos antiguos.
• Las declaraciones simples inicializan valores. Usa runas explícitas para reactividad: {let count = $state(0)} y {const doubled = $derived(count * 2)}.
• Migrar {@const area = width * height} reactivo requiere {const area = $derived(width * height)}. Un {const area = width * height} simple no es reactivo.
• Las declaraciones usan alcance léxico dentro de su elemento/bloque, pueden sombrear variables externas y deben preceder su uso. Se soportan múltiples declaradores.

Adjuntos

• Prefiere {@attach ...} para nuevas integraciones de elementos en Svelte 5.29+. Devuelve limpieza desde el adjunto.
• Los adjuntos rastrean lecturas reactivas y se vuelven a ejecutar cuando las dependencias cambian. Los valores falsos los deshabilitan. Evita repetir configuraciones costosas leyendo opciones cambiantes a través de un getter dentro de un efecto hijo.
• Los envoltorios de componentes deben reenviar props que contienen adjuntos al elemento previsto. createAttachmentKey() soporta adjuntos en objetos spread.
• fromAction(action, () => argument) conserva el comportamiento de una acción existente. Su segundo argumento es un getter. Este helper llegó en 5.32, después de los adjuntos mismos.

Clases, enlaces y HTML

• class acepta arrays y objetos anidados desde 5.16. ClassValue de svelte/elements está disponible desde 5.19 para props de envoltorio.
• Los enlaces de función usan bind:value={get, set} desde 5.9. Usa null como getter para enlaces de solo lectura.
• Las entradas numéricas pueden producir undefined cuando están vacías o son inválidas. El estado de checkbox puede usar bind:checked y bind:indeterminate; los grupos de radio usan bind:group.
• Las entradas soportan defaultValue/defaultChecked desde 5.6. Los selects soportan defaultValue desde 5.57, incluido el comportamiento de reinicio de formulario. Verifica la precedencia de enlaces al proporcionar valores predeterminados.
• Los selects nativos personalizables son compatibles desde 5.47. Verifica la compatibilidad del navegador y el patrón documentado <selectedcontent> antes de reemplazar un widget de select personalizado.
• Los comentarios estilo JavaScript entre atributos son válidos desde 5.53: <div /* explicación */ class="card">.
• {@html} acepta TrustedHTML desde 5.52. El soporte de Trusted Types no sanitiza entradas arbitrarias; usa una fuente confiable o una política de sanitización.

Bloques Each y fragmentos

• {#each items as { id, name }} desestructura items. La iteración de rango puede usar {#each { length: 8 }, index}.
• Prefiere claves de item estables para listas cuya identidad importa. Al editar un item, enlaza su propiedad a través del objeto item para que las mutaciones lleguen a la fuente.
• Los fragmentos se declaran en el marcado y se renderizan con {@render snippet(...)}. Los fragmentos de nivel superior pueden exportarse desde <script module> desde 5.5 si no capturan estado de instancia.
• Los fragmentos soportan genéricos desde 5.30. Los genéricos de componentes usan <script lang="ts" generics="T">.
• En modo runas, las variables de componente se renderizan dinámicamente como <Component />. Los componentes recursivos pueden importarse a sí mismos.

Runas y estado compartido

Estado y props

• $state.raw rastrea reasignaciones sin proxy profundo. Úsalo para valores grandes reemplazados como un todo. $state.snapshot extrae datos simples y respeta toJSON().
• Las instancias de clase no tienen proxy profundo. Usa campos $state, o su primera asignación en el constructor desde 5.31. Los campos reactivos se convierten en accesores no enumerables; conserva this al pasar métodos como callbacks.
• Pasar un valor reactivo a una función pasa su valor actual. Pasa un getter cuando la función necesite valores futuros. Desestructurar un proxy también lee los valores actuales.
• Usa .svelte.js/.svelte.ts para lógica de runas compartida. Exporta un objeto de estado estable o accesores cuando los consumidores necesiten estado cambiante; exportar directamente estado de runa reasignado está restringido.
• Limita el estado específico del usuario a través del contexto del componente durante SSR. El estado de módulo compartido puede filtrarse entre solicitudes.
• $props.id(), añadido en 5.20, proporciona un ID de instancia de componente que coincide entre SSR e hidratación.
• $bindable() declara una prop enlazable. Las props pueden reasignarse localmente; mutar el proxy no enlazable de un padre genera advertencias de propiedad. Los valores de respaldo no se proxy automáticamente.
• Mantén el tipo no inicializado real de $state<T>(), que incluye undefined, o proporciona un valor inicial válido. Usa estrechamiento en los sitios de acceso.

Derivados y efectos

• Usa $derived(expression) o $derived.by(fn) para valores calculados. Los derivados declarados con let pueden reasignarse para UI optimista desde 5.25; los cambios de dependencia los recalculan.
• Los valores $derived desestructurados permanecen reactivos. Los objetos devueltos no son proxies profundos automáticos. La igualdad referencial puede omitir trabajo downstream.
• Los efectos rastrean lecturas síncronas de su última ejecución. Las lecturas dentro de un callback asíncrono ordinario después de await no son dependencias automáticas.
• $effect se ejecuta en el navegador. Devuelve limpieza sincrónicamente; reserva efectos para sincronización externa y coloca el trabajo iniciado por el usuario en manejadores.
• $effect.tracking() detecta un contexto de seguimiento. $effect.root() crea un ámbito gestionado manualmente y devuelve un disposedor.
• getAbortSignal(), añadido en 5.35, debe ejecutarse dentro de un efecto o derivado. Su señal aborta en re-ejecución o destrucción. Úsalo para trabajo fetch propiedad de ese cómputo reactivo.
• untrack(fn) excluye lecturas del seguimiento de dependencias.
• $inspect(...).with(fn) recibe "init"/"update" seguido de valores. $inspect.trace(label?), añadido en 5.14, debe ser la primera sentencia en la función rastreada.
• $host() es para elementos personalizados y devuelve su elemento DOM anfitrión.

Módulos de tiempo de ejecución

• createContext<T>() proporciona contexto tipado desde 5.40. Desde 5.57 devuelve [get, set, has]; has() verifica disponibilidad antes de get(), que lanza cuando no está establecido. La búsqueda de contexto incluye el componente actual y los ancestros. Llama a los accesores de contexto durante la inicialización y establece el contexto antes del primer await en el script. Desde 5.57.1, un setContext posterior lanza set_context_after_init durante SSR.
• svelte/reactivity proporciona SvelteMap, SvelteSet, SvelteDate, SvelteURL y SvelteURLSearchParams. Las entradas de Map/Set no se hacen profundamente reactivas.
• Svelte 5.57 añade SvelteMap.getOrInsert(key, value) y getOrInsertComputed(key, key => value). El callback computado se ejecuta cuando la clave está ausente, incluido el manejo correcto de entradas undefined existentes.
• MediaQuery y createSubscriber llegaron en 5.7. Usa createSubscriber para conectar eventos externos a lecturas rastreadas con configuración y limpieza de suscripción compartida. MediaQuery acepta un fallback SSR; usa CSS cuando pueda expresar el mismo comportamiento.
• svelte/reactivity/window proporciona valores .current reactivos para dimensiones, posición de desplazamiento, estado en línea, posición de pantalla y relación de píxeles desde 5.11. Ten en cuenta los valores de ventana no disponibles durante SSR.
• on() de svelte/events conserva el orden con manejadores de eventos declarativos y devuelve limpieza. Usa <svelte:window>/<svelte:document> para escuchas globales declarativas.
• flushSync(fn?) vacía las actualizaciones pendientes sincrónicamente. createRawSnippet soporta marcado programático con configuración/limpieza. getAllContexts() proporciona el mapa de contexto actual para montaje programático; llámalo durante la inicialización.
• Spring y Tween de svelte/motion reemplazan los stores spring()/tweened() obsoletos desde 5.8. Ambos exponen .target, .current, .set() y .of(fn). Spring.set soporta preserveMomentum; prefersReducedMotion soporta movimiento accesible.
• Desde 5.55, las exportaciones de motion incluyen TweenOptions, SpringOptions, SpringUpdateOptions y Updater.
• hydratable(key, fn), añadido en 5.44, serializa datos para reutilización durante la hidratación. Usa devalue y soporta promesas anidadas. Las claves con espacios de nombres evitan colisiones. Las funciones remotas de Kit ya manejan esta capa.
• Con CSP, las integraciones SSR personalizadas deben configurar render con un nonce por respuesta o hashes estáticos y colocar valores coincidentes en los encabezados de respuesta. Svelte 5.46 añadió soporte CSP para render; 5.57 exporta RenderOutput, SyncRenderOutput, Csp y Sha256Source de svelte/server.
• Para herramientas, print() convierte un AST moderno de Svelte a fuente desde 5.45; parseCss() llegó en 5.48. Las opciones del compilador css, runes y customElement pueden ser funciones dependientes del nombre de archivo desde 5.54. Lee la referencia de Svelte antes de usar estas APIs.

SvelteKit

Las nuevas apps usan Kit 3 (npx sv create). Migra una app de Kit 2 con npx sv migrate sveltekit-3, luego trabaja a través de los TODOs generados. La guía de Kit 2 aplica solo a proyectos que permanezcan en 2.x.

Base de Kit 3

• Kit 3 requiere Node 22.17, TypeScript 6, Svelte 5.57.1, Vite 8.0.12 y vite-plugin-svelte 7.
• La configuración reside en sveltekit({...}) dentro de vite.config.ts, con opciones de Kit en el nivel superior junto a compilerOptions. Kit 3 ya no lee svelte.config.js.
• #lib reemplaza $lib mediante subpath imports en package.json. Escribe extensiones de archivo, como #lib/server/db.ts.
• Un segmento de nombre de archivo server, o cualquier directorio server fuera de src/routes, marca un módulo solo de servidor. Un segmento de nombre de archivo remote, como en data.remote.ts o remote.ts, marca un módulo remoto.
• Declara variables de entorno en src/env.ts con defineEnvVars de @sveltejs/kit/env. Importa valores desde $app/env/private y $app/env/public, y browser, building, dev, version desde $app/env. Las variables públicas pueden aparecer en app.html como %sveltekit.env.NAME%. $env/* y $app/environment son alias obsoletos.
• $app/stores está eliminado; usa $app/state. page.url es de solo lectura; cópialo con new URL(page.url) antes de mutarlo. Los valores de estado en $app/state existen con sus variantes de navegador y SSR; accede a .current en el navegador. navigate y pushState de $app/state están disponibles como funciones directas. onNavigate de $app/state se ejecuta al inicio de las navegaciones; el callback willSnap recibe registros de instantáneas de desplazamiento. afterNavigate, beforeNavigate, onNavigate y goto se importan desde $app/state.

Configuración de enrutamiento, página y diseño

• Kit 3 enruta src/routes/(group)/path/folder/+page.ts, /layout.ts, /layout.svelte, /+page.svelte, /+error.svelte y /+server.ts con carga diferida. Puedes exportar load, actions, entries, prerender, ssr y csrf.
• Kit 3 no necesita export const trailingSlash; configúralo en sveltekit({ trailingSlash: 'always' }) en la configuración del plugin.
• Usa parámetros de ruta: [param] dinámico, [...rest] rest, [[optional]] opcional. Las expresiones de ruta tipadas usan [param=type], con tipos definidos en src/params. Los tipos coincidentes comunes incluyen integer, uuid, slugify, letter, alphanumeric, color, datetime, date, duration, filepath y path. uuid y duration tienen inversas completas; la mayoría carece de etapa de generación de URL inversa en entries.
• Los diseños pueden exportar load.
• goto con hash selecciona escuchas de desplazamiento (onNavigate recibe willSnap). Si usas onNavigate, el tercer parámetro debe ser un objeto willSnap.

Ruta de error y página de error

• +error.svelte es un límite de error. Muestra el error con $page.error. El tipo por defecto es App.Error. Maneja errores en hooks.server.ts con handleError y devuelve un objeto con message. handleError en el navegador requiere experimental.async. En Kit 3, handleError recibe App.Error; en Kit 2, el tipo App.Error está disponible y debe ser tipado en app.d.ts como { message: string; code?: string }.

Navegación de páginas

• goto con beforeNavigate sobrescribe la confirmación del usuario si se cancela. Llama a confirmNavigation() confirmará y cancelNavigation() redirige. Los efectos afterNavigate se ejecutan después de que el DOM se estabiliza.
• La desactivación del servidor y las actualizaciones de módulos en caliente pueden afectar la navegación. Verifica el estado de la navegación con $app/state.

Endpoints de API

• +server.ts exporta GET, POST, etc. url.searchParams es el objeto de parámetros de consulta. Usa request.formData() para datos de formulario. Devuelve json(), text(), redirect() o un Response.

Acciones de formulario

• +page.server.ts exporta acciones con export const actions = { default: async (event) => { ... } }. Usa fail() para errores de validación, redirect() para redirecciones y json() para respuestas JSON.
• Las acciones reciben request, params, url, cookies, locals, platform, fetch y isFormData. isFormData está disponible desde SvelteKit 2.70.
• Los formularios HTML usan method="POST" con use:enhance para envío progresivo. use:enhance recibe un callback ({ formData, action, result }).
• Devuelve { success: true } para éxito. fail(status, data) para errores.

Cookies

• cookies.set(name, value, options) con httpOnly, secure, sameSite, path, maxAge.
• Lee cookies con cookies.get(name), elimínalas con cookies.delete(name).
• Las cookies disponibles en load y acciones.

Manejo de errores

• error(status, message) desde @sveltejs/kit lanza errores HTTP en load y acciones. redirect(status, location) redirige.
• handleError captura errores no manejados.

Carga de datos

• load en +page.ts y +layout.ts. load recibe event y fetch. Devuelve datos como objeto plano. Las funciones load pueden ser asíncronas. Los datos se pasan como data a page.svelte o layout.svelte.

SEO y metadatos

• Usa svelte:head en +page.svelte o +error.svelte para metadatos. $page.url para URL actual. Las etiquetas meta se renderizan en el servidor y se actualizan en el cliente.

Variables de entorno

• $app/env/private para variables privadas del servidor, $app/env/public para variables públicas.

Soporte de TypeScript

• TypeScript 6 requerido para Kit 3. Usa satisfies y tipos mejorados. App.Locals para locals, App.PageData para datos de página, App.Error para errores.

Despliegue

• adapter-auto para despliegues serverless, adapter-node para Node.js, adapter-static para sitios estáticos. npm run build construye, npm run preview previsualiza.

Kit 3: Migración desde Kit 2

• Ejecuta npx sv migrate y sigue los TODOs generados. Las claves de configuración han cambiado; verifica la documentación de plugins. $app/stores requiere $app/state. $lib requiere #lib. La configuración de Vite está en vite.config.ts. Verifica la compatibilidad de dependencias.