frontend-implementation

Frontend Implementation — Skill

When to use / when NOT to use

Use this skill when:

• Implementing React 18 UI components in TypeScript 5 with strict mode.
• Creating a typed API client to consume Spring Boot REST APIs.
• Implementing client-side validation, error and loading states, and accessibility.
• Propagating correlation IDs from backend to frontend and logging client-side events.
• Preparing UI for integration and E2E tests (Test Automation will wire Selenium).

Do NOT use this skill for:

• Backend implementation details (use spring-boot-implementation).
• Test execution infrastructure (use test-automation).
• Deployment manifests (use deployment-cicd).

Required inputs

Before you begin, have ready:

1. OpenAPI or API contract for the endpoints the UI will call.
2. Authentication strategy and token acquisition flow (should not embed secrets in code).
3. UX acceptance criteria and accessibility requirements.
4. Design tokens or theme guidance (colors, spacing) if available.
5. CORS and API base URL configuration for environments.

Step-by-step procedure

1. Project setup and TypeScript config

   • Ensure tsconfig.json has "strict": true enabled and target set to ES2022 or later.
   • Use React 18, TypeScript 5, and prefer Vite or Create React App as approved by your team.
   • Do not store secrets in client code; use OAuth/OIDC implicit or authorization code flow via secure cookies or short-lived tokens.

2. Build a typed API client (contract-first)

   • Use the OpenAPI contract to generate types where possible (openapi-generator or manual types).
   • Wrap HTTP calls in a small, typed client that handles correlation IDs, retries, and transforms ProblemDetail errors into typed objects.
   • Centralize base URL and headers via environment variables injected at build/deploy time (never checked into source with secrets).

3. Implement function components with hooks

   • Use function components + hooks (no class components).
   • Keep components small and focused; prefer composition over large, stateful components.
   • Use useEffect for side effects, useCallback and useMemo for stable handlers and derived data.
   • Propagate and display loading and error states; ensure accessibility (aria-live for messages).

4. State management

   • For local UI state use useState and useReducer where appropriate.
   • For shared state, prefer React Context or a lightweight state library; avoid over-architecting with global stores unless justified.
   • Keep server state in sync with API client and cache client-side only for UX improvements.

5. Error handling and observability

   • Convert RFC 7807 ProblemDetail responses into a UI-friendly Problem object and display sanitized messages.
   • Attach correlation IDs to outgoing requests and display them in error UI to help cross-team debugging.
   • Use client-side structured logging (console with JSON or a logging library) to include correlationId, userId (if available), and component context.

6. Security and input validation

   • Validate inputs on the client for UX, but always validate on the server.
   • Never store tokens or secrets in source code; use HttpOnly cookies for tokens where possible.
   • Sanitize user-provided HTML and user input to prevent XSS.

7. Accessibility and testing readiness

   • Use semantic HTML and ARIA attributes for interactive controls.
   • Ensure components expose stable selectors (data-testid or data-e2e) for E2E tests; avoid brittle CSS/XPath selectors.
   • Provide example fixtures that Test Automation can use for Selenium page objects.

Production standards checklist

• TypeScript strict mode enabled
• Function components + hooks used (no class components)
• Typed API client with request/response types and ProblemDetail handling
• Correlation ID propagated in requests and included in logs/UI errors
• No secrets in repository; tokens handled securely (HttpOnly cookies or secure storage)
• Accessible components (ARIA, keyboard navigation, semantic markup)
• Stable selectors for E2E tests (data-testid or data-e2e attributes)
• Input validation and sanitization implemented on the client (server-side validation still required)
• Error & loading states displayed and tested
• Observability: structured client logs with correlationId and metrics where applicable

GOOD vs BAD examples

BAD: Un-typed fetch, no error handling, leaks config

// ❌ Bad: untyped, no error handling, base URL in code
export async function fetchOrders(customerId) {
  const res = await fetch('http://localhost:8080/api/v1/orders?customerId=' + customerId);
  const body = await res.json();
  return body.data;
}

GOOD: Typed API client with axios, ProblemDetail handling, correlation ID

// templates/typed-api-client.ts (bundled)
import axios, { AxiosError, AxiosInstance } from 'axios';

export interface ProblemDetail {
  type?: string;
  title?: string;
  status?: number;
  detail?: string;
  instance?: string;
  correlationId?: string;
  timestamp?: string;
}

export interface OrderItem {
  productId: string;
  quantity: number;
  unitPrice: number;
}

export interface OrderResponse {
  id: string;
  customerId: string;
  totalPrice: number;
  status: string;
  items: OrderItem[];
  correlationId?: string;
}

export class ApiClient {
  private readonly http: AxiosInstance;

  constructor(baseUrl: string) {
    this.http = axios.create({ baseURL: baseUrl, timeout: 5000 });

    // Attach correlation ID header to every request if present in local context
    this.http.interceptors.request.use(config => {
      const correlationId = (window as any).__CORRELATION_ID__ || undefined;
      if (correlationId) {
        config.headers = { ...config.headers, 'X-Correlation-ID': correlationId };
      }
      return config;
    });

    this.http.interceptors.response.use(
      r => r,
      (error: AxiosError) => {
        if (error.response && error.response.data) {
          const pd = error.response.data as ProblemDetail;
          // Normalize server ProblemDetail into a typed rejection
          return Promise.reject(pd);
        }
        return Promise.reject(error);
      }
    );
  }

  async listOrders(customerId: string): Promise<OrderResponse[]> {
    const res = await this.http.get<{ data: OrderResponse[] }>(`/api/v1/orders`, {
      params: { customerId }
    });
    return res.data.data;
  }
}

BAD: Component that swallows errors and has no types

// ❌ Bad: any types, no loading state, no error display
export const OrderList = ({ customerId }: any) => {
  const [orders, setOrders] = useState<any[]>([]);
  useEffect(() => {
    fetch(`/api/v1/orders?customerId=${customerId}`)
      .then(r => r.json())
      .then(d => setOrders(d.data))
      .catch(() => {});
  }, [customerId]);

  return <div>{orders.map(o => <div key={o.id}>{o.id}</div>)}</div>;
};

GOOD: Typed component with loading/error states and accessible markup

// templates/react-component.md (bundled)
import React, { useEffect, useState } from 'react';
import { ApiClient, OrderResponse, ProblemDetail } from './typed-api-client';

const api = new ApiClient(import.meta.env.VITE_API_BASE_URL || 'http://localhost:8080');

export const OrderList: React.FC<{ customerId: string }> = ({ customerId }) => {
  const [orders, setOrders] = useState<OrderResponse[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<ProblemDetail | null>(null);

  useEffect(() => {
    let mounted = true;
    setLoading(true);
    api.listOrders(customerId)
      .then(data => {
        if (!mounted) return;
        setOrders(data);
        setError(null);
      })
      .catch((pd: ProblemDetail) => {
        if (!mounted) return;
        setError(pd);
      })
      .finally(() => {
        if (!mounted) return;
        setLoading(false);
      });

    return () => { mounted = false; };
  }, [customerId]);

  if (loading) return <div role="status">Loading orders…</div>;
  if (error) return <div role="alert">Error: {error.detail} (ID: {error.correlationId})</div>;

  return (
    <ul aria-live="polite">
      {orders.map(o => (
        <li key={o.id} data-e2e={`order-${o.id}`}>
          <strong>{o.id}</strong> — ${o.totalPrice.toFixed(2)}
        </li>
      ))}
    </ul>
  );
};

Definition of Done

The frontend feature is complete when:

• Components are typed and tsc passes with strict enabled.
• Typed API client exists and maps ProblemDetail to UI errors.
• Correlation ID is propagated in requests and surfaced in error UI.
• No secrets or tokens are stored in repo source files.
• Accessibility checks pass (basic keyboard and screen reader smoke tests).
• E2E selectors (data-e2e) are present and stable for Test Automation.
• Peer review completed and acceptance criteria satisfied.

Bundled resources

• templates/typed-api-client.ts — Typed Axios-based API client (see GOOD example above).
• templates/react-component.md — Typed React component skeleton with loading/error states.
• templates/security-guidelines.md — Frontend-specific security practices (no secrets, XSS prevention).

Last updated: 2026-07-04