Merge pull request #880 from IQSS/877-spa-runtime-config

New SPA Runtime Configuration and Language Selector

Author: ChengShi-1

.env.example

@@ -30,7 +30,10 @@ jobs:
         working-directory: packages/design-system
         run: npm run build
 
-      - name: Create and populate .env file
+      - name: Build with base path
+        run: npm run build -- --base=/spa
+
+      - name: Override runtime config.js for BETA
         env:
           DATAVERSE_BACKEND_URL: ${{ secrets.BETA_DATAVERSE_BACKEND_URL }}
           OIDC_CLIENT_ID: ${{ secrets.BETA_OIDC_CLIENT_ID }}
@@ -39,18 +42,26 @@ jobs:
           OIDC_LOGOUT_ENDPOINT: ${{ secrets.BETA_OIDC_LOGOUT_ENDPOINT }}
           OIDC_STORAGE_KEY_PREFIX: ${{ secrets.BETA_OIDC_STORAGE_KEY_PREFIX }}
         run: |
-          touch .env
-          echo VITE_DATAVERSE_BACKEND_URL="$DATAVERSE_BACKEND_URL" >> .env
-          echo VITE_OIDC_CLIENT_ID="$OIDC_CLIENT_ID" >> .env
-          echo VITE_OIDC_AUTHORIZATION_ENDPOINT="$OIDC_AUTHORIZATION_ENDPOINT" >> .env
-          echo VITE_OIDC_TOKEN_ENDPOINT="$OIDC_TOKEN_ENDPOINT" >> .env
-          echo VITE_OIDC_LOGOUT_ENDPOINT="$OIDC_LOGOUT_ENDPOINT" >> .env
-          echo VITE_OIDC_STORAGE_KEY_PREFIX="$OIDC_STORAGE_KEY_PREFIX" >> .env
+          mkdir -p ./dist
+          cat > ./dist/config.js <<EOF
+          window.__APP_CONFIG__ = {
+            backendUrl: "${DATAVERSE_BACKEND_URL}",
+            oidc: {
+              clientId: "${OIDC_CLIENT_ID}",
+              authorizationEndpoint: "${OIDC_AUTHORIZATION_ENDPOINT}",
+              tokenEndpoint: "${OIDC_TOKEN_ENDPOINT}",
+              logoutEndpoint: "${OIDC_LOGOUT_ENDPOINT}",
+              localStorageKeyPrefix: "${OIDC_STORAGE_KEY_PREFIX}"
+            },
+            languages: [
+              { code: 'en', name: 'English' },
+              { code: 'es', name: 'Español' }
+            ],
+            defaultLanguage: 'en'
+          }
+          EOF
         shell: bash
 
-      - name: Build with base path
-        run: npm run build -- --base=/spa
-
       - uses: actions/upload-artifact@v4
         with:
           name: built-site

.github/workflows/deploy-beta-testing.yml

@@ -41,8 +41,10 @@ jobs:
         working-directory: packages/design-system
         run: npm run build
 
-      # For BETA environment
-      - name: Create and populate .env file for BETA
+      - name: Build with base path
+        run: npm run build -- --base=/${{ github.event.inputs.basepath }}
+
+      - name: Override runtime config.js for BETA
         if: ${{ github.event.inputs.environment == 'beta' }}
         env:
           DATAVERSE_BACKEND_URL: ${{ secrets.BETA_DATAVERSE_BACKEND_URL }}
@@ -52,17 +54,26 @@ jobs:
           OIDC_LOGOUT_ENDPOINT: ${{ secrets.BETA_OIDC_LOGOUT_ENDPOINT }}
           OIDC_STORAGE_KEY_PREFIX: ${{ secrets.BETA_OIDC_STORAGE_KEY_PREFIX }}
         run: |
-          touch .env
-          echo VITE_DATAVERSE_BACKEND_URL="$DATAVERSE_BACKEND_URL" >> .env
-          echo VITE_OIDC_CLIENT_ID="$OIDC_CLIENT_ID" >> .env
-          echo VITE_OIDC_AUTHORIZATION_ENDPOINT="$OIDC_AUTHORIZATION_ENDPOINT" >> .env
-          echo VITE_OIDC_TOKEN_ENDPOINT="$OIDC_TOKEN_ENDPOINT" >> .env
-          echo VITE_OIDC_LOGOUT_ENDPOINT="$OIDC_LOGOUT_ENDPOINT" >> .env
-          echo VITE_OIDC_STORAGE_KEY_PREFIX="$OIDC_STORAGE_KEY_PREFIX" >> .env
-        shell: bash
-
-      # For QA environment
-      - name: Create and populate .env file for QA
+          mkdir -p ./dist
+          cat > ./dist/config.js <<EOF
+          window.__APP_CONFIG__ = {
+            backendUrl: "${DATAVERSE_BACKEND_URL}",
+            oidc: {
+              clientId: "${OIDC_CLIENT_ID}",
+              authorizationEndpoint: "${OIDC_AUTHORIZATION_ENDPOINT}",
+              tokenEndpoint: "${OIDC_TOKEN_ENDPOINT}",
+              logoutEndpoint: "${OIDC_LOGOUT_ENDPOINT}",
+              localStorageKeyPrefix: "${OIDC_STORAGE_KEY_PREFIX}"
+            },
+            languages: [
+              { code: 'en', name: 'English' },
+              { code: 'es', name: 'Español' },
+            ],
+            defaultLanguage: 'en'
+          }
+          EOF
+
+      - name: Override runtime config.js for QA
         if: ${{ github.event.inputs.environment == 'qa' }}
         env:
           DATAVERSE_BACKEND_URL: ${{ secrets.QA_DATAVERSE_BACKEND_URL }}
@@ -72,17 +83,26 @@ jobs:
           OIDC_LOGOUT_ENDPOINT: ${{ secrets.QA_OIDC_LOGOUT_ENDPOINT }}
           OIDC_STORAGE_KEY_PREFIX: ${{ secrets.QA_OIDC_STORAGE_KEY_PREFIX }}
         run: |
-          touch .env
-          echo VITE_DATAVERSE_BACKEND_URL="$DATAVERSE_BACKEND_URL" >> .env
-          echo VITE_OIDC_CLIENT_ID="$OIDC_CLIENT_ID" >> .env
-          echo VITE_OIDC_AUTHORIZATION_ENDPOINT="$OIDC_AUTHORIZATION_ENDPOINT" >> .env
-          echo VITE_OIDC_TOKEN_ENDPOINT="$OIDC_TOKEN_ENDPOINT" >> .env
-          echo VITE_OIDC_LOGOUT_ENDPOINT="$OIDC_LOGOUT_ENDPOINT" >> .env
-          echo VITE_OIDC_STORAGE_KEY_PREFIX="$OIDC_STORAGE_KEY_PREFIX" >> .env
-        shell: bash
-
-      # For DEMO environment
-      - name: Create and populate .env file for DEMO
+          mkdir -p ./dist
+          cat > ./dist/config.js <<EOF
+          window.__APP_CONFIG__ = {
+            backendUrl: "${DATAVERSE_BACKEND_URL}",
+            oidc: {
+              clientId: "${OIDC_CLIENT_ID}",
+              authorizationEndpoint: "${OIDC_AUTHORIZATION_ENDPOINT}",
+              tokenEndpoint: "${OIDC_TOKEN_ENDPOINT}",
+              logoutEndpoint: "${OIDC_LOGOUT_ENDPOINT}",
+              localStorageKeyPrefix: "${OIDC_STORAGE_KEY_PREFIX}"
+            },
+            languages: [
+              { code: 'en', name: 'English' },
+              { code: 'es', name: 'Español' },
+            ],
+            defaultLanguage: 'en'
+          }
+          EOF
+
+      - name: Override runtime config.js for DEMO
         if: ${{ github.event.inputs.environment == 'demo' }}
         env:
           DATAVERSE_BACKEND_URL: ${{ secrets.DEMO_DATAVERSE_BACKEND_URL }}
@@ -92,17 +112,24 @@ jobs:
           OIDC_LOGOUT_ENDPOINT: ${{ secrets.DEMO_OIDC_LOGOUT_ENDPOINT }}
           OIDC_STORAGE_KEY_PREFIX: ${{ secrets.DEMO_OIDC_STORAGE_KEY_PREFIX }}
         run: |
-          touch .env
-          echo VITE_DATAVERSE_BACKEND_URL="$DATAVERSE_BACKEND_URL" >> .env
-          echo VITE_OIDC_CLIENT_ID="$OIDC_CLIENT_ID" >> .env
-          echo VITE_OIDC_AUTHORIZATION_ENDPOINT="$OIDC_AUTHORIZATION_ENDPOINT" >> .env
-          echo VITE_OIDC_TOKEN_ENDPOINT="$OIDC_TOKEN_ENDPOINT" >> .env
-          echo VITE_OIDC_LOGOUT_ENDPOINT="$OIDC_LOGOUT_ENDPOINT" >> .env
-          echo VITE_OIDC_STORAGE_KEY_PREFIX="$OIDC_STORAGE_KEY_PREFIX" >> .env
-        shell: bash
-
-      - name: Build with base path
-        run: npm run build -- --base=/${{ github.event.inputs.basepath }}
+          mkdir -p ./dist
+          cat > ./dist/config.js <<EOF
+          window.__APP_CONFIG__ = {
+            backendUrl: "${DATAVERSE_BACKEND_URL}",
+            oidc: {
+              clientId: "${OIDC_CLIENT_ID}",
+              authorizationEndpoint: "${OIDC_AUTHORIZATION_ENDPOINT}",
+              tokenEndpoint: "${OIDC_TOKEN_ENDPOINT}",
+              logoutEndpoint: "${OIDC_LOGOUT_ENDPOINT}",
+              localStorageKeyPrefix: "${OIDC_STORAGE_KEY_PREFIX}"
+            },
+            languages: [
+              { code: 'en', name: 'English' },
+              { code: 'es', name: 'Español' },
+            ],
+            defaultLanguage: 'en'
+          }
+          EOF
 
       - uses: actions/upload-artifact@v4
         with:

.github/workflows/deploy.yml

@@ -33,24 +33,6 @@ jobs:
         working-directory: packages/design-system
         run: npm run build
 
-      - name: Create and populate .env file
-        env:
-          DATAVERSE_BACKEND_URL: 'http://localhost:8000'
-          OIDC_CLIENT_ID: 'test'
-          OIDC_AUTHORIZATION_ENDPOINT: 'http://localhost:8000/realms/test/protocol/openid-connect/auth'
-          OIDC_TOKEN_ENDPOINT: 'http://localhost:8000/realms/test/protocol/openid-connect/token'
-          OIDC_LOGOUT_ENDPOINT: 'http://localhost:8000/realms/test/protocol/openid-connect/logout'
-          OIDC_STORAGE_KEY_PREFIX: 'DV_'
-        run: |
-          touch .env
-          echo VITE_DATAVERSE_BACKEND_URL="$DATAVERSE_BACKEND_URL" >> .env
-          echo VITE_OIDC_CLIENT_ID="$OIDC_CLIENT_ID" >> .env
-          echo VITE_OIDC_AUTHORIZATION_ENDPOINT="$OIDC_AUTHORIZATION_ENDPOINT" >> .env
-          echo VITE_OIDC_TOKEN_ENDPOINT="$OIDC_TOKEN_ENDPOINT" >> .env
-          echo VITE_OIDC_LOGOUT_ENDPOINT="$OIDC_LOGOUT_ENDPOINT" >> .env
-          echo VITE_OIDC_STORAGE_KEY_PREFIX="$OIDC_STORAGE_KEY_PREFIX" >> .env
-        shell: bash
-
       - name: Create containerized development environment .env file
         working-directory: dev-env
         run: cp .env.example .env
@@ -113,24 +95,6 @@ jobs:
           sed -i -e 's/<YOUR_GITHUB_AUTH_TOKEN>/${{ secrets.GITHUB_TOKEN }}/g' .npmrc
           sed -i -e 's/<YOUR_NPM_AUTH_TOKEN>/${{ secrets.NPM_AUTH_TOKEN }}/g' .npmrc
 
-      - name: Create and populate .env file
-        env:
-          DATAVERSE_BACKEND_URL: 'http://localhost:8000'
-          OIDC_CLIENT_ID: 'test'
-          OIDC_AUTHORIZATION_ENDPOINT: 'http://localhost:8000/realms/test/protocol/openid-connect/auth'
-          OIDC_TOKEN_ENDPOINT: 'http://localhost:8000/realms/test/protocol/openid-connect/token'
-          OIDC_LOGOUT_ENDPOINT: 'http://localhost:8000/realms/test/protocol/openid-connect/logout'
-          OIDC_STORAGE_KEY_PREFIX: 'DV_'
-        run: |
-          touch .env
-          echo VITE_DATAVERSE_BACKEND_URL="$DATAVERSE_BACKEND_URL" >> .env
-          echo VITE_OIDC_CLIENT_ID="$OIDC_CLIENT_ID" >> .env
-          echo VITE_OIDC_AUTHORIZATION_ENDPOINT="$OIDC_AUTHORIZATION_ENDPOINT" >> .env
-          echo VITE_OIDC_TOKEN_ENDPOINT="$OIDC_TOKEN_ENDPOINT" >> .env
-          echo VITE_OIDC_LOGOUT_ENDPOINT="$OIDC_LOGOUT_ENDPOINT" >> .env
-          echo VITE_OIDC_STORAGE_KEY_PREFIX="$OIDC_STORAGE_KEY_PREFIX" >> .env
-        shell: bash
-
       - name: Install Dependencies
         run: npm install
 

.github/workflows/test.yml

@@ -1,3 +1,4 @@
+<script src="/config.js"></script>
 <script>
   window.global = window
 </script>

.storybook/preview-head.html

@@ -9,6 +9,7 @@ import 'react-loading-skeleton/dist/skeleton.css'
 import '../src/assets/global.scss'
 import '../src/assets/swal-custom.scss'
 import '../src/assets/react-toastify-custom.scss'
+import { initAppConfig } from '../src/config'
 
 const preview: Preview = {
   parameters: {
@@ -22,6 +23,11 @@ const preview: Preview = {
   },
   decorators: [
     (Story) => {
+      const result = initAppConfig()
+      if (!result.ok) {
+        console.error('Storybook runtime config invalid/missing:', result.message)
+      }
+
       FakerHelper.setFakerSeed()
 
       const routes: RouteObject[] = [

.storybook/preview.tsx

@@ -12,13 +12,15 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - Contact Owner button in File Page.
 - Share button in File Page.
 - Link Collection and Link Dataset features.
+- With the addition of the new runtime configuration approach, we now support dynamic configuration for languages. If more than one language is configured, the Language Switcher will be shown in the header to allow users to change the language.
 
 ### Changed
 
 - Add pagination support to the Dataset Version Summaries and File Version Summaries use cases by introducing optional pagination object. #885
 - Refactored pagination to use consistent `CollectionItemsPaginationInfo` object in getMyDataCollectionItems, instead of individual limit/selectedPage parameters.
 - Use of the new `sourceLastUpdateTime` query parameter from update dataset and file metadata endpoints to support optimistic concurrency control during editing operations. See [Edit Dataset Metadata](https://guides.dataverse.org/en/6.8/api/native-api.html#edit-dataset-metadata) and [Updating File Metadata](https://guides.dataverse.org/en/6.8/api/native-api.html#updating-file-metadata) guides for more details.
 - Changed the way we were handling DATE type metadata field validation to better match the backend validation and give users better error messages. For example, for an input like “foo AD”, we now show “Production Date is not a valid date. The AD year must be numeric.“. For an input like “99999 AD”, we now show “Production Date is not a valid date. The AD year cant be higher than 9999.“. For an input like “[-9999?], we now show “Production Date is not a valid date. The year in brackets cannot be negative.“, etc.
+- The SPA now fetches the runtime configuration from `config.js` on each load, allowing configurations without rebuilding the app. We don't use `.env` variables at build time anymore.
 
 ### Fixed
 

CHANGELOG.md

@@ -54,6 +54,7 @@
             <li><a href="#1-unit-tests-or-component-tests">Unit Tests or Component tests</a></li>
             <li><a href="#2-integration-tests">Integration Tests</a></li>
             <li><a href="#3-end-to-end-e2e-tests">End-to-End (e2e) Tests</a></li>
+            <li><a href="#mocking-runtime-configuration-in-tests">Mocking runtime configuration in tests</a></li>
             <li><a href="#patterns-and-conventions">Patterns and Conventions</a></li>
             <li><a href="#continuous-integration-ci">Continuous Integration (CI)</a></li>
             <li><a href="#test-coverage">Test Coverage</a></li>
@@ -136,12 +137,6 @@ cd packages/design-system && npm run build
 
 **Running &amp; Building the App:**
 
-Set up your environment file.
-
-```bash
-cp .env.example .env
-```
-
 Run the app in the development mode. Open [http://localhost:5173][dv_app_localhost_build_url] to view it in your browser.
 
 ```bash
@@ -826,11 +821,82 @@ describe('Create Dataset', () => {
 
 </details>
 
-> **Note:** Some end-to-end (e2e) tests are failing in local development environments despite passing in GitHub Actions.
-> This discrepancy appears to be due to variations in machine resources.
->
-> We need to investigate and potentially optimize several aspects of our local setup. Check the issue
-> [here](https://github.com/IQSS/dataverse-frontend/issues/371).
+### Mocking runtime configuration in tests
+
+The SPA reads its runtime configuration from `window.__APP_CONFIG__` in `src/config.ts` file, which is provided by `public/config.js`.
+In Cypress tests we bootstrap a test-safe config and allow you to override any field per test.
+
+#### Component (unit) tests: override with Cypress.env
+
+Component tests automatically get a runtime config via the bootstrap file; you only need to set `env` on a per-test basis to customize values.
+
+Example: overriding languages for a component test
+
+```ts
+// tests/component/sections/layout/header/LanguageSwitcher.spec.tsx
+it(
+  'renders language options correctly when more than one language is configured',
+  {
+    env: {
+      languages: [
+        { code: 'en', name: 'English' },
+        { code: 'es', name: 'Español' },
+        { code: 'it', name: 'Italiano' }
+      ]
+    }
+  },
+  () => {
+    cy.customMount(<LanguageSwitcher />)
+    cy.get('#language-switcher-dropdown').click()
+    cy.findByText('English').should('exist')
+    cy.findByText('Español').should('exist')
+    cy.findByText('Italiano').should('exist')
+  }
+)
+```
+
+#### E2E tests: intercept public/config.js
+
+In e2e tests, the app fetches `public/config.js`. Intercept that request and respond with a body built from your `Cypress.env()` settings using the provided helper.
+
+```ts
+// Example e2e spec
+import { buildConfigJsBody } from '../tests/support/bootstrapAppConfig'
+
+it(
+  'test description',
+  {
+    env: {
+      languages: [
+        { code: 'en', name: 'English' },
+        { code: 'it', name: 'Italiano' }
+      ],
+      defaultLanguage: 'en'
+    }
+  },
+  () => {
+    // We intercept config.js request and the body will read from the updated Cypress.env() defined in this test above.
+    cy.intercept(
+      { method: 'GET', url: 'config.js' },
+      {
+        statusCode: 200,
+        headers: { 'content-type': 'application/javascript' },
+        body: buildConfigJsBody()
+      }
+    )
+
+    cy.visit('/spa/')
+
+    // Assertions that rely on your overridden config
+    cy.findByText('English').should('exist')
+    cy.findByText('Italiano').should('exist')
+  }
+)
+```
+
+Notes
+
+- If you don't intercept `config.js` in e2e tests, the app will use the real file from `public/config.js` and ignore your `Cypress.env()` overrides.
 
 ### Patterns and Conventions
 

DEVELOPER_GUIDE.md

@@ -35,6 +35,17 @@ export default defineConfig({
     }
   },
   env: {
+    backendUrl: 'http://localhost:8000',
+    oidcClientId: 'test',
+    oidcAuthorizationEndpoint: 'http://localhost:8000/realms/test/protocol/openid-connect/auth',
+    oidcTokenEndpoint: 'http://localhost:8000/realms/test/protocol/openid-connect/token',
+    oidcLogoutEndpoint: 'http://localhost:8000/realms/test/protocol/openid-connect/logout',
+    oidcLocalStorageKeyPrefix: 'DV_',
+    languages: [
+      { code: 'en', name: 'English' },
+      { code: 'es', name: 'Español' }
+    ],
+    defaultLanguage: 'en',
     codeCoverage: {
       exclude: ['tests/**/*.*', '**/ErrorPage.tsx']
     }