Lwc Public API Hardening

LWC Public API Hardening

Activate this skill when an LWC ships @api properties, @api methods, or admin-facing design attributes in <targetConfig> and the public surface needs to be defensive, well-typed at runtime, and survivable against unexpected input from parents, App Builder admins, Flow runtime, or programmatic instantiation. The fundamental thing to internalise: @api is a binding decorator, not a type checker. Anything you declare ends up as whatever JavaScript value the host hands you — most commonly a string, even when you wrote @api recordId; and your IDE shows a string annotation.

This is NOT about choosing how components talk to each other (component-communication covers that), NOT about App Builder surface targeting (see lwc-app-builder-config), and NOT about Custom Property Editors for Flow (see custom-property-editor-for-flow).

Before Starting

Gather this context before changing any @api surface:

• Every public touchpoint. List every @api property, every @api method, and every <property> block inside every <targetConfig> in .js-meta.xml. The public surface is the union of those three lists, not just the JS file.
• The most common wrong assumption. Authors almost always assume the LWC engine validates @api types at runtime. It does not. TypeScript-style annotations (whether via JSDoc @type {number} or a .ts-style comment) compile away — at runtime @api recordId and @api count are both just whatever the parent assigned, which is usually a string from HTML / App Builder / Flow.
• Default-value scope. default on a <property> in <targetConfig> is applied by App Builder when an admin drops the component on a page. It is NOT applied when (a) you instantiate the component programmatically via lwc.createElement(...), (b) you put the component directly inside another LWC's template, or (c) you use it on a Visualforce page. In those cases the property is plain undefined until the parent assigns it.
• Form-factor / container quirks. <lightning__FlowScreen> design attributes use propertyType for object inputs (Flow only — not valid in <lightning__AppPage> or <lightning__RecordPage>). HTML attribute parsing converts false / true to strings, not booleans, which bites when consumers use the component declaratively.

Core Concepts

1. @api does not enforce JavaScript types — only binds the property

@api exposes a property to the parent and (for primitive values from HTML) makes attribute writes flow into property writes. It does not coerce, validate, default, or constrain the value. The classic example is @api recordId: the framework documentation says it is "the record ID injected by the host page", and consumers infer the type is a Salesforce Id (a string of length 15 or 18). But on a Flow screen with a manually wired input, on a programmatically instantiated component, or in a Jest test, you can set it to a number, an object, null, or undefined. The component must tolerate every shape it can receive — a setter is the only place you can guarantee the value gets normalised before it lands in component state.

The same holds for @api method(). Nothing prevents a parent from calling myMethod('not a record id') when you expected myMethod(['a','list']). The argument list is whatever the caller passes, full stop.

2. Design attribute types are admin-facing strings until App Builder coerces them

Inside <property> you declare a type (String, Boolean, Integer, Color). At the App Builder UI level the admin gets a typed editor and Salesforce coerces what they enter to that type before assigning it to the @api property. But when the same component is dropped on a Flow screen or instantiated from another LWC's template, no coercion happens — the value flows through verbatim. Boolean attributes from HTML markup (<c-foo enabled="false">) are particularly nasty: the attribute value is the string "false", which is truthy, so a naive if (this.enabled) { ... } runs. Always coerce inside the setter.

3. Required-vs-optional has no enforcement layer

There is no @api required decorator. There is no js-meta.xml flag that fails the deploy when an admin drops the component without setting a property. The only place to enforce a required input is in connectedCallback (or in the setter, if you need to react before connection). Throwing during connectedCallback aborts the render with a stack trace in the console — that is your enforcement; choose whether you'd rather throw, log + return early, or render a fallback "configuration missing" template.

4. Reactive @api and the getter/setter trap

Plain @api foo; is reactive: when the parent reassigns it, the template re-renders. As soon as you replace it with a @api get foo() / set foo(v) pair, the underlying field the setter writes to must be tracked (decorated with @track or be a primitive on this) for re-renders to fire. A common bug is to write set foo(v) { this._foo = normalise(v); } and never re-render because the field _foo is not tracked and the getter's return value depends on it. Either keep the underlying value as a primitive on this (LWC tracks all primitive class fields automatically) or store complex shapes inside an @track-friendly structure.

Common Patterns

Pattern: Defensive setter with coercion

When to use: any @api property that receives values from HTML attributes, Flow runtime, or App Builder — i.e. the vast majority of them.

How it works:

import { api, LightningElement } from 'lwc';

export default class HardCounter extends LightningElement {
    _count = 0;

    @api
    get count() { return this._count; }
    set count(value) {
        // App Builder may pass a string; HTML attribute parsing always does.
        const n = Number(value);
        this._count = Number.isFinite(n) ? n : 0;
    }
}

Why not the alternative: if you skip coercion and write @api count = 0;, then <c-hard-counter count="3"> ends up with this.count === '3'. The === 0 falsy default looks correct in unit tests (where you assign a number) but is wrong in App Builder (where you get a string).

Pattern: Required-prop guard in connectedCallback

When to use: any property whose absence makes the component meaningless (e.g. recordId on a record-context component, topicId on a knowledge widget).

How it works:

connectedCallback() {
    if (!this.recordId) {
        // Hard fail — visible in console, surfaced to LWS.
        throw new Error('c-account-summary requires `record-id` to be set');
    }
}

For Flow screens, prefer setting an errorMessage property and rendering a fallback — Flow halts the screen on uncaught errors, which is harsh UX:

connectedCallback() {
    if (!this.topicId) {
        this.errorMessage = 'Configure the Topic Id in the Flow screen builder.';
    }
}

Pattern: Method that should be an event

When to use: the parent component currently calls child.refresh() after some user action.

How it works:

Replace the @api refresh() method with a CustomEvent flowing the other direction. The child should announce when it's ready / requesting refresh, the parent reacts:

// Inside child — instead of `@api refresh()`:
handleSaveSucceeded() {
    this.dispatchEvent(new CustomEvent('saved', { detail: { id: this.recordId } }));
}

<!-- Inside parent -->
<c-child

Why not the alternative: @api refresh() welds the parent to the child's internal lifecycle and is a recursion magnet (parent calls refresh(), refresh fires the event the parent listens to, parent calls refresh() again). Events are a one-way contract; the parent decides whether to act.

Pattern: Design attribute with admin-facing default and datasource

When to use: App Builder–facing properties where the admin is choosing from a known small set, or wiring a field name from the bound SObject.

How it works: in .js-meta.xml:

<targets><target>lightning__RecordPage</target></targets>
<targetConfigs>
    <targetConfig targets="lightning__RecordPage" objects="Account,Contact">
        <property
            name="primaryField"
            label="Primary field"
            type="String"
            default="Name"
            datasource="Name,AccountNumber,Industry"
            description="Field to display as the headline." />
        <property
            name="maxRows"
            label="Max rows"
            type="Integer"
            default="5"
            min="1"
            max="50" />
    </targetConfig>
</targetConfigs>

Then in .js, still coerce inside the setter — default only applies when the admin uses App Builder; programmatic callers get undefined.

Decision Guidance

Recommended Workflow

Step-by-step instructions for hardening an existing component's public API:

1. Inventory the public surface. Open <name>.js and <name>.js-meta.xml. List every @api property, every @api method, and every <property> inside every <targetConfig>. Note which ones currently have setters, which are bare fields, and which method names look like they should be events (refresh, update, notify).
2. Classify required vs optional. For each @api property, ask: does the component crash, render nothing useful, or silently misbehave when this is undefined? If yes, mark it required. If no, mark it optional and decide a sensible default.
3. Convert bare @api fields to getter/setter pairs where coercion is needed. Use the "Defensive setter" pattern above. Coerce strings to numbers, "true"/"false" strings to booleans, normalise nullish to a chosen default.
4. Add a connectedCallback guard for required props. Throw or render a fallback. Document the choice in a JSDoc comment on the class.
5. Audit @api methods. For each one, ask: "Could a CustomEvent in the other direction replace this?" If yes, refactor. If no, document the imperative contract in a JSDoc comment so consumers know the input shape and the side effects.
6. Type the design attributes in .js-meta.xml. Set explicit type, default, min/max (for Integer), and datasource (for fixed-set String). For Flow targets only, use propertyType if accepting an SObject. Verify kebab-case attribute names map to the camelCase JS property as expected.
7. Run the checker. python3 skills/lwc/lwc-public-api-hardening/scripts/check_lwc_public_api_hardening.py <bundle-path>. Fix every P0 and P1 finding before marking complete.

Review Checklist

Run through these before marking work in this area complete:

• Every @api property that can receive a string from HTML/App Builder has a setter that coerces to the intended type.
• Every required @api property is validated in connectedCallback (throw, log + early return, or fallback render).
• No @api method exists that could be replaced with a CustomEvent — methods are reserved for genuine imperative actions.
• No @api getter returns a value derived from a non-tracked, non-primitive backing field.
• Every design attribute has explicit type, default (where applicable), and datasource or min/max (where applicable).
• Boolean design attributes have setters that coerce string "false" to boolean false.
• No @api property leaks an internal mutable structure that the parent could mutate by reference.
• python3 skills/lwc/lwc-public-api-hardening/scripts/check_lwc_public_api_hardening.py <bundle-path> exits 0.

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. @api recordId is always a string. Even when surrounded by code that says Number(...) or has a @type {number} comment. The host page assigns the string Id; the framework does not coerce.
2. default on a design property does NOT apply to programmatic instantiation. A unit test that does createElement('c-foo', { is: Foo }) gets undefined for every property until the test explicitly assigns it. The same is true for one LWC including another in its template.
3. Boolean attributes from HTML are strings. <c-foo enabled="false"> results in this.enabled === 'false' (truthy). HTML knows nothing about JS types.
4. Design attribute names are kebab-case in markup, camelCase in JS. <property name="maxRows"> becomes @api maxRows (not max-rows). The XML attribute name is the internal key; it must follow the JS identifier convention except when used inline in HTML where attributes are kebab-case.
5. Default values in <targetConfig> are scoped to that target. A default="5" inside <targetConfig targets="lightning__RecordPage"> does not apply when the same component is dropped on lightning__AppPage. Each target needs its own <targetConfig> block with its own defaults.
6. propertyType is Flow-only. Using propertyType inside a non-Flow <targetConfig> either deploys quietly and is ignored, or fails deploy depending on org version. Object-typed inputs only work for <lightning__FlowScreen>.
7. Namespaced design attributes need the namespace prefix. When referenced from an installed package, c__myProperty is the resolved name, not myProperty. Author components in unmanaged orgs without the prefix to avoid confusion, but be aware of the package case.

Output Artifacts

Related Skills

• lwc/component-communication — choosing between @api, CustomEvent, LMS, and Pub/Sub for component-to-component communication
• lwc/lwc-app-builder-config — targets, targetConfigs, supportedFormFactors, and surface-level exposure rules in .js-meta.xml
• lwc/custom-property-editor-for-flow — when the design-attribute editor itself needs to be a custom LWC (Flow only)
• lwc/lwc-custom-event-patterns — naming, bubbling, composed events, and detail payload conventions
• lwc/lifecycle-hooks — semantics of connectedCallback, renderedCallback, and disconnectedCallback referenced by the hardening guards