lwc-vs-react

You are picking the frontend framework. Salesforce now supports native React on the platform alongside LWC; both are first-class. The choice depends on the surface, the team's expertise, and the depth of integration with Salesforce-native primitives.

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
FRONTEND="$(sf_config_get '.platform.frontend // \"lwc\"' "$ENV")"

If platform.frontend = "lwc", this skill defaults to LWC and only recommends React if the user explicitly opts in (which would require also flipping the config). If platform.frontend = "react" or "both", both options are live.

Input

$ARGUMENTS:

• (empty) — interactive Q&A
• <one-line description> — concrete component context
• --non-interactive answers="..." — scripted

Decision questions

1. What surface? Record page / App Builder / Experience Cloud / hosted outside the org?
2. Salesforce-native data? getRecord, getObjectInfo, picklist values, etc.?
3. Complex client interactivity? Drag-drop, rich-text editing, charts, multi-step forms?
4. Team expertise? Mostly LWC / mostly React / mixed?
5. Reuse? Does the project already have shared LWC components this would extend? Or shared React components?
6. External libraries needed? Charts, editors, design-system imports outside SLDS?
7. Mobile / embedded? Salesforce mobile app, embedded portal, custom domain?

Decision tree

Record page placement, single-record focus
  → LWC
    `@wire(getRecord)` is built-in; SLDS-native record-page UX

App Builder + simple reusable widget
  → LWC
    Lower bundle weight; well-trodden path

Complex interactive UI (drag-drop, multi-step wizard, rich editor, charts)
  AND React expertise on the team
  → React (RX-1 GraphQL fetch, RX-4 SLDS via tokens, RX-6 LWC interop if needed)

Existing project is mostly React; new surface
  → React (avoid mixing if you don't have to)

Mobile-first / hosted outside the org
  → React typically wins (server-side rendering, hydration story)

Quick admin tool / internal-only / one-shot
  → LWC
    LWC's tooling is faster for "throw together a quick tool"

Heavy third-party libs (Material UI, Three.js, Monaco editor)
  → React (LWC's module system is more constrained)

Mixing — incremental migration of an Aura/legacy app
  → Both, with RX-6 LWC<->React interop primitives

Output

# Choice: <one-line description>

## Answers
- Surface:           Experience Cloud landing page
- Salesforce-native data: light (member count, latest bulletins via GraphQL)
- Interactivity:     moderate (filtering, infinite scroll on bulletin feed)
- Team:              mixed (3 React, 2 LWC)
- Reuse:             no shared components on this surface yet
- External libs:     react-virtual (for the feed virtualization)
- Mobile:            yes — responsive design, embedded in the member portal app

## Recommendation: **React** (RX-1 + RX-4 + SF-19)

### Why
- Embedded in the member portal mobile app — React's hydration story is cleaner than LWC's mobile package
- Virtualization needed (>500 bulletins potentially) — `@tanstack/react-virtual` is well-tested; LWC has no equivalent first-party
- Mixed team with React majority — going LWC here forces the React engineers to context-switch; cost > the ~20% bundle-size savings LWC would offer
- `@salesforce/react/graphql` covers the data needs (RX-1); FLS auto-enforced

### Implementation outline
- /argo:react-init BulletinFeed --type page
- @react-dev: implement with useQuery + useVirtualizer
- @qa: tests via Vitest + RTL (@react-dev's scaffold provides 4 starter cases)
- Deploy via /argo:diff-deploy (handles React bundles same as LWC)

### Patterns referenced
- RX-1 (Platform GraphQL fetch)
- RX-4 (SLDS via React tokens)
- RX-5 (i18n for date formatting on bulletins)
- SF-19 (virtualized list — same threshold as LWC; React lib differs)

### Alternatives considered
- **LWC**: would work; ~30% smaller bundle. The interactivity is doable but the team mismatch makes ongoing iteration slower
- **Plain HTML page**: no — need real-time filtering and the GraphQL bindings save a lot of code

Rules

• Don't mix unnecessarily. If the project is LWC, default to LWC. If React, default to React. Mixing has bundle-size and mental-model cost
• Default toward LWC for record-page placements. @wire(getRecord) is hard to beat when you're literally on a record page
• Default toward React when external libs dominate. If the bulk of the component is third-party (a chart lib, an editor), React's npm tooling is friendlier
• Show the migration path. When recommending a switch (LWC → React or vice versa), mention RX-6 interop so the user knows incremental migration is possible
• Don't predict team preference. Ask question #4 explicitly; don't assume

Consumers

• @architect invokes this when planning a new UI surface
• /argo:adr captures the decision; future teammates know why
• @lwc-dev and @react-dev accept the recommendation and proceed