experience-aura-lwc-migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating Aura to LWC

将Aura组件迁移至LWC

Migrate an existing Salesforce Aura component bundle to a Lightning Web Component using a PRD-driven workflow. The Aura source is analyzed through eight expert lenses (static references, data, API surface, slots, styling, default values, unknown dependencies, redundant-code cleanup) to produce a framework-agnostic PRD, which is handed to the LWC authoring skills and verified against the Aura→LWC completeness checklist.

采用PRD驱动的工作流，将现有Salesforce Aura组件包迁移至Lightning Web Component（LWC）。通过八个专业维度（静态引用、数据、API接口、插槽、样式、默认值、未知依赖、冗余代码清理）分析Aura源文件，生成与框架无关的PRD，交付给LWC编写技能，并对照Aura→LWC完整性清单进行验证。

When to Use

适用场景

Porting an Aura bundle (

.cmp

.controller.js

.helper.js

.renderer.js

.css

.design

.evt

.intf

) to LWC.

Producing a framework-agnostic PRD from Aura source so a sibling team can implement the LWC equivalent.
Auditing an Aura component for patterns that need explicit mapping before LWC conversion (facets,
```
aura:id
```
DOM access,
```
force:recordData
```
, application events).

Do NOT use this skill for:

Authoring a brand-new LWC from a Figma or PRD with no Aura source (delegate to
```
experience-lwc-generate
```
).
Refactoring an existing LWC (delegate to
```
experience-lwc-generate
```
).
Post-hoc completeness scoring of a conversion that was already done without this skill, or Lightning Out Beta → 2.0 host-page migration — no checked-in skill covers these today.

将Aura组件包（

.cmp

、

.controller.js

、

.helper.js

、

.renderer.js

、

.css

、

.design

、

.evt

、

.intf

）移植到LWC。

从Aura源文件生成与框架无关的PRD，以便协作团队实现对应的LWC组件。
在LWC转换前，审计Aura组件中需要显式映射的模式（ facets、
```
aura:id
```
DOM访问、
```
force:recordData
```
、应用事件）。

请勿将此技能用于：

无Aura源文件，从Figma或PRD全新编写LWC（委托给
```
experience-lwc-generate
```
）。
重构现有LWC组件（委托给
```
experience-lwc-generate
```
）。
对未使用此技能完成的转换进行事后完整性评分，或Lightning Out Beta → 2.0宿主页面迁移——目前没有已入库的技能支持这些场景。

Prerequisites

前提条件

Aura component bundle files (minimum:
```
.cmp
```
; usually also controller / helper / CSS / events / interfaces).
Target LWC path (module folder) — discover the caller's module tree from
```
sfdx-project.json
```
```
packageDirectories
```
(typically an
```
lwc/<name>/
```
subdirectory under one of the listed package paths).
For resolver-assisted dependency lookup (Phase 2, step 7): the
```
@sfdc-internal/adk-knowledge
```
package installed in the caller's workspace. If it is not present, the skill surfaces the missing dependency as an unknown rather than failing.
Awareness of the project's downstream LWC authoring flow — this skill hands off a PRD to that flow but does not invoke it.

Aura组件包文件（至少包含
```
.cmp
```
；通常还包含控制器/辅助函数/CSS/事件/接口文件）。
目标LWC路径（模块文件夹）——从
```
sfdx-project.json
```
的
```
packageDirectories
```
中获取调用方的模块树（通常是所列包路径下的
```
lwc/<name>/
```
子目录）。
用于依赖解析的辅助工具（第2阶段第7步）：调用方工作区中已安装
```
@sfdc-internal/adk-knowledge
```
包。如果未安装，此技能会将缺失的依赖标记为未知项，而非直接失败。
了解项目的下游LWC编写流程——此技能仅将PRD交付给该流程，不会主动调用它。

Core Principles

核心原则

Apply the Aura → LWC migration principles before and during each phase: understand before converting, prioritize functionality equivalence over structural equivalence, leverage native web standards, migrate iteratively, and test thoroughly. The architectural deltas (two-way → one-way binding, Aura events → DOM events,

aura:id

→

this.template.querySelector

, etc.) are documented in references/aura-migration-guidelines.md.

在迁移的每个阶段前后，都需遵循Aura → LWC迁移原则：先理解再转换、优先保证功能等价而非结构等价、利用原生Web标准、迭代式迁移、全面测试。架构差异（双向绑定→单向绑定、Aura事件→DOM事件、

aura:id

→

this.template.querySelector

等）记录在references/aura-migration-guidelines.md中。

Knowledge Bases

知识库

references/aura-prd-framework.md — the 14-section framework for drafting a framework-agnostic PRD from an Aura component.
references/aura-migration-guidelines.md — core principles + Aura-vs-LWC architectural differences + markup / JS / event / lifecycle translation tables.
references/aura-reference-expert.md — static resources, global value providers, HTML-to-generic wording, URLs, component dependencies,
```
Aura.Action
```
handlers.
references/aura-data-expert.md — data requirements,
```
force:recordData
```
,
```
lightning:recordViewForm
```
, Apex controllers.
references/aura-api-expert.md — API surface: public attributes, methods, layout, component events, DOM events.
references/aura-slots-expert.md — default and named slots (Aura facets /
```
{!v.body}
```
→ LWC slots).
references/aura-style-expert.md — CSS, SLDS, design tokens, dynamic styling.
references/aura-values-expert.md — default values and initialization patterns.
references/aura-resolver-expert.md — resolving unknown components, events, interfaces, and libraries via the
```
@sfdc-internal/adk-knowledge
```
package.
references/aura-redundant-code-expert.md — strip Aura-only noise (commented-out code, telemetry, unused private attributes/methods) from the PRD before LWC handoff.
WCAG 2.2 — Aura-scoped accessibility reviewers (SC 1.3.1 (ii) Tables, 1.3.5 Identify Input Purpose, 3.2.1 On Focus, 3.2.2 On Input, 3.3.2 Labels or Instructions, 4.1.2 Name / Role / Value) are planned to land as a separate
```
accessibility-code-review-aura
```
skill in a follow-up PR; until then, Phase 3 applies the WCAG preamble inline.
references/aura-to-lwc-completeness-checklist.md — post-conversion verification rubric.

Open the relevant reference before drafting or enhancing the corresponding PRD section.

references/aura-prd-framework.md——从Aura组件起草与框架无关的PRD的14节框架规范。
references/aura-migration-guidelines.md——核心原则 + Aura与LWC的架构差异 + 标记/JS/事件/生命周期转换对照表。
references/aura-reference-expert.md——静态资源、全局值提供者、HTML通用化表述、URL、组件依赖、
```
Aura.Action
```
处理器。
references/aura-data-expert.md——数据需求、
```
force:recordData
```
、
```
lightning:recordViewForm
```
、Apex控制器。
references/aura-api-expert.md——API接口：公共属性、方法、布局、组件事件、DOM事件。
references/aura-slots-expert.md——默认插槽和命名插槽（Aura facets /
```
{!v.body}
```
→ LWC插槽）。
references/aura-style-expert.md——CSS、SLDS、设计令牌、动态样式。
references/aura-values-expert.md——默认值和初始化模式。
references/aura-resolver-expert.md——通过
```
@sfdc-internal/adk-knowledge
```
包解析未知组件、事件、接口和库。
references/aura-redundant-code-expert.md——在交付LWC前，从PRD中移除仅Aura特有的冗余内容（注释代码、遥测代码、未使用的私有属性/方法）。
WCAG 2.2——针对Aura的可访问性审查（SC 1.3.1 (ii) 表格、1.3.5 识别输入用途、3.2.1 聚焦时、3.2.2 输入时、3.3.2 标签或说明、4.1.2 名称/角色/值）计划作为独立的
```
accessibility-code-review-aura
```
技能在后续PR中推出；在此之前，第3阶段会内联应用WCAG序言内容。
references/aura-to-lwc-completeness-checklist.md——迁移后验证准则。

在起草或优化PRD对应章节前，请打开相关参考文档。

Workflow

工作流程

This skill covers the analysis and PRD-generation phases only. It does not produce, edit, or validate LWC bundles, wire adapters, or tests. Phases 1–3 below are mandatory when this skill is invoked. Phases 4–5 describe the recommended downstream authoring flow — they are informational follow-up guidance for the caller and are NOT executed by this skill.

此技能仅涵盖分析和PRD生成阶段。不生成、编辑或验证LWC组件包、wire适配器或测试用例。调用此技能时，以下第1–3阶段为必填步骤。第4–5阶段为推荐的下游编写流程指导——仅为调用方提供信息，不由此技能执行。

Phase 1 — Analyze and draft the PRD

第1阶段 — 分析并起草PRD

Goal: produce a draft YAML PRD that captures every section of the 14-section framework.

Inspect the caller-supplied Aura bundle files. Extract the component name, the
```
access
```
attribute from the
```
.cmp
```
metadata, and every embedded/referenced component.
Apply the framework in references/aura-prd-framework.md. State the
```
access
```
attribute explicitly in the overview and describe its implications (GLOBAL: publicly available across namespaces; PRIVILEGED/PUBLIC: restricted; etc.).
Never list the host component itself in the
```
unknowns
```
section — that creates a circular dependency. If no valid unknowns exist, use an empty array.

Save the draft PRD to the workspace (e.g.,

packages/skills/<skill>-workspace/<iteration>/PRD-draft.yaml

Deliverable: draft PRD (YAML) covering the 14 sections.

**目标：**生成涵盖14节框架所有内容的YAML格式PRD草稿。

检查调用方提供的Aura组件包文件。提取组件名称、
```
.cmp
```
元数据中的
```
access
```
属性，以及所有嵌入/引用的组件。
应用references/aura-prd-framework.md中的框架规范。在概述中明确说明
```
access
```
属性及其含义（GLOBAL：跨命名空间公开可用；PRIVILEGED/PUBLIC：受限访问；等）。
切勿将宿主组件本身列入
```
unknowns
```
章节——这会造成循环依赖。如果没有有效的未知项，使用空数组。

将PRD草稿保存到工作区（例如：

packages/skills/<skill>-workspace/<iteration>/PRD-draft.yaml

）。

**交付物：**涵盖14节内容的PRD草稿（YAML格式）。

Phase 2 — Enhance the PRD with Aura expert lenses

第2阶段 — 借助Aura专业维度优化PRD

Goal: harden each section using the eight Aura expert frameworks.

Apply the experts in order. Each pass reads the draft PRD and rewrites the relevant sections in place.

Reference analysis — apply references/aura-reference-expert.md to
```
staticReferences
```
,
```
componentCommunication
```
, and
```
unknowns
```
. Enumerate every
```
$Resource
```
,
```
$ContentAsset
```
,
```
$Label
```
,
```
$Browser
```
,
```
$Locale
```
,
```
/lightning/*
```
route, and
```
c:*
```
/
```
force:*
```
/
```
lightning:*
```
dependency. The blueprint must never directly contain the Aura-specific strings
```
$ContentAsset
```
,
```
$Label
```
,
```
$Resource
```
,
```
$Browser
```
, or
```
$Locale
```
; replace each with a description of intent.
Data analysis — apply references/aura-data-expert.md to
```
dataRequirements
```
. The blueprint
```
dataRequirements
```
must not contain
```
force:recordData
```
or
```
lightning:recordViewForm
```
— document the underlying record, fields, and object-API-name instead. Rename
```
sObjectName
```
→
```
objectApiName
```
. Capture Apex-controller method names, input parameters, and output shapes.
API analysis — apply references/aura-api-expert.md to
```
componentCommunication
```
,
```
interactions
```
, and
```
staticReferences
```
. Document every public attribute (with type, default, and all usage intents),
```
<aura:method>
```
declaration, event firing (
```
component.getEvent(...).fire()
```
), and
```
Object
```
-typed callback attribute (these become LWC custom events).
Slots analysis — apply references/aura-slots-expert.md to
```
contentRequirements
```
. Translate every
```
{!v.body}
```
/
```
{#v.body}
```
to a default slot entry (LWC components can have only one default slot — capture the condition under which it is present) and every
```
<aura:attribute type="Aura.Component">
```
or
```
"Aura.Component[]"
```
to a named-slot entry.
Style analysis — apply references/aura-style-expert.md to
```
styling
```
and
```
dataRequirements
```
. Move styling-related attributes out of
```
dataRequirements
```
and into
```
styling
```
. Document SLDS hooks, custom CSS, and any dynamic styling driven by JS.
Values analysis — apply references/aura-values-expert.md to
```
dataRequirements
```
. For every Aura attribute, record its default value (type + literal; or namespace + name for
```
$Label
```
references) in the
```
what
```
property.
Resolver analysis — apply references/aura-resolver-expert.md to
```
unknowns
```
. For each unknown, parse namespace + name, look up the corresponding file under
```
node_modules/@sfdc-internal/adk-knowledge/dist/
```
using the mapping rules, and either inline the resolved content or leave a note that manual research is required. If the
```
@sfdc-internal/adk-knowledge
```
package is not installed, note the expected path and leave the unknown in place.
Redundant-code cleanup — apply references/aura-redundant-code-expert.md across the PRD. Remove commented-out markup/JS/CSS, telemetry/instrumentation, and private attributes/methods that aren't used elsewhere — these don't carry forward to LWC. Keep the PRD's JSON shape intact; sections may end up with empty arrays. Generate a short report listing only the items that actually changed.

Deliverable: enhanced PRD (YAML) with all eight expert passes applied.

**目标：**通过八个Aura专业框架强化PRD的每个章节。

按顺序应用各专业维度。每次处理都会读取PRD草稿并就地重写相关章节。

引用分析——对
```
staticReferences
```
、
```
componentCommunication
```
和
```
unknowns
```
章节应用references/aura-reference-expert.md。枚举所有
```
$Resource
```
、
```
$ContentAsset
```
、
```
$Label
```
、
```
$Browser
```
、
```
$Locale
```
、
```
/lightning/*
```
路由，以及
```
c:*
```
/
```
force:*
```
/
```
lightning:*
```
依赖项。蓝图中绝不能直接包含Aura特有的字符串
```
$ContentAsset
```
、
```
$Label
```
、
```
$Resource
```
、
```
$Browser
```
或
```
$Locale
```
；需替换为对应的用途描述。
数据分析——对
```
dataRequirements
```
章节应用references/aura-data-expert.md。蓝图的
```
dataRequirements
```
章节不得包含
```
force:recordData
```
或
```
lightning:recordViewForm
```
——需记录底层的记录、字段和对象API名称。将
```
sObjectName
```
重命名为
```
objectApiName
```
。捕获Apex控制器方法名称、输入参数和输出结构。
API分析——对
```
componentCommunication
```
、
```
interactions
```
和
```
staticReferences
```
章节应用references/aura-api-expert.md。记录所有公共属性（含类型、默认值和所有使用意图）、
```
<aura:method>
```
声明、事件触发（
```
component.getEvent(...).fire()
```
），以及
```
Object
```
类型的回调属性（这些将成为LWC自定义事件）。
插槽分析——对
```
contentRequirements
```
章节应用references/aura-slots-expert.md。将所有
```
{!v.body}
```
/
```
{#v.body}
```
转换为默认插槽条目（LWC组件只能有一个默认插槽——需记录其存在的条件），将所有
```
<aura:attribute type="Aura.Component">
```
或
```
"Aura.Component[]"
```
转换为命名插槽条目。
样式分析——对
```
styling
```
和
```
dataRequirements
```
章节应用references/aura-style-expert.md。将与样式相关的属性从
```
dataRequirements
```
移至
```
styling
```
章节。记录SLDS钩子、自定义CSS，以及由JS驱动的动态样式。
值分析——对
```
dataRequirements
```
章节应用references/aura-values-expert.md。对于每个Aura属性，在
```
what
```
属性中记录其默认值（类型+字面量；或
```
$Label
```
引用的命名空间+名称）。
解析器分析——对
```
unknowns
```
章节应用references/aura-resolver-expert.md。针对每个未知项，解析命名空间+名称，使用映射规则在
```
node_modules/@sfdc-internal/adk-knowledge/dist/
```
下查找对应文件，要么内联解析后的内容，要么留下需手动调研的注释。如果未安装
```
@sfdc-internal/adk-knowledge
```
包，记录预期路径并保留未知项。
冗余代码清理——对整个PRD应用references/aura-redundant-code-expert.md。移除注释掉的标记/JS/CSS、遥测/ instrumentation代码，以及未在其他地方使用的私有属性/方法——这些内容无需迁移至LWC。保持PRD的JSON结构完整；部分章节可能最终为空数组。生成一份简短报告，仅列出实际修改的内容。

**交付物：**经过八个专业维度优化后的PRD（YAML格式）。

Phase 3 — Accessibility pass

第3阶段 — 可访问性检查

Goal: ensure the PRD's

accessibility

section meets WCAG 2.2 minimums.

Apply the WCAG 2.2 reviewers inline against the Aura source files (
```
.cmp
```
,
```
.controller.js
```
,
```
.helper.js
```
,
```
.renderer.js
```
,
```
.css
```
). Cover the Aura-scoped Success Criteria: 1.3.1 (ii) Tables, 1.3.5 Identify Input Purpose, 3.2.1 On Focus, 3.2.2 On Input, 3.3.2 Labels or Instructions, 4.1.2 Name / Role / Value. (When the sibling
```
accessibility-code-review-aura
```
skill ships in a follow-up PR, hand off to it instead.)
Fold each finding into the PRD's
```
accessibility
```
section. For every requirement, capture the WCAG Success Criterion it satisfies and the proposed LWC implementation approach (semantic HTML first, ARIA only where semantic HTML cannot achieve the same outcome).
Only cite violations that directly break a WCAG Success Criterion. Do not suggest enhancements outside WCAG scope.

Deliverable: PRD with an accessibility section that lists each required feature, the WCAG Success Criterion it satisfies, and the LWC implementation approach.

**目标：**确保PRD的

accessibility

章节符合WCAG 2.2最低要求。

针对Aura源文件（
```
.cmp
```
、
```
.controller.js
```
、
```
.helper.js
```
、
```
.renderer.js
```
、
```
.css
```
）内联应用WCAG 2.2审查规则。覆盖Aura相关的成功准则：1.3.1 (ii) 表格、1.3.5 识别输入用途、3.2.1 聚焦时、3.2.2 输入时、3.3.2 标签或说明、4.1.2 名称/角色/值。（当后续PR推出配套的
```
accessibility-code-review-aura
```
技能后，将委托给该技能处理。）
将每个检查结果整合到PRD的
```
accessibility
```
章节中。对于每个需求，记录其满足的WCAG成功准则，以及建议的LWC实现方案（优先使用语义化HTML，仅在语义化HTML无法实现相同效果时使用ARIA）。
仅引用直接违反WCAG成功准则的问题。不建议超出WCAG范围的增强内容。

**交付物：**包含可访问性章节的PRD，列出每个所需功能、其满足的WCAG成功准则，以及LWC实现方案。

Phase 4 — Downstream authoring (follow-up guidance, not executed here)

第4阶段 — 下游编写流程（指导内容，不由本技能执行）

Once the enhanced PRD is complete, the caller can hand it off to an LWC authoring workflow. This skill does not perform any authoring. Recommended downstream steps:

Pass the enhanced PRD to
```
experience-lwc-generate
```
as the design input, substituting for a Figma / written-spec input. This skill does not invoke
```
experience-lwc-generate
```
; the caller triggers it as a follow-up step.
For data access decisions (UIAPI / GraphQL / Apex), the caller may consult LDS-focused workflows to translate the PRD's
```
dataRequirements
```
section into concrete adapters.
For SLDS styling decisions, the caller may consult an SLDS design workflow.

优化后的PRD完成后，调用方可将其交付给LWC编写工作流。此技能不执行任何编写操作。推荐的下游步骤：

将优化后的PRD作为设计输入传递给
```
experience-lwc-generate
```
，替代Figma或书面规范输入。此技能不会调用
```
experience-lwc-generate
```
；需由调用方作为后续步骤触发。
对于数据访问决策（UIAPI / GraphQL / Apex），调用方可咨询LDS相关工作流，将PRD的
```
dataRequirements
```
章节转换为具体的适配器。
对于SLDS样式决策，调用方可咨询SLDS设计工作流。

Phase 5 — Downstream verification (follow-up guidance, not executed here)

第5阶段 — 下游验证流程（指导内容，不由本技能执行）

After LWC authoring completes, the caller can verify the migrated component with the project's standard test and review workflows — Jest coverage, accessibility Jest, a11y / security / RTL review, telemetry, feature-flag gating, etc. Apply references/aura-to-lwc-completeness-checklist.md as a final scoring pass on the completed LWC.

LWC编写完成后，调用方可通过项目的标准测试和审查工作流验证迁移后的组件——Jest覆盖率、可访问性Jest测试、a11y/安全/RTL审查、遥测、功能标志管控等。将references/aura-to-lwc-completeness-checklist.md作为最终评分标准，对已完成的LWC进行检查。

Cross-References

交叉引用

```
experience-lwc-generate
```
— recommended downstream authoring handoff (non-executing; the caller triggers it after this skill's PRD is complete).

```
experience-lwc-generate
```
——推荐的下游编写交付目标（不由本技能执行；调用方需在本技能生成PRD后触发）。

Verification (PRD-only)

验证（仅针对PRD）

The enhanced PRD covers all 14 framework sections with no
```
TODO
```
/ placeholder entries.

dataRequirements

contains no direct references to

force:recordData

lightning:recordViewForm

, and no

sObjectName

keys (renamed to

objectApiName

staticReferences

and other sections contain no raw Aura strings like

$Resource

$Label

$ContentAsset

$Browser

$Locale

Every
```
<aura:method>
```
appears in
```
interactions
```
with the corresponding trigger.
Every
```
{!v.body}
```
/
```
{#v.body}
```
appears in
```
contentRequirements
```
as a default slot (with the presence condition).

Every

<aura:attribute type="Aura.Component">

appears in

contentRequirements

as a named slot.

Every unknown has been resolved via the
```
@sfdc-internal/adk-knowledge
```
package (or marked as manually-required with the attempted knowledge-file path).

优化后的PRD涵盖所有14节框架内容，无
```
TODO
```
/占位符条目。

dataRequirements

章节不包含对

force:recordData

或

lightning:recordViewForm

的直接引用，也无

sObjectName

键（已重命名为

objectApiName

）。

```
staticReferences
```
及其他章节不包含
```
$Resource
```
、
```
$Label
```
、
```
$ContentAsset
```
、
```
$Browser
```
、
```
$Locale
```
等原始Aura字符串。
每个
```
<aura:method>
```
都出现在
```
interactions
```
章节中，并包含对应的触发条件。
每个
```
{!v.body}
```
/
```
{#v.body}
```
都作为默认插槽（含存在条件）出现在
```
contentRequirements
```
章节中。

每个

<aura:attribute type="Aura.Component">

都作为命名插槽出现在

contentRequirements

章节中。

每个未知项都已通过
```
@sfdc-internal/adk-knowledge
```
包解析（或标记为需手动处理，并记录尝试查找的知识库文件路径）。