lwc-web-components-interop
LWC interop with non-LWC web components: consuming third-party standard custom elements in LWC, exposing LWC as custom elements externally, Shadow DOM vs native web components, polyfills, and slotting patterns. NOT for LWC-to-LWC composition (use lwc-best-practices). NOT for Aura interop (use aura-to-lwc-migration).
Best use case
lwc-web-components-interop is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
LWC interop with non-LWC web components: consuming third-party standard custom elements in LWC, exposing LWC as custom elements externally, Shadow DOM vs native web components, polyfills, and slotting patterns. NOT for LWC-to-LWC composition (use lwc-best-practices). NOT for Aura interop (use aura-to-lwc-migration).
Teams using lwc-web-components-interop should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/lwc-web-components-interop/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How lwc-web-components-interop Compares
| Feature / Agent | lwc-web-components-interop | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
LWC interop with non-LWC web components: consuming third-party standard custom elements in LWC, exposing LWC as custom elements externally, Shadow DOM vs native web components, polyfills, and slotting patterns. NOT for LWC-to-LWC composition (use lwc-best-practices). NOT for Aura interop (use aura-to-lwc-migration).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# LWC Web Components Interop
Activate when an LWC must consume a third-party standard web component (a custom element defined outside Salesforce's LWC framework) or expose an LWC for external consumption. Web component interop is a supported pattern but full of subtle traps — shadow DOM boundary, event bubbling, styling isolation, and polyfill behavior all differ from plain LWC.
## Before Starting
- **Verify the third-party component is a true custom element.** Many "web components" are React-wrapped; those require a bridge, not direct consumption.
- **Check for Salesforce platform blockers.** Not all JavaScript APIs are available in Lightning Locker / Lightning Web Security context. Test early.
- **Audit the component's CSS approach.** If it ships a global stylesheet, it can clobber SLDS; if it uses shadow DOM, SLDS does not bleed in automatically.
## Core Concepts
### Custom elements in LWC
LWC supports embedding standard custom elements. The element must be defined via `customElements.define()`. LWC renders it like any DOM node; it is the consumer's responsibility to load the definition before first render.
### Static resource loading via loadScript
`loadScript` (from `lightning/platformResourceLoader`) imports a bundled custom element from a Static Resource. The script must call `customElements.define()` with a namespaced tag (e.g., `my-widget`) to avoid collisions across components.
### Shadow DOM boundary
LWC components have shadow DOM. A consumed web component may also have its own shadow DOM → nested shadow roots. Event bubbling respects both boundaries; styles are isolated on each side.
### Events
Third-party web components emit `CustomEvent` on their host. LWC listens via `onmyevent` in template or `this.addEventListener('myevent', ...)` in connectedCallback. Event detail payloads follow CustomEvent spec.
### Lightning Web Security (LWS)
LWS is the successor to Locker. It is more permissive but not unlimited; test custom elements that touch `window`, `document`, timers, or fetch.
## Common Patterns
### Pattern: Consume a Shoelace / Material component inside an LWC
Bundle the component JS as a Static Resource. LWC `connectedCallback` calls `loadScript(this, staticResource)` and renders `<sl-button>` (or equivalent). Events bridged via `addEventListener`.
### Pattern: Wrapper LWC with SLDS theming
An LWC wraps the third-party component, applies SLDS-consistent props, and exposes a simplified API. Rest of the codebase uses the wrapper — changing libraries becomes a wrapper-only change.
### Pattern: Event bridging to LWC events
Third-party component dispatches `CustomEvent('value-change')`. Wrapper LWC catches it and re-dispatches a Salesforce-flavored `CustomEvent('valuechange')` (lowercase, no dashes) for easier consumption in templates.
## Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Need a specific third-party control | Wrapper LWC consuming standard custom element | Native interop |
| Component depends on a heavy framework (React/Vue) | Reconsider — write native LWC or find alternative | Bridge cost exceeds value |
| Styling must match SLDS | Wrapper LWC applies SLDS props or CSS vars | Shadow DOM isolates |
| Multiple LWCs consume same third party | Single Static Resource, one define() call | Prevent collisions |
| Component touches window/document | Test in LWS early | Locker / LWS blocker |
## Recommended Workflow
1. Verify the candidate library is a true standard custom element (no framework wrapper).
2. Prototype in a scratch org: Static Resource + loadScript + render tag.
3. Test in Lightning Web Security context; note any blocked APIs.
4. Build a wrapper LWC with SLDS-consistent props and event bridging.
5. Document the wrapper's public API in JSDoc and in a README.
6. Centralize the Static Resource load (load once per page) to avoid duplicate define() errors.
7. Write LWC jest tests for the wrapper that mock the custom element.
## Review Checklist
- [ ] Third-party component confirmed as standard custom element
- [ ] Static Resource and loadScript pattern consolidated
- [ ] LWS compatibility tested
- [ ] Wrapper LWC provides SLDS-consistent API
- [ ] Events bridged to Salesforce-flavored names
- [ ] jest tests cover wrapper behavior
- [ ] Fallback or error UI if load fails
## Salesforce-Specific Gotchas
1. **customElements.define() is global.** Loading the same library twice on the same page throws "already defined" errors — centralize the load.
2. **Lightning Web Security is not identical to Locker.** Components that worked under Locker may need retesting; some APIs unblock under LWS.
3. **Experience Cloud vs Lightning App context differ.** Static Resources load consistently, but CSP, Locker/LWS, and loader timing can vary — test on every target surface.
## Output Artifacts
| Artifact | Description |
|---|---|
| Wrapper LWC template | JS + HTML + meta for the wrapper |
| Static Resource bundle | Web component JS packaged for Salesforce |
| Event bridging spec | External → Salesforce event names |
| Compatibility report | LWS / Locker blockers per API |
## Related Skills
- `lwc/lwc-best-practices` — baseline LWC patterns
- `lwc/lwc-performance-optimization` — loader optimization
- `integration/integration-pattern-selection` — adjacent choicesRelated Skills
lwc-dynamic-components
Dynamic LWC component creation using the `lwc:component` directive, lazy-loaded dynamic imports (`import()`), and runtime component resolution for conditional rendering at scale. Triggers: 'render different components based on record type', 'dynamically load lwc at runtime', 'lwc:component lwc:is constructor', 'lazy load component only when needed', 'dynamic import lwc'. NOT for static component composition or `lwc:if` conditional rendering when the component set is fixed at build time (use lwc-conditional-rendering).
experience-cloud-lwc-components
Use when building custom LWC components for Experience Cloud (Experience Builder sites, LWR portals, Aura-based communities). Covers community context imports, guest user Apex access patterns, navigation API differences between LWR and Aura, and JS-meta.xml target configuration for Experience Builder exposure. NOT for internal LWC components deployed to Lightning App Builder or standard record pages (see lwc/lwc-development). NOT for Aura community components. Trigger keywords: build LWC for Experience Cloud, custom component community portal LWC, guest user LWC component, community context import salesforce, lightningCommunity target, @salesforce/community, guest Apex.
commerce-lwc-components
Use this skill when building or customizing Lightning Web Components for B2B Commerce or D2C LWR storefronts — product display tiles, cart line-item components, checkout step components, wishlist buttons, and product comparison widgets that rely on Commerce Storefront wire adapters from the commerce namespace. NOT for standard LWC development outside a Commerce store context, not for Aura-based Community Builder components, and not for legacy B2B Commerce (CloudCraze) Aura widgets.
flow-screen-lwc-components
Design custom Lightning Web Components that render inside Screen Flow steps — covers the lightning__FlowScreen target, @api properties as Flow inputs/outputs, FlowAttributeChangeEvent propagation, FlowNavigationNext/Back/Finish/Pause events, the @api validate() hook, and design-time targetConfig wiring. NOT for custom property editors that configure flow elements at design time — see flow-custom-property-editors. NOT for the LWC implementation deep-dive — see lwc/lwc-in-flow-screens.
flow-reactive-screen-components
Build reactive Flow screens where one component updates another without navigation using reactive formulas and component outputs. NOT for Aura-based screens.
analytics-embedded-components
Use this skill when embedding a CRM Analytics dashboard into a Lightning App Builder page, Experience Cloud page, or when embedding a custom LWC inside an Analytics dashboard. Trigger keywords: wave-wave-dashboard-lwc, wave-community-dashboard, analytics__Dashboard target, embed dashboard, record-id context filtering, dashboard state JSON, analytics component. NOT for standard LWC development unrelated to Analytics dashboards, NOT for designing dashboard content or datasets, NOT for CRM Analytics app creation or dataset management.
health-cloud-lwc-components
Use this skill when building custom LWC components for Health Cloud: extending patient card configurations, building custom timeline components using TimelineObjectDefinition metadata, creating care plan visualizations, and surfacing clinical data via LWC. NOT for standard LWC development unrelated to Health Cloud clinical components, or OmniStudio FlexCard development.
xss-and-injection-prevention
Use when writing or reviewing Visualforce pages, Apex controllers, or LWC components that output user-supplied data, build dynamic queries, or construct HTTP responses. Triggers: 'XSS in Visualforce', 'SOQL injection vulnerability', 'how to encode output in Apex', 'JSENCODE Visualforce', 'open redirect prevention'. NOT for Apex CRUD/FLS enforcement (use soql-security or apex-crud-and-fls), NOT for Shield encryption (use shield-encryption-key-management), NOT for AppExchange security review process (use secure-coding-review-checklist).
visualforce-security-and-modernization
Use when hardening or modernizing legacy Visualforce pages — covers the platform CSRF token model and when disabling it is a security regression, view state encryption guarantees and the 170 KB ceiling, FLS/CRUD enforcement gaps on `<apex:outputField>` and on getters that return sObjects, `<apex:includeScript>` interaction with the org Content Security Policy, hosting LWC inside a VF page via `lightning:container` / `lightning-out`, and the retire-vs-harden-vs-leave-alone decision for an inventory of legacy pages. Triggers: 'should I rewrite this Visualforce page in LWC', 'CSRF protection disabled on Visualforce page is that safe', 'community user sees a field they should not on a Visualforce page', 'view state encryption is that enough for sensitive data', 'how do I host an LWC inside a Visualforce page', 'apex:dynamicComponent and apex:actionFunction safe to keep'. NOT for greenfield Visualforce architecture (use apex/visualforce-fundamentals — controller types, view state pattern selection, PDF rendering); NOT for Visualforce email template authoring (use apex/visualforce-email-templates if/when that skill is authored); NOT for general Apex security review across triggers and async (use apex/soql-security and security/secure-coding-review-checklist).
transaction-security-policies
Transaction Security policy creation and configuration: condition builder, enhanced policies, enforcement actions (block, MFA, notification, end session), real-time monitoring mode, and policy troubleshooting. NOT for Event Monitoring log analysis or Shield Event Monitoring setup (use event-monitoring). NOT for Apex testing or debug-log analysis.
sso-saml-troubleshooting
Diagnosing broken SAML SSO into Salesforce — IdP-initiated vs SP-initiated flows, signing-certificate validity / expiry, NameID format mismatches, RelayState handling, audience / entityId / issuer mismatches, clock skew, the SAML Assertion Validator in Setup, the Login History debug log, and the My Domain prerequisite for SSO. Covers the standard diagnostic loop: read the SAML response, identify which check failed, fix at the IdP or SP. NOT for OAuth / OpenID Connect SSO (see security/oauth-openid-troubleshooting), NOT for setting up SSO from scratch (see security/sso-saml-setup).
shield-kms-byok-setup
Configure Shield Platform Encryption with customer-supplied (BYOK) or customer-held (Cache-Only Key Service) tenant secrets, rotate them, and recover. NOT for Classic Encryption or field masking.