SvelteKit 3

Actualiza un proyecto de SvelteKit 2 a SvelteKit 3.

Sintaxis

$ vela migrate sveltekit-3

Vela 0.15 solo escribe código de SvelteKit 3. En un proyecto de SvelteKit 2, uno cuyo package.json declara @sveltejs/kit 2 o que todavía tiene un svelte.config.js, vela bless, vela deploy y los comandos que escriben código, como enable, disable y generate, se niegan a ejecutarse y remiten aquí. vela dev, build, preview y test:server siguen funcionando, con un aviso de una línea.

Un proyecto de SvelteKit 2 fija vela ^0.14, que nunca pasa a 0.15 por sí solo, así que ejecuta la migración con npx:

$ npx vela@^0.15 migrate sveltekit-3

O quédate en Vela 0.14, que sigue funcionando con SvelteKit 2.

Opciones

  • --cwd <path> - El proyecto que migrar; por defecto, el proyecto actual
  • --no-install - Omite la instalación de dependencias
  • --force - Se ejecuta aunque el árbol de trabajo de git tenga cambios sin confirmar
  • --skip-sv - Solo ejecuta los pasos de Vela, para un proyecto que sv ya migró

Qué hace

Necesita Node 22.17 o posterior, y un árbol de trabajo de git limpio para que los cambios de la migración se puedan revisar por separado.

Primero ejecuta la migración propia de SvelteKit, sv migrate sveltekit-3. La configuración sale de svelte.config.js y pasa al plugin sveltekit() de vite.config.ts, tsconfig.json extiende $app/tsconfig, las importaciones de $lib pasan a #lib, las variables de entorno se declaran en src/env.ts y se leen de $app/env, y las APIs de SvelteKit pasan a sus nuevos módulos.

Después hace lo que un proyecto de Vela necesita además:

  • Restaura VELA_ORIGIN como paths.origin, que sv descarta al mover la configuración. Consulta vela build.
  • Declara en src/env.ts las variables que lee Vela, como POCKETBASE_URL. Consulta vela env.
  • Añade #lib a los imports de package.json, hace que components.json apunte a él y reescribe las importaciones de $lib que sv deja atrás, como las de fuera de src/.
  • Sustituye el alias $locales de i18n por una importación #locales.
  • Sube las versiones mínimas de vela y de los paquetes que SvelteKit 3 necesita, y añade overrides para las dependencias que todavía declaran SvelteKit 2 como peer.
  • Elimina las entradas del lockfile que de otro modo harían fallar la instalación.

Luego instala las dependencias y da formato a lo que cambió.

Qué queda

Lo que no se puede hacer con seguridad de forma automática se enumera en MIGRATION_TASKS.md y se marca en el código con comentarios @migration-task. Resuelve ambos y elimina el archivo; después ejecuta npm run check, vela test:server y npm run build.

Los servidores también necesitan Node 22.17 o posterior. Ejecuta vela provision en cada uno antes del primer despliegue con SvelteKit 3.

Volver a ejecutar el comando es seguro. En un proyecto que ya está en SvelteKit 3 se salta sv y solo vuelve a comprobar los pasos de Vela.