Skip to main content
SvelteKitConcepts clés

Variables d’environment

Les variables d’environnement sont des valeurs dont votre application a besoin, mais qui existent en dehors du code source de votre application. Elles vous permettent d’utiliser des informations sensibles comme des clés d’API ou des authentifiants de bases de données sans les stocker dans votre contrôle de version.

Lors du développement, et au moment de la compilation, les variables définids dans un fichier .env ou .env.local seront ajoutées à l’environnement :

.env
API_KEY=19f401ba-e8b0-48c4-8c77-b0ebb26d97fe

Par défaut, chaque variable d’environnement est rendue implicitement disponible au sein de votre application via les modules suivants :

Variables d’environnement explicites

Depuis SvelteKit 2.63, vous pouvez activer les variables d’environnement explicites, ce qui vous permet plutôt d’importer vos variables d’environnement depuis ces modules :

Additionnellement, le module $app/environment est renommé en $app/env.

Les variables d’environnement explicites seront le comportement par défaut de SvelteKit 3. Les modules $env/*, ainsi que $app/environment, seront supprimés.

Mise en place

Pour activer les variables d’environnement explicites, mettez votre configuration à jour...

svelte.config
export default {
	kit: {
		experimental: {
			explicitEnvironmentVariables: true
		}
	}
};

... et ajoutez un fichier src/env.ts (ou src/env.js) exportant un objet variables :

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

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

Chaque valeur de l’objet passée à defineEnvVars est un objet EnvVarConfig qui configure la variable d’environnement.

defineEnvVars renvoie son argument inchangé — cette fonction n’existe que pour vous aider avec le typage.

Variables privées

Par défaut, toutes les variables sont considérées privées. Par exemple, vous ne souhaitez pas révéler votre API_KEY :

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

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

Puisqu’aucune configuration n’est nécessaire pour cette variable, nous pouvons utiliser un objet vide ({}).

Maintenant que API_KEY est défini, elle peut être importée dans le code applicatif via $app/env/private :

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

Le module $app/env/private ne peut pas être importé dans du code exécuté dans le navigateur, de sorte que ne puissiez pas accidentellement révéler vos secrets dans un bundle JavaScript.

Variables publiques

Certaines variables peuvent être rendues accessibles dans le navigateur sans aucun danger — c’est même parfois nécessaire. Pour ces variables, nous pouvons préciser public: true :

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

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

GOOGLE_ANALYTICS_ID peut maintenant être importée depuis $app/env/public, ou utilisée dans votre fichier de template app.html en tant que %sveltekit.env.GOOGLE_ANALYTICS_ID% :

src/app
<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<link rel="icon" href="%sveltekit.assets%/favicon.png" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		%sveltekit.head%

		<script
			async
			src="https://www.googletagmanager.com/gtag/js?id=%sveltekit.env.GOOGLE_ANALYTICS_ID%"
		></script>

		<script>
			window.dataLayer ??= [];
			function gtag(){dataLayer.push(arguments)}
			gtag('js', new Date());
			gtag('config', '%sveltekit.env.GOOGLE_ANALYTICS_ID%');
		</script>
	</head>
	<body data-sveltekit-preload-data="hover">
		<div style="display: contents">%sveltekit.body%</div>
	</body>
</html>

Validation

Vous pouvez préciser un validateur de Standard Schema comme Zod ou Valibot pour vérifier que’une variable d’nvironnement est définie correctement :

src/env
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]+/))
	}
});

Si une valeur est invalide, l’application échouera à se lancer (ou à compiler). Pour en désactiver une, utilisez l’export building de $app/env en combinaison avec un validateur qui accepte une valeur optionnelle :

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

export const variables = defineEnvVars({
	SECRET: {
		// optionnel lors de la compilation, mais requis au démarrage de l'application
		schema: building ? v.optional(v.string()) : v.string()
	}
});

Vous pouvez utiliser le validateurs pour rendre des valeurs optionnelles, ou les transformer (comme transformer une string en booléen, ou parser du JSON) — voir la documentation de votre librairie de validation pour en savoir plus.

Variables statiques

Par défaut, les variables sont dynamiques. Si une variable est configurée avec static: true, elle sera inlinée dans le code applicatif, permettant des optimisations telles que l’élimination de code mort :

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

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

		// transforme la valeur en true/false
		schema: v.pipe(
			v.optional(v.string(), ''),
			v.transform((str) => str !== '')
		)
	}
});

Puisque cette variable est static, le composant <DebugOverlay> utilisé ici sera exclus du bundle JavaScript à moins que SHOW_DEBUG_OVERLAY ne soit vrai :

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

{#if SHOW_DEBUG_OVERLAY}
	<DebugOverlay />
{/if}

Mais si la variable est définie lors de la compilation de l’applicaation...

SHOW_DEBUG_OVERLAY=true npm run build

... alors le composant sera inclus et affiché.

Documenter les variables

Vous pouvez documenter le rôle d’une variable d’environnement en ajoutant une description :

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

export const variables = defineEnvVars({
	CACHE_TTL_SECONDS: {
		description: 'Combien de temps cacher les réponses, en secondes'
	}
});

Survoler CACHE_TTL_SECONDS dans le code de votre application affichera alors la description.

Modifier cette page sur Github llms.txt

précédent suivant
Fonctions distantes