fix(angular-server): fallback to scoped+annotations when SSR DOM lacks attachShadow

[SebastianKohler]

Issue number: resolves #29751

What is the current behavior?

In Angular SSR environments using a server DOM that does not implement native attachShadow (for example Domino), Ionic server hydration can fail with:

TypeError: this.attachShadow is not a function

This occurs in the server hydrate path used by @ionic/angular-server when calling hydrateDocument(...) with the current default behavior.

What is the new behavior?

This PR adds a capability check in packages/angular-server/src/ionic-server-module.ts and applies a conditional fallback only when attachShadow is unavailable:

• if attachShadow is supported:
  • keep existing behavior (clientHydrateAnnotations: false)
• if attachShadow is not supported:
  • use serializeShadowRoot: 'scoped'
  • use clientHydrateAnnotations: true

This keeps the current behavior for environments with native attachShadow, while providing a compatible SSR path for Domino-like environments.

Does this introduce a breaking change?

• Yes
• No

Other information

The change is intentionally scoped to @ionic/angular-server integration logic and does not modify component behavior or the existing excludeComponents list.

I could not run the full Ionic test/lint suite locally in my current Windows environment setup, so this PR relies on CI for full validation.

Note: this PR addresses the attachShadow SSR crash path in @ionic/angular-server by applying a conditional fallback.

From upstream investigation, there is also a Stencil runtime fix in >= 4.40.0 related to non-shadow component patching (children/childNodes) that may affect Angular client hydration behavior. So full end-to-end resolution of all symptoms may also depend on the Stencil bump tracked separately.

[vercel]

@SebastianKohler is attempting to deploy a commit to the Ionic Team on Vercel.

A member of the Team first needs to authorize it.

[SebastianKohler]

@gnbm Are there any plans from the Ionic team to take a look at this PR? I see you are hard at work developing Angular 21 och 22 support for Ionic v9 due in Q3 2026, but does that include Angular SSR support? Angular SSR has not worked in Ionic since v8.2.2, which this PR attempts to fix.

Btw, I love the fact that your focus for v9 is to "keep up" rather than implement new features 👍👍

[ShaneK]

Hey @SebastianKohler! Thanks for the PR. It looks fine, but a couple of concerns:

• There's no tests for this fallback functionality. Is there a way to add tests for this?
• You seem uncertain whether this will close bug: elm.attachShadow is not a function TypeError in Angular SSR app since Ionic v8.2.4 #29751 without a stencil update. Can we verify for sure if no future changes will be needed for that to be resolved?

[SebastianKohler]

I tested the PR fallback against Ionic 8.8.13, which bundles Stencil 4.43.5. The server-side attachShadow error is gone and Stencil produces rendered SSR output. However, the browser test exposed a remaining Angular hydration failure:

TypeError: e.hasAttribute is not a function

The minified function maps to Angular’s hasSkipHydrationAttrOnRElement. Stencil’s clientHydrateAnnotations: true inserts a <!--r.*--> marker before <ion-button>, which Angular expects to hydrate as the next element. Angular encounters the comment instead.

Stencil 4.40+ contains the fix for the related non-shadow DOM traversal issue (the current test confirms ion-app.children.length === 1), but it does not resolve this Angular/Stencil hydration-marker conflict.

A useful regression test would need to load the SSR result with Angular client hydration, assert that there are no page/console errors, and verify that the <ion-button> host is no longer hidden and contains exactly one native control in its shadow root. That test currently fails with the PR.

I published the exact verification setup here: https://github.com/SebastianKohler/ionic-angular-ssr-attachShadow-typeError/tree/codex/verify-pr-30967. It pins Ionic 8.8.13, which bundles Stencil 4.43.5, and applies the PR implementation locally. SSR completes successfully, but Angular client hydration still fails because Stencil’s annotations alter the expected node order.

I’m sharing this reproduction and diagnosis so the Ionic team has a concrete starting point. I won’t be able to continue investigating the Angular/Stencil hydration interaction or develop the framework-level fix. Given the remaining client-side failure, I don’t think this PR can currently be considered a complete resolution of #29751. I’ll leave it to the maintainers to decide whether the server-side fallback has value independently or whether the PR should be closed.

[SebastianKohler]

One important clarification to my previous comment: Angular client hydration is optional.

I repeated the test after removing provideClientHydration() from app.module.ts. With the same PR fallback on Ionic 8.8.13/Stencil 4.43.5, the application then works end-to-end without server or browser errors.

Without Angular client hydration, Angular replaces the server-rendered DOM during client bootstrap instead of reconciling it. Consequently, Angular does not encounter the Stencil hydration markers that caused the failure described in my previous comment.

This means the PR appears to be a working fix for Angular SSR applications that do not enable provideClientHydration(). The remaining marker conflict is specific to applications using Angular client hydration.

The original reproduction has always included provideClientHydration(), but my earlier testing with Ionic 8.2.2 only verified the absence of the server-side attachShadow error. I did not verify whether Angular client hydration worked in that version, so I cannot characterize the browser failure as a regression from 8.2.2.

Therefore, if #29751 is scoped to the server-side error and SSR without Angular client hydration, the PR appears to resolve it. If Ionic intends to support Angular client hydration as well, that path still requires additional work.