TypeScript Coding Standards

Goal: Write type-safe React components with proper MSAL integration

Hot Module Replacement (HMR) Workflow

The frontend runs with Vite HMR. When you edit TypeScript/React code:

1. •Save the file - Vite instantly updates the browser (no refresh needed)
2. •Check the terminal - Look for HMR updates in the "Frontend: React Vite" terminal
3. •State is preserved - React state persists through most edits

VS Code Tasks (use Run Task command or check terminal panel):

• •Frontend: React Vite - Runs npm run dev with HMR enabled
• •Logs are visible directly in VS Code terminal

No restart needed - Just edit, save, and see changes instantly in the browser.

Testing changes: Use Playwright browser tools to:

• •Navigate to http://localhost:5173
• •Check browser console logs for state transitions and errors
• •Inspect network requests for API validation

TypeScript Config

Enable strict mode + explicit types (avoid any):

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

React Components

Use functional components + hooks + typed props:

interface MessageProps {
  message: string;
  sender: 'user' | 'agent';
}

function Message({ message, sender }: MessageProps) {
  return <div className={`msg-${sender}`}>{message}</div>;
}

MSAL Pattern

Always: Try silent first, fallback to popup:

try {
  const { accessToken } = await instance.acquireTokenSilent({
    ...tokenRequest,
    account: accounts[0]
  });
  return accessToken;
} catch {
  const { accessToken } = await instance.acquireTokenPopup(tokenRequest);
  return accessToken;
}

Environment Variables

CRITICAL: Access at module level only (build-time replacement):

// ✅ Correct - module level
const clientId = import.meta.env.VITE_ENTRA_SPA_CLIENT_ID;

// ❌ Wrong - inside function (won't work after build)
function getClientId() {
  return import.meta.env.VITE_ENTRA_SPA_CLIENT_ID;
}

Available variables:

• •VITE_ENTRA_SPA_CLIENT_ID - Entra app client ID
• •VITE_ENTRA_TENANT_ID - Azure tenant ID

State Management

Use useState (local) or Context API (shared):

const [messages, setMessages] = useState<Message[]>([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState<Error | null>(null);

Memoization Patterns

Use useMemo and useCallback for expensive computations and stable references:

// Memoize computed values
const isAuthenticated = useMemo(
  () => accounts.length > 0,
  [accounts.length]
);

// Memoize callbacks to prevent child re-renders
const getAccessToken = useCallback(async () => {
  // ... token acquisition logic
}, [instance, accounts]);

// Return memoized object for stable reference
return useMemo(
  () => ({ getAccessToken, isAuthenticated, user }),
  [getAccessToken, isAuthenticated, user]
);

API Calls

Include Authorization header + use async/await:

const response = await fetch('/api/endpoint', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

if (!response.ok) throw new Error(`API error: ${response.status}`);

npm Dependencies

React 19: Use --legacy-peer-deps flag:

npm install --legacy-peer-deps

IMPORTANT: --legacy-peer-deps skips automatic peer dependency installation. If a package requires peer dependencies, you must add them explicitly to package.json.

Example: @fluentui-copilot/react-copilot → @lexical/react → @lexical/yjs requires yjs as a peer dependency. Since peer deps aren't auto-installed, yjs must be in package.json directly.

Before committing package changes, always verify with:

npm ci  # Fails if lock file is out of sync with package.json

If npm ci fails with "Missing: <package> from lock file", add the missing package explicitly to package.json and run npm install --legacy-peer-deps again.

Common Mistakes

• •❌ Accessing import.meta.env.* in functions
• •❌ Calling hooks conditionally or in loops
• •❌ Using any type
• •❌ Storing tokens in component state
• •❌ Running npm install without --legacy-peer-deps
• •❌ Missing memoization in custom hooks (causes infinite re-renders)
• •❌ Returning new objects from hooks without useMemo

Project-Specific: Architecture

Project-Specific: Key Components

Project-Specific: Citation System

Parser: frontend/src/utils/citationParser.ts

Handles Azure AI Agent citation formats:

• •Assistants/Responses API: 【4:0†source】, 【13†myfile.pdf】
• •Azure OpenAI On Your Data: [doc1], [doc2]

Flow:

1. •parseContentWithCitations() replaces placeholders with [N] markers
2. •Markdown.tsx renders CitationMarker components for each [N]
3. •Clicking inline marker scrolls to footnote (with highlight animation) or opens URL
4. •AssistantMessage.tsx renders footnote list with icons by type (URI/file/document)

Key Types (frontend/src/types/chat.ts):

• •IAnnotation - Citation metadata (type, label, url, fileId, quote, textToReplace)
• •IndexedCitation - Parsed citation with display index

Project-Specific: File Upload Validation

Limits: 5MB per file, max 5 files total

See: frontend/src/utils/fileAttachments.ts for validateImageFile() and validateFileCount()

Project-Specific: ChatService

File: frontend/src/services/chatService.ts

Key patterns:

• •Class-based service with Dispatch<AppAction> for state updates
• •AbortController for stream cancellation (cancelStream())
• •retryWithBackoff() for resilient API calls (3 retries, 1s initial delay)
• •SSE parsing via parseSseLine() and splitSseBuffer() utilities
• •Duplicate chunk suppression to prevent UI flicker

Methods:

Project-Specific: Adding Features

1. •Extend state: Add discriminated action to AppAction union in frontend/src/types/appState.ts
2. •Handle in reducer: Update frontend/src/reducers/appReducer.ts (keep pure, no side effects)
3. •Create service method: Add to ChatService if network interaction needed
4. •Wire container: Update AgentPreview.tsx to dispatch actions
5. •Update UI: Pass callbacks to controlled component

Project-Specific: Accessibility Checklist

• •✅ Live region announces latest assistant message
• •✅ aria-busy attribute on messages container during streaming
• •✅ Buttons have aria-label when icon-only
• •✅ Focus returns to input after sending
• •✅ Character counter linked via aria-describedby

Related Skills

• •implementing-chat-streaming - SSE streaming patterns and frontend state flow
• •troubleshooting-authentication - MSAL popup issues and token debugging
• •testing-with-playwright - Browser testing and accessibility validation