Home / lwc / lwc-app-builder-config

lwc-app-builder-config

Use when an LWC needs to appear, be configured, and be constrained inside Lightning App Builder, Experience Builder, Home Page, or Flow screens via its js-meta.xml file — including isExposed, targets, targetConfigs, supportedFormFactors, objects scoping, and admin-facing design attributes.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Operational Excellence
• Reliability
• Security

• lwc-app-builder-config
• meta-xml
• targets
• target-configs
• design-attributes
• form-factors
• experience-builder
• record-page

Open the skill folder on GitHub

LWC App Builder Config

Use this skill whenever the functional behavior of the LWC is fine but the component either does not appear in a builder, appears in the wrong builder, or offers admins the wrong set of configuration knobs. The js-meta.xml file is the single source of truth that controls exposure, surface targeting, per-surface configuration, form-factor fit, and the admin UX inside App Builder, Experience Builder, Home Page, Utility Bar, and Flow.

Every component folder must include a componentName.js-meta.xml file; without one, a push fails (create-components-meta-file L715–L723).

Before Starting

Gather this context before editing a .js-meta.xml:

• Which surfaces must this component render on — Record Page, App Page, Home Page, Experience Cloud page, Utility Bar, Custom Tab, Flow Screen, or several of these?
• Which sObjects is the component valid against? A record-page targetConfig with no <objects> supports every UI-API-supported object (targets-lightning-record-page L19363), which is almost always wider than intended.
• Which form factors must be supported — Large (desktop), Small (phone), or both? App and record pages support both; Home pages support only Large (use-config-form-factors L9795).
• What admin-tunable inputs does the component need, and are any of them field-name pickers, picklist-value pickers, or free-text with defaults?
• Will this bundle ship in a managed package or be placed in a live Experience Cloud site? That decision closes doors permanently — see the one-way-door table below.

Questions to Ask Before Configuring

Ask these before you write the file. Each one traces to a gotcha in references/gotchas.md; skipping them produces a meta.xml that deploys and then cannot be changed.

What a proper configuration adds over just exposing the component: admins see only the knobs that make sense on the surface they are editing, the component cannot be dropped where its data model does not apply, and every irreversible choice (packaging exposure, form factors, min/max) is made deliberately instead of discovered later.

Core Concepts

The meta.xml file is small, but every element changes how the builder treats the bundle. Six concepts cover almost every real situation.

isExposed Controls Builder Visibility

<isExposed>false</isExposed> means the component is not exposed in the builders. To use it in a builder, set isExposed to true and define at least one <target> (reference-configuration-tags L18711–L18712). Both halves are required — isExposed=true with an empty <targets> gets you nothing.

targets Enumerate The Surfaces

<targets> holds one <target> per surface. The guide enumerates these values (L18721–L18749):

capabilities Declare What The Component Can Do

A capability is something a component can do, as opposed to a target, which is where it can be used (L18701). <capabilities> holds one <capability> per value; the guide documents five (L18704–L18709):

targetConfigs Customize Per-Surface Behavior

A <targetConfig targets="…"> block configures one or more targets and defines their properties. Its targets attribute takes a comma-separated list, and every value must match a page type listed under <targets> (L18769, L18966). Inside a block go <property> elements, <supportedFormFactors>, and — for record pages only — <objects>.

Which subtags a targetConfig accepts depends on the target, and the differences are real:

Design Attributes Give Admins Typed Inputs

<property> takes name (must match the @api property in the JS class), type, label, description, default, required, and — depending on type — datasource, min, max, placeholder.

The valid type set is per target, not global:

datasource renders the field as a picklist and is supported only when type is String. It takes either static values (datasource="value1,value2,value3") or an Apex class (datasource="apex://MyCustomPickList") — L18976. Lightning App Builder does not support the Map, Object, or java:// complex types (L9908).

Record-Page Scoping And Auto-Injected Context

<objects> limits the component to a set of objects and works only inside a targetConfig configured for lightning__RecordPage; specify it once per targetConfig; it does not support external objects; and if you omit it the component supports all supported objects (L19363–L19368).

Three public properties are populated by the platform rather than by an admin, and none of them is declared in the meta file — you declare them with @api in the JS class:

• recordId — set to the 18-character record ID when the component is placed in an explicit record context; unset everywhere else, so the component must not depend on it (L7888, L7893).
• objectApiName — set to the API name of the record's object in the same circumstances (L7912–L7913).
• flexipageRegionWidth — receives the width of the App Builder region; CSS class values are SMALL, MEDIUM, LARGE (L7925–L7931).

Experience Builder does not auto-bind recordId or objectApiName; an admin types {!recordId} into the component's Record ID property field (L7894, L7900, L7914).

One-Way Doors

These changes cannot be reversed once the component is in use. Decide them before the first deploy that matters.

Common Patterns

Multi-Surface Reusable Bundle

When to use: One component should appear on Case and Account record pages, on a custom App Page, on the Home page, and on an Experience Cloud page.

How it works: List every target in <targets> (including both lightningCommunity__Page and lightningCommunity__Default for Experience Cloud), then create one <targetConfig> per surface. Scope the record-page target with <objects>, give the App Page target its own property set, and keep Home at Large only. The full bundle is in references/code-examples.md.

Why not the alternative: Cloning the bundle per surface multiplies maintenance cost and drifts admin UX. A single bundle with per-surface targetConfig keeps behavior consistent.

Apex-Backed Dynamic Picklist

When to use: Admins need to pick a field name, record-type developer name, or any other list that depends on org schema.

How it works: Extend VisualEditor.DynamicPickList in Apex, override getValues() and getDefaultValue(), and reference it as datasource="apex://MyPicklistProvider". Add a VisualEditor.DesignTimePageContext constructor parameter when the list must differ by page type or object — the context exposes pageType and entityName (Apex Reference Guide L247696–L247782).

Why not the alternative: A static CSV datasource cannot reflect org-specific schema, and hardcoding the values inside the LWC forces a deploy for every change. The cost is one Apex invocation when the property panel opens, plus a 200-value display ceiling (L248023).

Experience Cloud Pairing

When to use: The component must be draggable in Experience Builder and expose editable properties.

How it works: List lightningCommunity__Page (drag-and-drop into the Components panel) and lightningCommunity__Default (editable properties) as two targets, and put the <property> elements in a targetConfig whose targets is lightningCommunity__Default (L8106–L8110, L18811–L18812). lightningCommunity__Page on its own supports no properties.

Why not the alternative: Declaring only lightningCommunity__Page produces a component admins can place but cannot configure; declaring only lightningCommunity__Default produces properties on a component that never appears in the Components panel.

Decision Guidance

Recommended Workflow

1. Answer the seven questions above and write the surface × property matrix down — one row per target, one column per admin input, plus the object list and form factors. That matrix is the meta file.
2. Copy the bundle skeleton from templates/lwc/component-skeleton/ and the worked multi-target file from references/code-examples.md; set apiVersion (63.0 is the latest release mapped in create-version-alignment L856 — an org can accept up to its own current release, L813).
3. Declare an @api field in the JS class for every property name in the meta file, plus recordId / objectApiName / flexipageRegionWidth if the component uses record or region context. Give each one a JS-side initializer — Jest never reads the meta file (unit-testing-using-jest-create-tests L12326).
4. If any property needs a schema-driven list, write the VisualEditor.DynamicPickList class and its test alongside the bundle (both are in references/code-examples.md), and remember the Apex class must be in the same deploy or the property panel breaks.
5. Run python3 skills/lwc/lwc-app-builder-config/scripts/check_lwc_app_builder_config.py --manifest-dir force-app/main/default and fix every ERROR; add --strict in CI to fail on WARNs too.
6. Run the Jest suite (npm run test:unit) to pin the property defaults and setter behaviour, then deploy Apex before the bundle and drop the component from each configured surface in App Builder / Experience Builder.
7. Before the change ships to a package or a live site, re-read the one-way-door table and confirm nothing in this deploy is a door you did not mean to close.

Review Checklist

• [ ] <isExposed>true</isExposed> is present and <targets> is non-empty.
• [ ] <apiVersion> is set — Spring '25 and later require it to save changes (L796–L798).
• [ ] Every targetConfig targets="…" value also appears inside <targets>.
• [ ] Every <property name="x"> has a matching @api x in the JS class.
• [ ] <property type="…"> uses only the values documented for that target — no Color on App Builder targets, no Picklist anywhere.
• [ ] <objects> appears only inside a lightning__RecordPage targetConfig, and record-page exposure is either scoped or scoped-by-decision.
• [ ] Form factors use <supportedFormFactor type="…"/>, live inside a targetConfig, and omit Small for Home pages.
• [ ] Every required="true" property also has a default (L9899).
• [ ] Every apex:// datasource names a class present in the same deployment.
• [ ] <masterLabel> and <description> are filled in and read well in the builder.

Salesforce-Specific Gotchas

The full set, with what happens / when it occurs / how to avoid, is in references/gotchas.md. In one line each:

1. supportedFormFactor — not supported — is the child tag, and the attribute is type.
2. Color is not a documented App Builder property type; it is an Experience Cloud and Email Builder type.
3. <objects> outside a record-page targetConfig scopes nothing.
4. Omitting <objects> opens the component to every UI-API-supported object.
5. lightning__Tab accepts neither property nor supportedFormFactor.
6. Form factors, object tags, page-type support and min/max all freeze once the component is placed.
7. A packaged, exposed component can never drop a target or an @api property.
8. Experience Builder does not auto-bind recordId; an admin must type {!recordId}.
9. A dynamic picklist displays only its first 200 values unless containsAllRows says otherwise.
10. Jest never reads the meta file, so a green test proves nothing about a meta-file default.

Output Artifacts

Reference Files

Related Skills

• lwc/lwc-base-component-recipes — once the component is exposed, use base components inside it for standard admin UX.
• lwc/custom-property-editor-for-flow — owns custom property editors; use when Flow-side config outgrows typed design attributes.
• lwc/experience-cloud-lwc-components — owns Experience Cloud specifics: CSP levels, LWR, theming, custom property types.
• lwc/lwc-in-flow-screens — owns Flow-screen component design: role, propertyType, output attributes, FlowAttributeChangeEvent.
• lwc/lwc-quick-actions — owns lightning__RecordAction components: headless vs screen actions, CloseActionScreenEvent, invoke().
• lwc/lwc-offline-and-mobile — owns what actually happens on the Small form factor at runtime.
• lwc/component-communication — owns the event / schema payload design once Dynamic Interactions are declared here.
• lwc/lwc-testing — owns Jest depth beyond the default-pinning tests in this skill.

Package files

• references/code-examples.md
• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/lwc-app-builder-config-template.md
• scripts/check_lwc_app_builder_config.py