Lwc Locker To Lws Migration

LWC Locker → Lightning Web Security (LWS) Migration

Activate this skill when an org is preparing to flip from Lightning Locker Service (the old per-namespace JavaScript sandbox built on SecureWindow/SecureElement proxies) to Lightning Web Security (LWS), the modern replacement based on JavaScript realms and standards-based browser primitives. LWS went GA for LWC in Spring '23, became the default for new orgs shortly after, and Salesforce has announced Locker for LWC will be retired — every org will eventually run on LWS.

The migration is a per-org switch controlled by the "Use Lightning Web Security for Lightning web components" setting on Session Settings (the metadata field is SecuritySettings.lwsForLwcEnabled; the older Locker-disable flag persists as lws.disabled in some legacy docs). Flipping it is one click — but the JavaScript runtime under every LWC changes, so the work is in inventorying what could break, exercising it in a sandbox, and removing now-redundant Locker workarounds.

This skill is NOT for Aura → LWC migration (see lwc/aura-to-lwc-migration) and NOT for generic LWC security review (see lwc/lwc-security and lwc/lwc-public-api-hardening). It is specifically the runbook for the Locker → LWS cutover.

Before Starting

Gather this context before working on anything in this domain:

• Where the org sits today. Is the org already on LWS (default for orgs created after Spring '23)? Check Setup → Session Settings → "Use Lightning Web Security for Lightning web components." If the box is checked, you are already on LWS — this skill becomes a clean-up exercise (remove obsolete Locker shims), not a migration.
• Aura coexistence. LWS for LWC and Locker for Aura are independent toggles. Flipping LWS on for LWC does NOT migrate Aura components — they continue to run under Aura Locker. Plan the LWC cutover without assuming Aura comes along.
• Third-party library inventory. Every library loaded via loadScript/loadStyle from a static resource is a migration risk surface. Chart.js, D3, jsPDF, PDF.js, signature pads, OCR libs, crypto libs, anything that touched window/document or used eval/Function() for hot paths — list them.
• Locker-era workarounds in the codebase. Search for // LOCKER:, SecureElement, SecureWindow, unwrap(), deep cloning before passing into a third-party lib, manual JSON.parse(JSON.stringify(...)) to "escape the proxy" — these are now dead weight (and sometimes actively harmful under LWS).
• The most common wrong assumption. That LWS is "stricter" than Locker. It is not — LWS is less intrusive at runtime (no SecureElement proxy wrapping every DOM node) but more strict at the realm boundary (cross-namespace access is harder, prototype pollution is contained per-realm). Things that broke under Locker often just work under LWS; the regressions are concentrated in cross-namespace and prototype-extending code.
• No partial rollout. The setting is org-wide for LWC, not per-component. There is no "enable LWS for these 12 components only." Plan to flip it everywhere, in a sandbox, on a defined date.

Core Concepts

1. Locker proxies vs LWS realms

Locker wraps every DOM node and every window reference your component touches in a SecureElement / SecureWindow proxy. The proxy filters property access to enforce per-namespace isolation. The cost: third-party libraries see a proxy, not a real Element, and many of them perform instanceof HTMLElement checks, prototype walks, or property descriptor lookups that the proxy doesn't satisfy. This is why Chart.js 2.x, jsPDF, and many DOM-touching libs needed elaborate workarounds under Locker.

LWS uses JavaScript realms (the same primitive that powers <iframe> isolation in browsers) instead. Each component's code runs in its own realm with its own copy of the built-in prototypes (Array.prototype, Object.prototype, etc.). The DOM nodes your code receives are real DOM nodes — instanceof HTMLElement is true, property descriptors look exactly like the spec, DevTools shows the actual element rather than Proxy {}. Third-party libraries see what they expect.

The cost is at the boundary: passing an object between realms (e.g., from a parent component in namespace A to a child in namespace B) causes a structured-clone-style copy. Functions don't transfer cleanly across realms, so you cannot pass a callback from one namespace into a library running in another namespace and expect identity.

2. The org switch and how LWS gets enabled

The setting lives at Setup → Session Settings → Lightning Web Security for Lightning web components. Metadata API exposes it on the SecuritySettings type. There is no per-component opt-in/opt-out for LWC — it is the entire org's LWC runtime, all at once.

For Aura, a separate Lightning Web Security for Aura components toggle controls whether Aura components run under LWS or under Aura Locker. As of Spring '25 this is still rolling out (treat as pilot/GA-rolling, verify per-org), so don't promise an unrelated team that flipping LWC also moves Aura.

force:hasRecordId and force:hasSObjectName are Aura interfaces historically used by Aura components to receive context. LWC equivalents are the @api recordId and @api objectApiName properties exposed automatically when a component is placed in a record context. Migrating to LWS does not change LWC's recordId/objectApiName behaviour — but if you have legacy LWCs that were exposed inside an Aura wrapper purely to consume force:hasRecordId, the wrapper is no longer required (and the LWC can be placed directly).

3. What changes for eval, new Function(), and dynamic code

Locker blocked eval() and new Function() outright in the per-component sandbox. Many libraries shipped a "Locker-compatible" build that pre-compiled templates or used a different code path to avoid these primitives.

LWS does not unconditionally block eval. It enforces the page's CSP policy, which on Lightning Experience disallows unsafe-eval for hosted code by default — but a library shipped via <script> from a Salesforce static resource and evaluated inside the LWS realm runs against the realm's CSP, which historically permits more than Locker did. In practice: assume eval and new Function are still off-limits at the page-CSP level for production code, but Locker-era pre-compilation workarounds may now be unnecessary because the library's standard build runs correctly under LWS.

Critical caveat for LLM-generated code: do not "unblock" Locker-era restrictions by reaching for eval "because LWS allows it now." LWS is not a license to ship eval-based code — the workaround was insecure under Locker and remains insecure under LWS. See references/llm-anti-patterns.md.

4. Cross-namespace, postMessage, and iframes

Locker filtered cross-namespace property access at the proxy boundary, which made some postMessage patterns awkward (you'd receive a proxy, not the raw message data). LWS uses realm boundaries: messages crossing a realm are structurally cloned, so:

• postMessage to/from an <iframe> works with standard DOM semantics — the message is a structured clone, no proxy unwrapping required.
• Cross-namespace component-to-component calls (parent in acme__, child in widgets__) cross a realm boundary; identity is not preserved across the hop.
• A function passed across realms is not callable on the other side. Use events with structured-cloneable detail payloads, not callbacks.

Common Patterns

Pattern 1: Library that broke under Locker, works native under LWS

When to use: any third-party library shipped as a static resource that needed Locker-era patches, custom shims, or a "Locker-compatible" fork.

How it works:

1. Identify the library (search loadScript / loadStyle callers).
2. Find the Locker workaround (a fork, a patched build, a shim file, or a JSON.parse(JSON.stringify(x)) deep-clone before passing data in).
3. Switch back to the upstream build.
4. Remove the shim.
5. In a sandbox with LWS enabled, exercise the library's hot path (render a chart, generate a PDF, sign a signature pad, etc.).
6. Confirm DevTools shows real DOM nodes, not Proxy objects, in the library's render target.

Why not "just leave the workaround in": Locker-era shims often deep-clone data on the way in to escape the proxy. Under LWS, the deep-clone is now pure overhead and frequently strips functions / class identity that the library expected to preserve, causing new bugs.

Pattern 2: Sandbox exercise plan before flipping production

When to use: every Locker → LWS cutover. Never flip in production without exercising in at least one sandbox first.

How it works:

1. In a Full or Partial sandbox, enable LWS for LWC in Session Settings.
2. Open every Lightning page that hosts custom LWCs (App Pages, Record Pages, Quick Actions, Utility Bar items, Experience Cloud sites).
3. Exercise every third-party-library-driven feature (charts render, PDFs download, signature captured, file uploads chunk correctly).
4. Open DevTools and confirm: no Proxy {...} wrappers in component logs, no console errors that mention SecureElement / SecureWindow / [object SecureWindow].
5. Re-run the org's LWC Jest suite — many Locker-only mocks (e.g., jest-canvas-mock injected because Locker proxies confused canvas tests) may no longer be necessary; remove what is now unused.
6. Document any regressions, fix in the sandbox, then plan the production cutover with a rollback window.

Why not "just flip prod and watch": the switch is org-wide. There is no graceful per-component rollback — you either toggle the setting back off (which restores Locker for everyone) or you ship code fixes. Sandbox exercise is the only way to make the production flip uneventful.

Pattern 3: Identifying components likely to break

When to use: triage step before the sandbox exercise — narrows the manual-test list.

How it works: scan the LWC bundles for these signals (the skill-local checker scripts/check_lwc_locker_to_lws_migration.py automates this):

• Direct references to SecureElement, SecureWindow, SecureDocument, SecureObject — Locker-only types that no longer exist under LWS.
• Calls to unwrap() / getRawNode() / LightningElement.prototype walking — Locker-era tricks.
• Static resource loads of known-broken-under-Locker libraries (Chart.js < 3.x patched builds, jsPDF < 2.x with custom forks, D3 v4 patched build) — likely have shims to remove.
• instanceof HTMLElement guards followed by a fallback path — the fallback was for Locker proxies and is now dead code.
• Jest mocks named *-locker-shim*, mock-secure-window*, or that explicitly set up window polyfills — likely obsolete under LWS.

Why not just rely on automated tests: Jest doesn't run inside Locker or LWS — Jest runs in Node with @lwc/jest-preset. Test passes are necessary but not sufficient evidence the runtime change is safe; manual sandbox exercise is required for any DOM/library-dependent feature.

Decision Guidance

Recommended Workflow

1. Read the org state. Check Session Settings → Lightning Web Security for LWC for the current toggle. Check Setup → Salesforce release notes for the active release to confirm LWS is GA in this org's instance. Note whether the Aura LWS toggle is on.
2. Inventory the surface. Collect: every LWC bundle path, every static resource loaded via loadScript/loadStyle, every third-party library version, every Jest mock specifically added for Locker. Build a CSV / table.
3. Run the static checker. python3 skills/lwc/lwc-locker-to-lws-migration/scripts/check_lwc_locker_to_lws_migration.py <path-to-lwc-bundles> to flag Locker-only references (SecureElement, SecureWindow, unwrap(), etc.) and known-suspect library names.
4. Classify each component as safe (no Locker-specific code, no third-party DOM lib), needs-shim-removal (has Locker workarounds to delete), or manual-test-required (loads a third-party library or touches window/document directly).
5. Enable LWS in a sandbox. Pick a Full or Partial Copy sandbox. Flip the Session Settings toggle. Exercise every manual-test-required component on every page where it appears. Capture DevTools console for errors.
6. Remove obsolete workarounds. Strip Locker shims, replace patched library builds with upstream, drop now-unnecessary Jest mocks. Re-run Jest.
7. Plan the production cutover. Pick a low-traffic window. Communicate to stakeholders. Identify the rollback path (toggle back off → Locker is restored, but redeployed code stays). Flip in production. Monitor for 24–48 hours.

Review Checklist

• Org switch state confirmed — Session Settings inspected; current state (Locker / LWS) explicitly recorded
• Static checker clean — check_lwc_locker_to_lws_migration.py reports no SecureElement / SecureWindow / unwrap() references remain
• Third-party libraries verified — every library loaded via loadScript/loadStyle has been exercised in a sandbox under LWS
• Locker-era shims removed — patched library forks replaced with upstream; deep-clone-on-input workarounds deleted
• Jest config rationalised — Locker-only mocks (canvas polyfills, SecureWindow stubs) removed if no longer needed; suite still passes
• Cross-namespace callbacks audited — no function passed across realm boundaries between parent and child in different namespaces
• Rollback runbook documented — clear steps to flip the setting back if production exhibits an unrecoverable regression

Salesforce-Specific Gotchas

1. The toggle flips the entire org's LWC runtime at once — there is no per-component or per-page LWS opt-in. Treat the flip as a release event, not a per-feature feature flag. (See references/gotchas.md for what happens to in-flight user sessions.)
2. SecureElement/SecureWindow references are silent failures, not loud errors — under LWS, code that reads instanceof SecureElement simply evaluates to false (the global no longer exists), which often steers code into a stale fallback path rather than throwing. Static scan for these symbols before flipping.
3. Aura LWS is a separate toggle and lags LWC LWS — don't assume that flipping LWC LWS also moves Aura components. Aura components remain on Aura Locker until the (separate) Aura LWS toggle is enabled, and that feature has had its own GA timeline.
4. Third-party libraries that "broke under Locker" usually work under LWS — but the reverse can also happen — a library that depended on a Locker-side effect (rare, but real for libs that probed for the proxy as a fingerprint) can break under LWS. The sandbox exercise is the only reliable check.
5. force:hasRecordId Aura wrappers around LWCs become redundant — once on LWS, an LWC placed directly on a record page receives recordId via @api. Retire wrappers as a clean-up step; do not retire them in the same change as the LWS flip — keep the changes separable for rollback clarity.

Output Artifacts

Related Skills

• lwc/lwc-security — general LWC security posture (XSS, sanitisation, CSP) — orthogonal to the runtime sandbox change LWS represents
• lwc/lwc-public-api-hardening — hardening @api boundaries; relevant because LWS realm boundaries make cross-namespace @api cleaner
• lwc/lwc-testing — Jest patterns; informs which Locker-only mocks can be retired
• lwc/aura-to-lwc-migration — separate migration; LWS migration is a good prompt to also retire residual Aura wrappers
• lwc/common-lwc-runtime-errors — diagnosing the runtime errors that show up immediately after flipping LWS in a sandbox