Skip to main content
skill CX Codex

experience-lwc-legacy-migrate — Claude Code skill: install & guide

experience-lwc-legacy-migrate verifies Aura to LWC migration completeness and upgrades legacy Lightning Out Beta host pages to Lightning Out 2.0 with OAuth PKCE.

Apache-2.0 245 installs ★ 1,183 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add forcedotcom/sf-skills --skill experience-lwc-legacy-migrate -a claude-code
Open on GitHub

What experience-lwc-legacy-migrate does

The skill handles two distinct workflows. First, it audits already converted Aura components across 12 dimensions, including event handling, security, and Jest test coverage. Each metric receives a rating from Excellent to Missing. It does not perform the initial Aura-to-LWC conversion itself, which requires experience-aura-lwc-migrate.

Second, it guides the transition from lightning.out.js to Lightning Out 2.0. This replaces $Lightning.use() calls with the <lightning-out-application> tag and swaps static tokens for OAuth PKCE. Built-in Python scripts handle name conversion and page validation. You will need python3 (>=3.8) and a Salesforce External Client App Consumer Key before running the workflow.

What it helps with

  • audit an Aura-to-LWC conversion across 12 completeness dimensions
  • migrate external host pages from Lightning Out Beta to LO 2.0
  • replace legacy $Lightning.use() calls with <lightning-out-application>
  • switch hardcoded Lightning Out tokens to OAuth PKCE flows

Example prompts for the agent

  • Verify Aura to LWC migration completeness for component accountTile
  • Migrate Lightning Out Beta host page index.html to LO 2.0
  • Validate my migrated LO 2.0 page against the core rules

How to install experience-lwc-legacy-migrate

1Skills CLI (Vercel)

npx skills add forcedotcom/sf-skills --skill experience-lwc-legacy-migrate -a claude-code

2Manually: put the files in place

~/.claude/skills/experience-lwc-legacy-migrate/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/experience-lwc-legacy-migrate/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about experience-lwc-legacy-migrate

How do I install experience-lwc-legacy-migrate in Claude Code?

Run npx skills add forcedotcom/sf-skills --skill experience-lwc-legacy-migrate -a claude-code in your terminal.

Does this skill convert Aura components to LWC from scratch?

No, it only verifies completeness after the conversion is done. For the initial code conversion, use the experience-aura-lwc-migrate skill.

What are the prerequisites for the Lightning Out 2.0 migration?

You need python3 version 3.8 or higher, access to the host page source, and an External Client App with a Consumer Key set up in Salesforce.

Source text

SKILL.md · Apache-2.0
---
name: experience-lwc-legacy-migrate
description: "Migrate legacy Salesforce UI stacks onto modern LWC — Aura → LWC conversion completeness verification and Lightning Out Beta → Lightning Out 2.0 host-page migration. TRIGGER on \"verify Aura to LWC migration completeness\", \"migrate Lightning Out Beta to LO 2.0\", \"upgrade $Lightning.use() to <lightning-out-application>\", \"replace hardcoded LO tokens with OAuth PKCE\", \"write an LO 2.0 host page\", or an external Lightning Out page that stopped rendering; also `.cmp`/`.js-meta.xml` files alongside LWC. DO NOT TRIGGER for the initial Aura-to-LWC conversion (use experience-aura-lwc-migrate), a React-to-LWC migration, or building a new LWC (use experience-lwc-design-generate)."
metadata:
  version: "1.0"
  domains: ["Experience"]
  relatedSkills:
    - "experience-aura-lwc-migrate"
    - "experience-lwc-design-generate"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.8"
---
<!-- adk-managed-skill -->

# Migrating Legacy LWC Stacks

Two distinct migration workflows live here because users in the middle of
migrating Aura components are often also migrating Lightning Out host pages
— they benefit from one skill that knows both.

| Migration                          | Use when                                               | Reference                                                                                              |
|------------------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Aura → LWC completeness check      | An Aura component was converted, verify nothing is lost | [aura-to-lwc-completeness-checklist.md](references/aura-to-lwc-completeness-checklist.md)              |
| Lightning Out Beta → LO 2.0        | Migrating an external host page off `lightning.out.js`  | [lightning-out-beta-to-2-migration.md](references/lightning-out-beta-to-2-migration.md)                |

## When to Use This Skill

- User has already converted an Aura component to LWC and wants a structured
  completeness check.
- User has a non-Salesforce host page that embeds Salesforce LWC via
  Lightning Out Beta and needs to move to LO 2.0.
- User is upgrading `$Lightning.use()` / `$Lightning.createComponent()` calls
  to the `<lightning-out-application>` web component pattern.
- User needs to replace a hardcoded LO auth token with OAuth PKCE + front-door
  flow.

If the user wants to build a brand-new LO 2.0 host page from scratch (no Beta
code to migrate), the LO 2.0 system reference inside this skill is still the
right source of truth — point them at it directly.

## Prerequisites

- Access to the source (Aura component files or Beta host page).
- For LO 2.0 migration: ability to create an External Client App (ECA) in
  Salesforce Setup (Consumer Key required) and optionally a Lightning Out 2.0
  App (18-char App ID).
- For Aura migration: access to the LWC conversion, including any `__tests__`
  (Jest) and `__utam__` (UTAM) folders if they exist.


## Workflow A — Aura → LWC Completeness Check

Goal: rate an already-done Aura-to-LWC conversion across 12 dimensions and
produce actionable recommendations.

### Step A1 — Identify the component

Ask the user for the component name (e.g. `accountTile`). Locate the Aura
source (`{componentName}.cmp`, controller, helper, CSS) and the LWC output
(`{componentName}.html`, `.js`, `.css`, `.js-meta.xml`).

### Step A2 — Run the checklist

Follow [aura-to-lwc-completeness-checklist.md](references/aura-to-lwc-completeness-checklist.md)
verbatim:

- Score the conversion on all 12 metrics (Functional Parity, Event Handling,
  Data Binding & State, UI/UX Parity, Extensibility & Modularity, Error
  Handling, Localization, Security & Access Control, Performance, Salesforce
  Best Practices, Jest Test Coverage, UTAM Page Objects).
- Use the six-rating scale: Excellent / Good / Satisfactory / Limited / Poor
  / Missing.
- Present the output as a list (not a table), per the reference.

### Step A3 — Summarize + recommend

End with an overall confidence statement and a prioritized list of specific,
actionable recommendations (what to fix, in what order).


## Workflow B — Lightning Out Beta → LO 2.0

Goal: transform a Lightning Out Beta host page into a Lightning Out 2.0 host
page while leaving the customer's HTML structure, styling, and business logic
intact.

### Step B1 — Read the LO 2.0 mental model

Internalize the architecture *before* editing code:
[lightning-out-2-system-reference.md](references/lightning-out-2-system-reference.md).

Key takeaway: LO 2.0 is not a library upgrade. It runs the LWC inside an
iframe with a closed shadow DOM — host-page JS cannot touch the LWC and
vice versa, and host-page CSS does not cascade in.

### Step B2 — Identify Beta patterns

Use Phase 1 of the migration guide to locate:

- **Pattern A** — Script tag loading `lightning.out.js` (extract the domain).
- **Pattern B** — Config variables (endpoint, Aura app, component, token).
- **Pattern C** — `$Lightning.use(...)` call.
- **Pattern D** — `$Lightning.createComponent(...)` call.
- **Pattern E** — DOM target element referenced by the 3rd arg of Pattern D.

See [lightning-out-beta-to-2-migration.md § Phase 1](references/lightning-out-beta-to-2-migration.md).

### Step B3 — Apply transformations

The script-tag URL, the component tag name, and the attribute names are
**deterministic** conversions — derive them with the helper script so they are
exact every time (namespace preserved, camelCase → kebab-case, Beta host →
versioned LO 2.0 library URL):

```bash
python3 scripts/convert-lo-names.py \
  --component c:myComponent \
  --attributes recordId,ownerId \
  --my-domain https://<DOMAIN>.lightning.force.com
```

It prints the `<c-...>` tag, the kebab-case attributes, and the versioned LO
2.0 library URL. Then work through Phase 2 of the guide:

1. **Script tag** — use the `library-url` the script prints; add `async`.
2. **Component name / attributes** — use the `component-tag` and kebab-case
   attributes the script prints.
3. **Component tag** — add the `<c-...>` tag directly in HTML at the target
   location (a judgement call — place it where the Beta render target was).
4. **Replace the `$Lightning` block** — delete it entirely and start from
   [assets/lo20-host-page-template.html](assets/lo20-host-page-template.html),
   filling in the config constants; it already includes the helper functions,
   `mountLo20(frontdoorUrl, orgUrl)`, `boot()`, and the OAuth listeners.

### Step B4 — Six non-negotiable rules

These rules cause silent runtime failures if violated, and every one is a
deterministic code-structure check. Enforce them with the validator script
rather than by eye — run it against the migrated page and fix every FAIL:

```bash
python3 scripts/validate-lo20-page.py <migrated-page.html>
```

It prints a PASS/FAIL line per rule (plus the LO 2.0 library and Beta-removal
checks) and exits non-zero if any rule fails. The six rules it enforces:

1. `customElements.whenDefined(...)` must receive a **literal string**, not
   the `components` variable.
2. `mountLo20(frontdoorUrl, orgUrl)` must accept two parameters.
3. Call `clearCachedResult()` before every `mountLo20(...)`.
4. Always pass both parameters when calling `mountLo20(...)`, even if
   `orgUrl` is undefined.
5. Wrap all initialization in `boot()` and call `boot()` at the end.
6. The component tag has **no inline `display:none`** — control visibility
   via the loading indicator.

### Step B5 — Salesforce setup

- **External Client App (ECA)** — Setup → App Manager → New Connected App →
  External Client App. Enable OAuth with PKCE. Copy the Consumer Key.
- **Lightning Out 2.0 App** — apply this decision before continuing:

  | Condition | Action |
  |---|---|
  | Host page sets `app-id="..."` | Setup → Lightning Out → New LO App; copy the 18-character App ID into the host page's `app-id` attribute |
  | Host page embeds LWC directly (no `app-id`) | Skip the LO App entirely |
- Helper files the migration assumes exist alongside the host page:
  `frontdoor-url.html` (OAuth callback) and `utils/LightningOutAuth.js`
  (PKCE implementation).

### Step B6 — Run the LO 2.0 verification checklist

First run `python3 scripts/validate-lo20-page.py <migrated-page.html>` to clear
the mechanical checks, then walk the remaining manual items in the full
post-migration checklist — cover every item before declaring the migration
done. See the "Verification Checklist" section at the end of
[lightning-out-beta-to-2-migration.md](references/lightning-out-beta-to-2-migration.md).


## Verification Checklist (high level)

For Aura → LWC:
- [ ] All 12 completeness metrics rated with a justification.
- [ ] Output in list form (not table), per the reference.
- [ ] Overall confidence statement present.
- [ ] Concrete, prioritized recommendations listed.

For LO Beta → LO 2.0:
- [ ] Script tag uses `.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js` with `async`.
- [ ] No references to `$Lightning.use` / `$Lightning.createComponent` remain.
- [ ] Component name is kebab-case; attributes are kebab-case.
- [ ] `mountLo20(frontdoorUrl, orgUrl)` takes two parameters.
- [ ] `customElements.whenDefined(...)` uses a literal string.
- [ ] All initialization wrapped in `boot()` and `boot()` is called once.
- [ ] OAuth PKCE flow replaces hardcoded token; postMessage, BroadcastChannel,
      and storage listeners all present and defensively coded.
- [ ] Component tag has no inline `display:none`.


## Troubleshooting

- **LO 2.0 mount hangs** — custom element not registered. Verify the library
  script tag URL and that the `app-id` / `frontdoor-url` values are correct.
- **Component renders empty** — attributes probably still in camelCase. LO 2.0
  reads HTML attributes which must be kebab-case.
- **OAuth callback never fires** — one of postMessage / BroadcastChannel /
  storage listeners was dropped. LO 2.0 needs all three.
- **Aura checklist scored "Missing" on UTAM or Jest** — may be acceptable if
  the team has an alternative test strategy; flag in recommendations rather
  than block.

© forcedotcom · Apache-2.0 · forcedotcom/sf-skills

Similar skills

All skills for Frontend and UI →

From the same set232

The whole set →
consumer-goods-tpe-dashboard-configure consumer-goods-tpe-dashboard-configure — a skill that walks a TPM admin through twelve phases of Trade Promotion Effectiveness dashboard setup, from package checks to the analytics app install. CX Codex +1 323installs service-itsm-slack-itservice-configure The service-itsm-slack-itservice-configure skill guides the Employee Service setup for Slack, including org preferences, employee permissions, and linking a digital experience site. CX Codex +1 320installs service-itsm-agentic-setup-agent-runtime-access-assign service-itsm-agentic-setup-agent-runtime-access-assign is a Claude Code skill that assigns Salesforce users runtime permissions for activated ITSM agents. It addresses access errors during agent actions. CX Codex +1 314installs experience-search-coordinate experience-search-coordinate coordinates search workflows for articles, news, and media assets across Salesforce CMS channels, splitting mixed requests into structured content and media queries. CX Codex +1 275installs platform-agenticsetup-categories-get platform-agenticsetup-categories-get fetches Agentic Setup prompt categories from a connected Salesforce org through the Connect API. It can include prompts nested under each category. CX Codex +1 235installs experience-cms-content-render experience-cms-content-render — a skill for Claude Code, Codex, Cursor and other agents that wires existing Salesforce CMS content into a React or Angular uiBundle app. CX Codex +1 226installs experience-design-validate experience-design-validate performs visual craft audits on rendered interfaces using screenshots, Figma frames, or live URLs. Generates an evidence-backed craft report. CX Codex +1 220installs platform-role-hierarchy-apply The platform-role-hierarchy-apply Claude Code skill reshapes a Salesforce role hierarchy from an org chart. It prepares grouped role and user changes for admin review before submission. CX Codex +1 178installs

Project sponsors

Companies that keep this analytics open