afv-library/samples/webapp-template-app-react-sample-b2x-experimental/.a4drules/webapp-react.md

description	paths
React-specific patterns and Salesforce data access for SFDX web apps	force-app/main/default/webapplications/**/*

React Web App (SFDX)

React-specific guidelines for data access, component library, and Salesforce integration.

For layout, navigation, and generation rules, see webapp.md.

Project Structure

• Web app root: force-app/main/default/webapplications/<appName>/
• Entry: src/app.tsx
• Layout shell: src/appLayout.tsx
• Dev server: npm run dev
• Build: npm run build

Component Library (MANDATORY)

Use shadcn/ui for UI components:

import { Button } from '@/components/ui/button';
import { Card, CardHeader, CardContent } from '@/components/ui/card';
import { Input } from '@/components/ui/input';

Styling

• Use Tailwind CSS utility classes
• Follow consistent spacing, color, and typography conventions

Module & Platform Restrictions

React apps must NOT import Salesforce platform modules:

• ❌ @salesforce/* (except @salesforce/sdk-data)
• ❌ lightning/*
• ❌ @wire (LWC-only)

Use standard web APIs and npm packages only.

Data Access (CRITICAL)

Use DataSDK for All Salesforce API Calls

import { getDataSDK } from '@salesforce/sdk-data';

const sdk = await getDataSDK();
// Use sdk.graphql?.() or sdk.fetch!() for API calls

Do NOT use axios or raw fetch for Salesforce APIs. The SDK handles authentication and CSRF.

Data Access Priority

1. GraphQL (preferred) — queries & mutations via sdk.graphql?.()
2. UI API — via sdk.fetch!() for /services/data/v62.0/ui-api/*

Apex REST is NOT Available

Apex REST cannot be called from React applications. If Apex seems required:

1. Evaluate if GraphQL can accomplish the task
2. If not, inform the user the feature is not supported in React

MCP Tool Integration

Before implementing data access:

1. Check if orchestrate_lds_data_requirements tool is available
2. Use it to get guidance on the appropriate pattern (GraphQL or UI API)
3. If it recommends Apex REST, ignore and use GraphQL instead

Einstein LLM Gateway (AI Features)

import { getDataSDK } from '@salesforce/sdk-data';

async function callEinsteinGenerations(prompt: string): Promise<string> {
  const sdk = await getDataSDK();
  const resp = await sdk.fetch!('/services/data/v62.0/einstein/llm/prompt/generations', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      additionalConfig: { applicationName: 'PromptTemplateGenerationsInvocable' },
      promptTextorId: prompt,
    }),
  });

  if (!resp.ok) throw new Error(`Einstein LLM failed (${resp.status})`);
  const data = await resp.json();
  return data?.generations?.[0]?.text || '';
}

Error Handling

async function safeFetch<T>(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn();
  } catch (err) {
    console.error('API Error:', err);
    throw err;
  }
}

Authentication Errors

On 401/403 response, trigger page refresh to redirect to login:

window.location.reload();

Security Standards

• Validate user permissions before data operations
• Respect record sharing rules and field-level security
• Never hardcode credentials or secrets
• Sanitize all user inputs
• Use HTTPS for all API calls

Performance

• Use React Query or RTK Query for caching API data
• Use React.memo, useMemo, useCallback where appropriate
• Implement loading and error states

Anti-Patterns (FORBIDDEN)

• ❌ Calling Apex REST from React
• ❌ Using axios or raw fetch for Salesforce APIs
• ❌ Direct DOM manipulation in React
• ❌ Using LWC patterns (@wire, LDS) in React
• ❌ Hardcoded Salesforce IDs or URLs
• ❌ Missing error handling for async operations

Quality Checklist

• Entry point maintained (app.tsx)
• Uses shadcn/ui and Tailwind
• DataSDK used for all Salesforce API calls
• Proper error handling with try/catch
• Loading and error states implemented
• No hardcoded credentials or IDs