Diagnosing StencilJS @State/@Prop Re‑render Issues Caused by In‑place Mutations

Recognizable condition

You have a Stencil component whose template reads a property decorated with @State or @Prop. The property holds an array or an object. When you call a method that mutates the value in‑place (e.g., myArray.push(item) or myObj.foo = 42), the method executes but the UI does not update. No error appears in the console.

Short cause/diagnostic table

Symptom	Likely cause	Why it happens
Template does not change after push or property assignment	In‑place mutation leaves the reference unchanged	Stencil’s change detection compares the previous and current reference of the decorated property; if the reference is identical, no re‑render is scheduled.
Method runs but no update, even after @Watch on the property	Watcher only fires on reference changes	@Watch reacts to a new reference, not to deep mutations inside the same object/array.

Ordered checks

1. Confirm the property decorator
   • Open the component source file (src/components//.tsx).
   • Look for @State() or @Prop() directly above the property declaration.
   • If the property is @Prop, remember it is read‑only inside the component; assigning to it will cause a TypeScript error in strict mode.
2. Identify the mutation pattern
   • Search the component for lines that modify the property without reassigning it, such as:
   • this.items.push(newItem)
   • this.user.name = 'Ada'
   • this.data[0].value = 10
   • Note whether the code creates a new array/object (e.g., spread, Object.assign, [{...item}]) before assignment.
3. Verify that the template actually binds the property
   • In the component’s render method, ensure you reference the property directly, e.g., {this.items.map(i => <li>{i}</li>)} or {this.user.name}.
   • If you only use the property inside a child component via a prop, confirm the child receives the same reference.
4. Check for build caching that may hide changes
   • Run a clean build: npm run build -- --prod (or stencil build --prod if you have the CLI installed globally).
   • Delete the www or dist folder before rebuilding to ensure stale output is not served.

Fixes tied to findings

Immutable update for @State

Replace in‑place mutations with assignments that create a new reference.

// ❌ In‑place push (no re‑render)
addItem(item) {
  this.items.push(item);
}

// ✅ Immutable push (triggers re‑render)
addItem(item) {
  this.items = [...this.items, item];
}

// ❌ In‑place object property change
updateName(name) {
  this.user.name = name;
}

// ✅ Immutable object update
updateName(name) {
  this.user = { ...this.user, name };
}

Run the component after making the change and observe the UI update.

Using @Watch for external @Prop changes

If the property is a @Prop supplied by a parent and you need to react when the parent replaces the whole array/object, add a watcher:

@Prop() items: any[];

@Watch('items')
itemsChanged(newVal, oldVal) {
  // newVal is a different reference; you can safely recompute derived state
  this.processedItems = newVal.map(i => ({ ...i, processed: true }));
}

Note: @Watch will not fire for mutations that keep the same reference; you must still rely on immutable updates from the parent side.

Lifting state to a parent

When deep nested updates are frequent, consider moving the mutable state to a parent component and passing down a new reference each time:

// Parent
render() {
  return (
    <child-component
      items={this.parentItems}   {/* new reference after mutation */}
      onItemAdded={this.handleAdd}
    />
  );
}

handleAdd(item) {
  this.parentItems = [...this.parentItems, item];
}

The child receives a fresh reference, triggering its own render.

Escalation criteria

If after applying immutable updates the template still does not re‑render:

1. Validate the build output
   • Examine the generated component code (www/build/.js) for the property decorator and any watcher metadata. Look for lines like __decorate([State()], ...).
   • If the decorator is missing, ensure you are not accidentally compiling a different version of the file (e.g., a stale copy in node_modules).
2. Add temporary diagnostics
   • Insert a console.log inside render() or componentDidUpdate() to confirm whether the method is being called after your change.
   • Example:

   render() {
     console.log('render called, items length:', this.items.length);
     return ...
   }
   

3. Test in a minimal reproduction
   • Create a new component with only a single @State() items: any[] = []; and a button that calls this.items = [...this.items, {}].
   • If the minimal case works, the issue lies in interactions with other properties, child components, or Stencil plugins in your original component.
4. Check Stencil version and changelog
   • Run npm list @stencil/core to see the installed major version.
   • Review the release notes for that version (e.g., v4.x introduced async rendering changes). If you suspect a version‑specific bug, consider upgrading to the latest patch within the same major line.

Practical way to verify the fix

After applying an immutable update:

1. Run the dev server: npm start (or stencil dev).
2. Open the component in a browser and open the developer tools console.
3. Trigger the mutation (e.g., click the “Add item” button).
4. Observe the console for the temporary log you added in render() or componentDidUpdate(). A new log entry indicates a re‑render occurred.
5. Visually confirm the UI reflects the change (new list item appears, updated text shows).

If the log appears and the UI updates, the fix is successful. If the log does not appear, revisit the checks above.

Limitations

• Immutable updates may create extra garbage‑collection pressure for large arrays; consider using libraries like immer if performance becomes a concern.
• @Watch does not deep‑watch; nested changes still require a new reference from the owner.
• The behavior described assumes Stencil’s default change detection. Custom configurations that enable experimental features (e.g., enableAsyncRendering: true) may alter when watchers fire, but the reference‑based rule remains.