App config util (#147)

* initial zod config utility

* Refactor configuration handling: remove ConfigContext and related hooks, update environment variable timestamps to UTC format

* Update testing guidelines: specify test file placement in __tests__ directory

* Add config schema validation tests using Zod

* Enhance configuration access by introducing a type-safe `config` utility with Zod validation for environment variables

Author: mwarman

.env.example

@@ -6,7 +6,7 @@
 ## Provided by Pipeline (Simulated)
 VITE_BUILD_DATE=1970-01-01
 VITE_BUILD_TIME=00:00:00
-VITE_BUILD_TS=1970-01-01T00:00:00+0000
+VITE_BUILD_TS=1970-01-01T00:00:00Z
 VITE_BUILD_COMMIT_SHA=local
 VITE_BUILD_ENV_CODE=local
 VITE_BUILD_WORKFLOW_NAME=local

.github/copilot-instructions.md

@@ -173,7 +173,7 @@ package.json                            # Project dependencies and scripts
 ## Testing Guidelines
 
 - Use **Vitest**.
-- Place test files next to the source file, with `.test.ts` suffix.
+- Place test files in the `__tests__` directory adjacent to the source file, with `.test.ts` suffix.
 - Use Arrange - Act - Assert (AAA) pattern for test structure:
   - **Arrange:** Set up the test environment and inputs.
   - **Act:** Call the function being tested.

.github/workflows/reusable-deploy.yml

@@ -50,7 +50,7 @@ jobs:
           echo "${{ inputs.env_file }}" > .env
           echo "VITE_BUILD_DATE=$(date +'%Y-%m-%d')" >> .env
           echo "VITE_BUILD_TIME=$(date +'%H:%M:%S%z')" >> .env
-          echo "VITE_BUILD_TS=$(date +'%Y-%m-%dT%H:%M:%S%z')" >> .env
+          echo "VITE_BUILD_TS=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> .env
           echo "VITE_BUILD_COMMIT_SHA=${{ github.sha }}" >> .env
           echo "VITE_BUILD_ENV_CODE=${{ inputs.env }}" >> .env
           echo "VITE_BUILD_WORKFLOW_NAME=${{ github.workflow }}" >> .env

docs/CONFIGURATION_GUIDE.md

@@ -42,7 +42,7 @@ The following environment variables are available for configuring the React appl
    ```env
    VITE_BUILD_DATE=2026-02-10
    VITE_BUILD_TIME=14:30:00
-   VITE_BUILD_TS=2026-02-10T14:30:00+0000
+   VITE_BUILD_TS=2026-02-10T14:30:00Z
    VITE_BUILD_COMMIT_SHA=abc123def456
    VITE_BUILD_ENV_CODE=dev
    VITE_BUILD_WORKFLOW_NAME=Build
@@ -52,20 +52,35 @@ The following environment variables are available for configuring the React appl
 
 ### Accessing Configuration
 
-Application configuration values are accessible directly in your React components since Vite automatically injects them:
+Application configuration values are accessed through the `config` utility, which provides type-safe, validated configuration throughout your React components and utilities. The utility validates all environment variables at runtime using Zod schema validation, ensuring type safety and early error detection.
+
+Import the `config` object from the common utilities:
 
 ```typescript
-// API base URL
-const apiUrl = import.meta.env.VITE_BASE_URL_API;
+import { config } from 'common/utils/config';
+
+// API base URL (type-safe string)
+const apiUrl = config.VITE_BASE_URL_API;
 
-// Toast settings
-const toastDuration = import.meta.env.VITE_TOAST_AUTO_DISMISS_MILLIS;
+// Toast settings (type-safe number)
+const toastDuration = config.VITE_TOAST_AUTO_DISMISS_MILLIS;
 
-// Build information
-const buildDate = import.meta.env.VITE_BUILD_DATE;
-const buildCommit = import.meta.env.VITE_BUILD_COMMIT_SHA;
+// Build information (type-safe strings)
+const buildDate = config.VITE_BUILD_DATE;
+const buildCommit = config.VITE_BUILD_COMMIT_SHA;
+const envCode = config.VITE_BUILD_ENV_CODE;
 ```
 
+**Benefits of using the `config` utility:**
+
+- **Type Safety**: All configuration values are validated against a Zod schema, ensuring correct types
+- **Validation**: Environment variables are validated on application startup, catching missing or invalid configuration early
+- **IDE Support**: Full TypeScript autocomplete and type checking for configuration values
+- **Single Source of Truth**: Configuration is centralized and consistently accessed throughout the application
+
+**Configuration Schema Location:**
+The Zod schema that validates all environment variables is defined in [src/common/utils/config.ts](../src/common/utils/config.ts). This file also exports the `Config` type for use in type annotations when needed.
+
 ### Local Development
 
 For local development, create a `.env` file in the root directory with local values:
@@ -75,7 +90,7 @@ VITE_BASE_URL_API=http://localhost:3000
 VITE_TOAST_AUTO_DISMISS_MILLIS=5000
 VITE_BUILD_DATE=1970-01-01
 VITE_BUILD_TIME=00:00:00
-VITE_BUILD_TS=1970-01-01T00:00:00+0000
+VITE_BUILD_TS=1970-01-01T00:00:00Z
 VITE_BUILD_COMMIT_SHA=local
 VITE_BUILD_ENV_CODE=local
 VITE_BUILD_WORKFLOW_NAME=local
@@ -99,7 +114,7 @@ For running unit tests, create a `.env.test.local` file in the root directory wi
    # Provided by Pipeline (Simulated)
    VITE_BUILD_DATE=1970-01-01
    VITE_BUILD_TIME=00:00:00
-   VITE_BUILD_TS=1970-01-01T00:00:00+0000
+   VITE_BUILD_TS=1970-01-01T00:00:00Z
    VITE_BUILD_COMMIT_SHA=test
    VITE_BUILD_ENV_CODE=test
    VITE_BUILD_WORKFLOW_NAME=test
@@ -432,15 +447,19 @@ Ensure all required configuration variables are set as the correct type.
 2. Ensure AWS CLI is configured with `aws configure`
 3. Verify with: `aws sts get-caller-identity`
 
-### Application Build Variables Not Available
+### Application Configuration Validation Error
 
-**Problem**: `import.meta.env.VITE_*` variables are undefined at runtime.
+**Problem**: Application fails to start with a configuration validation error message.
 
 **Solution**:
 
-1. Ensure variables in `.env` are prefixed with `VITE_`
-2. Restart the development server after changing `.env`
-3. Verify with: `echo $VITE_BASE_URL_API`
+1. Ensure all required variables in `.env` are present (see Environment Variables table above)
+2. Ensure variables are prefixed with `VITE_` for Vite compatibility
+3. Restart the development server after changing `.env`
+4. Verify variables are set: `echo $VITE_BASE_URL_API`
+5. The config utility will provide detailed error messages indicating which variables are missing or invalid
+
+**Note**: The application uses the `config` utility from `common/utils/config` which validates all environment variables at startup using Zod schema validation. If any required variables are missing or have invalid values, the application will fail with a clear error message indicating the issue.
 
 ### CDK Configuration Validation Errors
 

src/App.tsx

@@ -4,7 +4,6 @@ import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 
 import ErrorBoundary from 'common/components/Errors/ErrorBoundary';
 import ErrorFallback from 'common/components/Errors/ErrorFallback';
-import ConfigContextProvider from 'common/providers/ConfigProvider';
 import SettingsContextProvider from 'common/providers/SettingsProvider';
 import AxiosContextProvider from 'common/providers/AxiosProvider';
 import { router } from 'common/components/Router/Router';
@@ -33,22 +32,20 @@ function App() {
   return (
     <div id="app" data-testid="app">
       <ErrorBoundary fallback={<ErrorFallback />}>
-        <ConfigContextProvider>
-          <QueryClientProvider client={queryClient}>
-            <SettingsContextProvider>
-              <Theme>
-                <AuthContextProvider>
-                  <AxiosContextProvider>
-                    <ToastsProvider>
-                      <RouterProvider router={router} />
-                    </ToastsProvider>
-                  </AxiosContextProvider>
-                </AuthContextProvider>
-              </Theme>
-              <ReactQueryDevtools initialIsOpen={false} />
-            </SettingsContextProvider>
-          </QueryClientProvider>
-        </ConfigContextProvider>
+        <QueryClientProvider client={queryClient}>
+          <SettingsContextProvider>
+            <Theme>
+              <AuthContextProvider>
+                <AxiosContextProvider>
+                  <ToastsProvider>
+                    <RouterProvider router={router} />
+                  </ToastsProvider>
+                </AxiosContextProvider>
+              </AuthContextProvider>
+            </Theme>
+            <ReactQueryDevtools initialIsOpen={false} />
+          </SettingsContextProvider>
+        </QueryClientProvider>
       </ErrorBoundary>
     </div>
   );

src/common/api/useGetUser.ts

@@ -1,7 +1,7 @@
 import { UseQueryResult, useQuery } from '@tanstack/react-query';
 
 import { useAxios } from 'common/hooks/useAxios';
-import { useConfig } from 'common/hooks/useConfig';
+import { config } from 'common/utils/config';
 import { QueryKey } from 'common/utils/constants';
 
 /**
@@ -56,7 +56,6 @@ interface UseGetUserProps {
  */
 export const useGetUser = ({ userId }: UseGetUserProps): UseQueryResult<User, Error> => {
   const axios = useAxios();
-  const config = useConfig();
 
   const getUser = async (): Promise<User> => {
     const response = await axios.request({

src/common/components/Toast/Toast.tsx

@@ -5,8 +5,8 @@ import { cva, VariantProps } from 'class-variance-authority';
 
 import { cn } from 'common/utils/css';
 import { BaseComponentProps } from 'common/utils/types';
+import { config } from 'common/utils/config';
 import { ToastDetail } from 'common/providers/ToastsContext';
-import { useConfig } from 'common/hooks/useConfig';
 import Button from 'common/components/Button/Button';
 import FAIcon from 'common/components/Icon/FAIcon';
 
@@ -48,8 +48,6 @@ export interface ToastProps extends BaseComponentProps {
  * used when some adverse action happens, such as an error.
  */
 const Toast = ({ className, dismiss, testId = 'toast', toast }: ToastProps) => {
-  const config = useConfig();
-
   const [springs, api] = useSpring(() => ({
     from: { opacity: 1, x: 0 },
   }));
@@ -74,7 +72,7 @@ const Toast = ({ className, dismiss, testId = 'toast', toast }: ToastProps) => {
 
       return () => clearInterval(dismissInterval);
     }
-  }, [toast, config.VITE_TOAST_AUTO_DISMISS_MILLIS]);
+  }, [toast]);
 
   return (
     <animated.div

src/common/components/Toast/__stories__/Toast.stories.tsx

@@ -1,7 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import dayjs from 'dayjs';
 
-import ConfigContextProvider from 'common/providers/ConfigProvider';
 import { ToastDetail } from 'common/providers/ToastsContext';
 
 import Toast from '../Toast';
@@ -11,10 +10,8 @@ const meta = {
   component: Toast,
   decorators: [
     (Story) => (
-      <div className="w-[480px]">
-        <ConfigContextProvider>
-          <Story />
-        </ConfigContextProvider>
+      <div className="w-120">
+        <Story />
       </div>
     ),
   ],