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
/// file: .env.local
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 :
- [`$env/static/private`]($env-static-private)
- [`$env/static/public`]($env-static-public)
- [`$env/dynamic/private`]($env-dynamic-private)
- [`$env/dynamic/public`]($env-dynamic-public)
## Variables d'environnement explicites [!VO]Explicit environment variables
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 :
- [`$app/env/private`]($app-env-private)
- [`$app/env/public`]($app-env-public)
Additionnellement, le module [`$app/environment`]($app-environment) est renommé en
[`$app/env`]($app-env).
> [!NOTE] 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 [!VO]Setup
Pour activer les variables d'environnement explicites, mettez votre configuration à jour...
```js
/// file: svelte.config.js
export default {
kit: {
experimental: {
+++explicitEnvironmentVariables: true+++
}
}
};
```
... et ajoutez un fichier `src/env.ts` (ou `src/env.js`) exportant un objet `variables` :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
export const variables = defineEnvVars({
// ...
});
```
Chaque valeur de l'objet passée à [`defineEnvVars`](@sveltejs-kit-hooks#defineEnvVars) est un objet
[`EnvVarConfig`](@sveltejs-kit#EnvVarConfig) qui configure la variable d'environnement.
> [!NOTE] `defineEnvVars` renvoie son argument inchangé — cette fonction n'existe que pour vous
> aider avec le typage.
### Variables privées [!VO]Private variables
Par défaut, toutes les variables sont considérées privées. Par exemple, vous ne souhaitez pas
révéler votre `API_KEY` :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
export const variables = defineEnvVars({
+++API_KEY: {}+++
});
```
> [!NOTE] 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` :
```js
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 [!VO]Public variables
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` :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
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%` :
```html
%sveltekit.head%
%sveltekit.body%
```
### Validation
Vous pouvez préciser un validateur de [Standard Schema](https://standardschema.dev/) comme
[Zod](https://zod.dev/) ou [Valibot](https://valibot.dev/) pour vérifier que'une variable
d'nvironnement est définie correctement :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
+++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`]($app-env#building) de `$app/env` en combinaison avec un
validateur qui accepte une valeur optionnelle :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
+++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 [!VO]Static variables
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 :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
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 `` utilisé ici sera exclus du bundle
JavaScript à moins que `SHOW_DEBUG_OVERLAY` ne soit vrai :
```svelte
{#if SHOW_DEBUG_OVERLAY}
{/if}
```
Mais si la variable est définie lors de la compilation de l'applicaation...
```bash
SHOW_DEBUG_OVERLAY=true npm run build
```
... alors le composant sera inclus et affiché.
### Documenter les variables [!VO]Documenting variables
Vous pouvez documenter le rôle d'une variable d'environnement en ajoutant une `description` :
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/hooks';
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.