writing-typescript-code（writing TypeScript 代码）

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

frontend/.npmrc sets legacy-peer-deps=true automatically — no flag needed when running from frontend/.

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

Example: @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, verify with:

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

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 outside frontend/ (misses .npmrc config)
• ❌ 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 AgentChat.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