Si sigues de cerca el mundo frontend, seguro que recuerdas lo largo que fue el camino del ecosistema Svelte hasta estabilizar el compilador Svelte 5 con su nuevo sistema de runas reactivas. Ahora ha llegado el siguiente paso lógico: el equipo ha publicado oficialmente el lanzamiento mayor del framework SvelteKit 3, acompañado de la versión estable de la CLI sv 1.0.
No estamos ante una simple actualización rutinaria de dependencias menores. Esta versión hace limpieza general de soluciones legacy acumuladas durante años, abandona los atajos propietarios del framework para abrazar estándares oficiales de Node.js y rediseña por completo el comportamiento de los adaptadores de servidor para las plataformas serverless actuales.
Vamos a desgranar qué ha cambiado exactamente bajo el capó, qué patrones habituales toca reescribir y cómo la nueva utilidad sv automatiza la parte más pesada de la migración.
Adiós, $lib: salto a los Subpath Imports estándar y a un único vite.config.ts
Probablemente el cambio sintáctico más visible con el que te toparás nada más actualizar sea la desaparición del mítico alias $lib.
En SvelteKit 1 y 2, el signo de dólar al principio del import (import Button from '$lib/Button.svelte') era pura magia interna del framework. Por debajo trabajaba una combinación de plugins de Vite y ajustes en tsconfig.json para reescribir la ruta. El problema es que esa magia chocaba constantemente con herramientas externas: linters como ESLint, analizadores estáticos como Biome o runtimes modernos como Bun y Deno tropezaban una y otra vez con ese identificador no estándar.
En SvelteKit 3, los desarrolladores han eliminado $lib sin contemplaciones y han pasado al estándar nativo de ECMAScript: los Subpath Imports con almohadilla:
// Antes en SvelteKit 2:
// import { formatDate } from '$lib/utils/format';
// Ahora en SvelteKit 3:
import { formatDate } from '#lib/utils/format.js';
Como este mecanismo ahora se resuelve mediante el sistema nativo de módulos de la plataforma, aparece una exigencia estricta: en los imports es obligatorio indicar la extensión exacta del archivo (.js, .ts, .svelte).
La segunda simplificación importante afecta a la configuración. Antes siempre tenías dos archivos vecinos en la raíz del proyecto: svelte.config.js y vite.config.ts. En el primero configurabas adaptadores de despliegue y preprocesadores, y en el segundo los plugins del empaquetador, lo que provocaba retardos asíncronos al inicializar Vite. En la versión 3, svelte.config.js deja de usarse para opciones de SvelteKit: todos los parámetros y adaptadores se declaran ahora dentro de la llamada al plugin sveltekit() directamente en vite.config.ts.
Giro radical en los adaptadores: workers estrictos en Cloudflare y hashes ETag en Node
Si de las rutas de importación se encarga la herramienta de migración, el código de servidor sí requerirá tu atención directa. Los cambios más profundos han recaído sobre los dos adaptadores más populares:
- Cloudflare Workers (
@sveltejs/adapter-cloudflare@8.0.0): Antes, para acceder a bases de datos D1, almacenamiento KV o colas de Cloudflare, los desarrolladores usaban el objeto global de plataformaevent.platform.env.MY_KV. Aquello era una fuente constante de confusiones: los tipos solían divergir del entorno real y el emulador local Miniflare se comportaba distinto que producción. En SvelteKit 3, el objetoplatformdesaparece por completo. Todos los bindings se importan ahora a través del módulo virtual emuladocloudflare:workers:
// src/routes/api/counter/+server.ts
import { env } from 'cloudflare:workers';
import { json } from '@sveltejs/kit';
export async function GET() {
// Acceso directo a variables de entorno y almacenamiento KV con tipado estricto
const currentCount = (await env.COUNTER_KV.get('hits')) ?? '0';
const nextCount = parseInt(currentCount, 10) + 1;
await env.COUNTER_KV.put('hits', nextCount.toString());
return json({ hits: nextCount });
}
- Node.js (
@sveltejs/adapter-node@6.0.0): El equipo ha reescrito desde cero la entrega de archivos estáticos, dejando atrás la antigua libreríasirv. Ahora el manifiesto estático se precalcula en tiempo de compilación y cada archivo recibe una cabecera estrictaETagbasada en un hash criptográfico de su contenido. Así el navegador recibe al instante un304 Not Modifiedsin llamadas innecesarias al disco para comprobar fechas de modificación. Eso sí, hay una restricción arquitectónica importante: el adaptador ya no sirve bajo ningún concepto archivos generados por la aplicación dinámicamente después de arrancar el contenedor. Si tu servicio generaba informes PDF en una carpeta local de estáticos, ahora tendrás que servirlos desde un endpoint explícito+server.tso subirlos a un almacenamiento compatible con S3.
SvelteKit 3 exige Node.js en versión v22.17 o superior, el compilador Svelte 5.57.1 o más reciente, Vite 8+ y TypeScript 6.0+. En versiones antiguas de Node la compilación fallará al parsear los subpath imports.
Migración automática con CLI sv 1.0 y complementos oficiales
Para que no tengas que reescribir cientos de imports a mano, el lanzamiento llega acompañado de la nueva CLI oficial sv 1.0. Para actualizar un proyecto basta con ejecutar:
# Lanzamiento del asistente oficial de actualización del proyecto
npx sv migrate sveltekit-3
La utilidad recorrerá todo el código, sustituirá $lib por #lib con las extensiones correctas, moverá la configuración de los adaptadores a vite.config.ts y actualizará el manifiesto package.json.
Además, sv 1.0 estrena una API estandarizada de complementos (add-ons). Ahora, para activar el plugin oficial de optimización progresiva de imágenes no hace falta pelearse con archivos de configuración:
# Instalación y configuración automática del complemento enhanced-img
npx sv add enhanced-img
Qué revisar antes de actualizar un proyecto en producción
Siempre recomiendo abordar los lanzamientos mayores con la cabeza fría. Dar el salto a SvelteKit 3 aporta mejoras tangibles: el arranque en frío de Vite es notablemente más rápido, el cacheo por ETag descarga los nodos de servidor y el tipado en Cloudflare por fin es sólido como una roca.
Antes de pulsar el botón de actualizar, comprueba tres cosas:
- Que tu proyecto no genere archivos temporales a medida dentro de la carpeta pública de estáticos (si usas
adapter-node). - Que tus runners de CI/CD estén preparados para Node.js 22.17.
- Que todas las mutaciones en segundo plano del cliente terminen con una llamada explícita a
ignore()(el servidor de SvelteKit 3 ahora interrumpe con error las peticiones single-flight paralelas que queden sin cerrar).
Con esos tres puntos cubiertos, ejecutar npx sv migrate sveltekit-3 convertirá la actualización en un paseo agradable de media hora.


