afv-library/skills/managing-webapp-agentforce-conversation-client/references/constraints.md

Constraints and Anti-Patterns

This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.

Never Edit Implementation Files

CRITICAL: Only edit files where the component is USED, never the component implementation itself.

• ✅ DO edit: Any React files that import and use <AgentforceConversationClient /> (for example, shared shells, route components, or feature pages)
• ❌ DO NOT edit: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
  • node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/
  • packages/template/feature/feature-react-agentforce-conversation-client/src/
  • src/components/AgentforceConversationClient.tsx (patched templates)
  • Any path containing /components/AgentforceConversationClient.

If you're reading a file named AgentforceConversationClient.tsx, you're in the wrong place. Stop and search for the USAGE instead.

Invalid Props

AgentforceConversationClient uses a flat prop API and does NOT accept these props:

• ❌ containerStyle - Use width and height props directly instead
• ❌ style - Use styleTokens for theming
• ❌ className - Not supported
• ❌ Any standard React div props - This wraps an embedded iframe, not a div

Why: The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.

Invalid Styling Approaches

CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use styleTokens prop.

Never use these approaches:

• ❌ Creating CSS files (e.g., agent-styles.css, theme.css)
• ❌ Creating <style> tags or internal stylesheets
• ❌ Using style attribute on the component
• ❌ Using className prop
• ❌ Inline styles
• ❌ CSS modules
• ❌ Styled-components or any CSS-in-JS libraries

Why: The component controls its own internal styling through the styleTokens API. External CSS cannot reach into the embedded iframe.

Invalid Implementation Approaches

Never do these:

• ❌ Create custom chat UIs from scratch
• ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
• ❌ Call embedAgentforceClient directly from @salesforce/agentforce-conversation-client
• ❌ Build custom WebSocket or REST API chat implementations

Why: The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.

Invalid Update Patterns

When updating an existing component:

• ❌ Delete and recreate the component
• ❌ Remove all props and start over
• ❌ Copy the entire component to a new file

Why: This loses configuration, introduces errors, and creates unnecessary diffs. Always update props in place.

Examples

❌ Wrong - Using containerStyle

<AgentforceConversationClient agentId="0Xx..." containerStyle={{ width: 420, height: 600 }} />

✅ Correct - Using width/height directly

<AgentforceConversationClient agentId="0Xx..." width="420px" height="600px" />

❌ Wrong - Creating CSS file

/* agent-styles.css */
.agentforce-chat {
  background: red;
  color: white;
}

import "./agent-styles.css";

<AgentforceConversationClient className="agentforce-chat" />;

✅ Correct - Using styleTokens

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "red",
    headerBlockTextColor: "white",
  }}
/>

❌ Wrong - Creating style tag

<>
  <style>{`.agent-chat { background: blue; }`}</style>
  <AgentforceConversationClient agentId="0Xx..." />
</>

✅ Correct - Using styleTokens

<AgentforceConversationClient
  agentId="0Xx..."
  styleTokens={{
    headerBlockBackground: "blue",
  }}
/>

❌ Wrong - Editing implementation file

Reading or editing: node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx

✅ Correct - Editing usage file

Reading and editing: usage files where the component is imported and used (for example, src/app.tsx, a route component, or a feature page)