What is the current behavior?

Following on from #6384 it surfaced a number of rough edges Stencil has around serializing properties to attributes and de-serializing attributes to properties.

Previously, Stencil has 'baked-in' certain serialization behaviours then use meta heuristics to decide when to use them.

e.g. 'When a property has an unknown type, it's incoming set value is a string, and that string starts with [ or { let's JSON parse()'

This behaviour is opaque and error-prone.

What is the new behavior?

Fixes #6247
Partially fixes #6216
Partially fixes #5110

2 new decorators have been added @PropSerialize and @AttrDeserialize - both having a similar footprint as the @Watch decorator.

@PropSerialize allows devs to explicitly set property > attribute serializers - turning a complex value into a string.
A good use case might be to use this only on the server during SSR - the serialized value being stringified in the resulting HTML can be ingested during client-side hydration.

@AttrDeserialize allows devs to explicitly set attribute > property translators. So setting a date attribute value of 2025-09-16 can now be immediately translated into a Date object.

Documentation

import { AttrDeserialize, Build, Component, h, Prop, PropSerialize } from '@stencil/core';

interface User {
  userName: string;
  avatarUrl: string;
  posts: any[]
}

@Component({
  tag: 'user-login-panel',
})
export class UserLogin {
  @Prop() user: User;

  // On the server *only* let's represent the user's data as an attribute
  // this allows the browser to get the data immediately without having to do a client-side fetch

  @PropSerialize('user')
  userSerialize(newVal: User) {
    if (Build.isBrowser) {
      return null;
    } 
    try { return JSON.stringify(newVal); } 
    catch (e) { return null; }
  }
  
  // Whenever we have an attribute (including on client init)
  // let's turn it back into an object that we can use and render

  @AttrDeserialize('user')
  userDeserialize(newVal: string) {
    try { return JSON.parse(newVal); } 
    catch (e) { return null; }
  }

  async componentWillLoad() {
    
    // On the server *only*, let's do a secret login involving private keys etc.
    
    if (Build.isServer) {  
      // Because we have a serializer method, 
      // setting a value automatically reflects it to the dom attribute 
      
      this.user = login(credentials);
    }    
  }

  render() {
    if (this.user) return (`Welcome ${this.user.userName}!`);
    else return (`Please login`);
  }
}

TODO - update docs site

Does this introduce a breaking change?

• Yes
• No

Testing

• New unit tests, testing desired compiler output
• New spec tests within Jest checking deserialize / serialize behaviour within mockdoc
• New wdio component tests checking deserialize / serialize behaviour within browser. New SSR > Client hydration test checking a common workflow
• Updated e2e tests that were removed in fix(runtime): stop eager json parsing for unknown and any type bindings #6384; re-implementing tests using the new decorators

Other information