feat: add VITE_ENVIRONMENT variable for environment-specific configuration

JeromeBu · JeromeBu · commit 86d4a1d3844f · 2025-11-07T12:05:06.000+01:00
diff --git a/.env.sample b/.env.sample
@@ -2,6 +2,12 @@ DATABASE_URL=postgresql://catalogi:pg_password@localhost:5432/db
 API_PORT=3084
 EXTERNAL_SOFTWARE_DATA_ORIGIN=wikidata
 
+# Environment identifier for environment-specific configuration
+# Valid values: "local", "dev", "staging", "pre-production", "production"
+# Can be used for environment-specific features like Sentry monitoring, logging levels, etc.
+# Defaults to "local" if not provided
+VITE_ENVIRONMENT=local
+
 VITE_HEAD="
   <title>Catalogi - Local use</title>
 
diff --git a/api/src/env.ts b/api/src/env.ts
@@ -14,6 +14,7 @@ const zEnvConfiguration = z.object({
     "databaseUrl": z.string(),
     "appUrl": z.string().url(),
     "isDevEnvironnement": z.boolean().default(false),
+    "environment": z.enum(["local", "dev", "staging", "pre-production", "production"]).default("local"),
     "port": z.coerce.number().optional().default(8080),
     "importDataSourceOrigin": z.string().optional().default("wikidata"),
     "botUserEmail": z.string().optional(),
@@ -33,6 +34,7 @@ const envConfiguration = zEnvConfiguration.parse({
     "port": parseInt(process.env.API_PORT ?? ""),
     "appUrl": process.env.APP_URL,
     "isDevEnvironnement": process.env.IS_DEV_ENVIRONNEMENT?.toLowerCase() === "true",
+    "environment": process.env.VITE_ENVIRONMENT,
     "importDataSourceOrigin": process.env.IMPORT_DATA_SOURCE_ORIGIN,
     "redirectUrl": process.env.REDIRECT_URL,
     "databaseUrl": process.env.DATABASE_URL,
diff --git a/deployment-examples/docker-compose/.env.sample b/deployment-examples/docker-compose/.env.sample
@@ -6,6 +6,12 @@ EXTERNAL_SOFTWARE_DATA_ORIGIN=wikidata
 OIDC_ISSUER_URI=https://auth.code.gouv.fr/auth/realms/codegouv
 OIDC_CLIENT_ID=sill
 
+# Environment identifier for environment-specific configuration
+# Valid values: "local", "dev", "staging", "pre-production", "production"
+# Can be used for environment-specific features like Sentry monitoring, logging levels, etc.
+# Defaults to "local" if not provided
+VITE_ENVIRONMENT=production
+
 VITE_HEAD="
   <title>Catalogi - Deployment exemple</title>
 
diff --git a/docs/6-env-variables-and-customization.md b/docs/6-env-variables-and-customization.md
@@ -7,7 +7,7 @@
 
 ## Environment variables
 
-The following environment variables are used to configure the Catalogi web application. 
+The following environment variables are used to configure the Catalogi web application.
 You can set them in a `.env` file or directly in your environment.
 
 | Variable Name | Required | Default Value | Example Value |
@@ -17,13 +17,33 @@ You can set them in a `.env` file or directly in your environment.
 | DATABASE_URL | ✅ | - | `postgresql://catalogi:pg_password@localhost:5432/catalogi` |
 | API_PORT | ❌ | `8080` | `1234` |
 | IS_DEV_ENVIRONNEMENT | ❌ | `false` | `true` |
+| VITE_ENVIRONMENT | ❌ | `local` | `local`, `dev`, `staging`, `pre-production`, or `production` |
 | EXTERNAL_SOFTWARE_DATA_ORIGIN | ❌ | `wikidata` | `wikidata` or `HAL` |
 | INIT_SOFT_FROM_SOURCE | ❌ | `false` | `true` |
 | BOT_AGENT_EMAIL | ❌ | - | `bot@example.com` |
 | IMPORT_WIKIDATA | ❌ | - | `Q123,Q456,Q789` |
 | REDIRECT_URL | ❌ | - | `https://catalogi.example.com` |
 
-There is another variable that is purely for frontend configuration, which can contain HTML code, that will be injected in the `<head>` of the web application. It is useful to add meta tags, or other HTML elements that you want to be present in the head of the page. Note that you cannot use the syntay with backticks '`'.
+### VITE_ENVIRONMENT
+
+The `VITE_ENVIRONMENT` variable identifies the deployment environment and is available in both the API (backend) and web (frontend). Valid values are:
+- `local` - Local development environment (default)
+- `dev` - Development environment
+- `staging` - Staging environment
+- `pre-production` - Pre-production environment
+- `production` - Production environment
+
+This variable can be used to enable environment-specific features and configurations, such as:
+- Error monitoring and logging services (e.g., Sentry)
+- Analytics and tracking tools
+- Feature flags and conditional behavior
+- Different API endpoints or service configurations
+
+While Sentry is not currently set up in this project, the `VITE_ENVIRONMENT` variable provides the foundation for integrating such tools if they become frequently requested features.
+
+### VITE_HEAD
+
+There is another variable that is purely for frontend configuration, which can contain HTML code, that will be injected in the `<head>` of the web application. It is useful to add meta tags, or other HTML elements that you want to be present in the head of the page. Note that you cannot use the syntay with backticks '`'.
 
 ```
 VITE_HEAD="
diff --git a/web/.env.declaration b/web/.env.declaration
@@ -1,14 +1,15 @@
 VITE_HEAD="
   <title>Catalogi</title>
 
-  <!-- 
+  <!--
     <meta name='title' content='Setup whatever you want'>
-    <meta name='description' content='Setup whatever you want'> 
+    <meta name='description' content='Setup whatever you want'>
   -->
 
   <script defer>
     console.log('Default script. You can change VITE_HEAD env variable, to edit what is injected in the <head> of the page.');
   </script>
 "
+VITE_ENVIRONMENT=
 VERSION=
 NODE_ENV=
diff --git a/web/src/vite-env.d.ts b/web/src/vite-env.d.ts
@@ -23,6 +23,7 @@ type ImportMetaEnv = {
   DEV: boolean
   PROD: boolean
   VITE_HEAD: string
+  VITE_ENVIRONMENT: string
   VERSION: string
   NODE_ENV: string
   // @user-defined-start
