Variables de entorno

Las variables de entorno permiten usar información confidencial, como claves de API y credenciales de bases de datos, si necesidad de almacenarlas en el control de versiones.

Durante el desarrollo y en el momento de la compilación, las variables definidas en un archivo .env y .env.local se añadirán al entorno.

API_KEY=abc1234cde

Las variables de entorno explícitas se deben importar de los módulos:

• $app/env/private
• $app/env/public

Configuración

vite.config.ts

export default defineConfig({
  plugins: [
    sveltekit({
      experimental: {
        remoteFunctions: true,
        explicitEnvironmentVariables: true, // <==============
      },
      compilerOptions: {
      },
      adapter: adapter(),
    }),
  ],
});

Agregar un archivo src/env.ts que exporte un objeto variables

src/env.ts

import { defineEnvVars } from '@sveltejs/kit/env';

export const variables = defineEnvVars({
	// ...
});

Variables privadas

Definición Por defecto, todas las variables se consideran privadas.

src/env.ts

import { defineEnvVars } from '@sveltejs/kit/env';

export const variables = defineEnvVars({
	API_KEY: {}
});

• Para el ejemplo, como API_KEY no necesita ninguna configuración entonces se puede usar un objeto vacío

Uso Ahora que API_KEYestá definido, se puede importar al código de la aplicación mediante $app/env/private:

import { API_KEY } from "$app/env/private";

• El módulo $app/env/private no se puede importar en código que se ejecuta en el navegador, para no revelar accidentalmente información sensible en un paquete de JavaScript

Variables públicas

En el objeto de configuración de la variable se habilita que sea pública, esto hace que sean públicas para el navegador.

src/env.ts

import { defineEnvVars } from '@sveltejs/kit/env';

export const variables = defineEnvVars({
	GOOGLE_ANALYTICS_ID: {
		public: true // <===============
	}
});

Ahora, se puede importar desde $app/env/public o utilizar en la plantilla app.html como %sveltekit.env.GOOGLE_ANALYTICS_ID%

Tipado o validación

Se puede utilizar un validador estándar de esquemas como Valibot o Zod para comprobar que el valor de una variable de entorno sea correcto:

Si un valor no es válido, la aplicación no se iniciará (o compilará).

src/env.ts

import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	GOOGLE_ANALYTICS_ID: {
		public: true,
		schema: v.pipe(v.string(), v.regex(/G-[A-Z0-9]+/))
	}
});

Es posible iniciar la aplicación aunque no esté definida la variable si se configura como si fuese una variable opcional.

src/env.ts

import { defineEnvVars } from '@sveltejs/kit/env';
import { building } from '$app/env'
import * as v from 'valibot';

export const variables = defineEnvVars({
	SECRET: {
		// opcional cuando se compila pero requerido cuando se inicia la app
		schema: building ? v.optional(v.string()) : v.string()
	}
});

Se pueden usar los validadores para hacer que los valores sean opcionales o transformarlos (por ejemplo, convertir una cadena en un valor booleano o analizar JSON) (se debe consultar la documentación del paquete que se está utilizando).

Variables estáticas

• Por defecto, las variables son dinámicas.
• Si una variable se configura con static: true, se incluirá directamente ("inline") en el código de tu aplicación, lo que habilita optimizaciones como la eliminación de código muerto (dead-code elimination).

Por ejemplo una app que se vende a distintos clientes. Algunos pagan un plan que incluye un widget de chat en vivo, y otros no. El widget usa una librería pesada (WebSockets, SDK del proveedor, etc.), por lo que no conviene que ese código viaje en el bundle de los clientes que no lo tienen contratado.

src/env.ts

import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	ENABLE_CHAT_WIDGET: {
		public: true,
		static: true,

		// convertir a true/false
		schema: v.pipe(
			v.optional(v.string(), ''),
			v.transform((str) => str !== '')
		)
	}
});

Como esta variable es static, el componente <ChatWidget> que se muestra aquí quedará excluido del bundle de JavaScript a menos que ENABLE_CHAT_WIDGET sea verdadero (truthy):

<script>
	import { ENABLE_CHAT_WIDGET } from '$app/env/public';
	import ChatWidget from '$lib/components/ChatWidget.svelte';
</script>

{#if ENABLE_CHAT_WIDGET}
	<ChatWidget />
{/if}

Pero si la variable se define antes de compilar la app...

ENABLE_CHAT_WIDGET=true npm run build

...entonces el componente se incluirá y se mostrará.