fix(ssr): improved SSR handling in Next.js by christian-bromann · Pull Request #641 · stenciljs/output-targets

christian-bromann · 2025-05-19T23:36:16Z

Pull request checklist

This PR polishes the SSR process within Next.js applications and elsewhere. It addresses the following issues:

Variable Support

Before passing it property values as variables would not work, e.g.:

// ❌ variable would not be resolved
const val = "hello world"
return <MyComponent prop={val} />

We now properly resolve the value if defined in the right scope, however this still will fail if the value is dynamically generated as we don't have access to its value and compile time, e.g.:

// ✅ variable is being resolved
const val = "hello world"
// ❌ variable resolved at runtime will still fail
const otherVal = someFunction()
return <MyComponent prop1={val} prop2={otherVal} />

Transform Components from other sources

If a component is imported from a different location (outside of the pages or app folder), it wouldn't be transformed properly, removing all SSR support for these components. This has been fixed by adjusting the Webpack loader.

Support for Spread Properties

Before using spread properties would cause a failure, e.g.:

// ❌ this would fail
const props = { first: "Hello", last: "World" }
return <MyComponent {...props} />

With this patch, it is now supported.

Support for Non-Dev Environments

In previous versions we would only check for jsxDev calls on Stencil components to do the right AST transformation. This has been extended and also supports production jsx calls.

Reduction of Hydration Errors in Next.js

Using @stencil/ssr in Next.js would still cause Hydration errors given that the template tag of the DSD would be removed (and replaced with a Shadow DOM). This has caused hydration errors and potential re-rendering of the component, destroying the ShadowRoot completely.

This is now being resolved by using the dynamic primitive of Next.js to tell it to replace the SSR rendered component with the runtime version of it, e.g. we modify the source file to wrap the component as following:

import dynamic from 'next/dynamic';
const compImport = import('component-library-react');

const getMyInput$0 = ({ children }) => dynamic(
  () => compImport.then(mod => mod.MyInput),
  {
    ssr: false,
    loading: () => (<>
      <my-input class="hydrated" s-id="17">
        <template shadowrootmode="open" shadowrootdelegatesfocus="true" dangerouslySetInnerHTML={{ __html: `<input aria-labelledby="my-input-0-lbl" autocapitalize="off" autocomplete="off" autocorrect="off" c-id="17.0.0.0" class="native-input" name="my-input-0" placeholder="" type="text" value="">` }}></template>
        {children}
      </my-input>
    </>)
  }
)

⚠️ Warning: this still causes issues when your components use slots as Next.js injects <template data-dgst="BAILOUT_TO_CLIENT_SIDE_RENDERING" data-msg="Bail out to client-side rendering: next/dynamic" data-stck="..." /> which (afaik) can't be disabled causing your component to deal with undesired child nodes, e.g.:

<MyStencilComponent>
  <template ...>
  <ExpectedSlotNode />
  <template ...>
  <ExpectedSlotNode />
</MyStencilComponent>

While the template tag doesn't render anything, it may be picked as slot component, causing issues in rendering.

Please check if your PR fulfills the following requirements:

Tests for the changes have been added (for bug fixes / features)
Docs have been reviewed and added / updated if needed (for bug fixes / features)
Build (npm run build) was run locally for affected output targets
Tests (npm test) were run locally and passed
Prettier (npm run prettier) was run locally and passed

Pull request type

Please check the type of change your PR introduces:

Does this introduce a breaking change?

Yes
No

Other information

Updated SSR docs: stenciljs/site#1525

Fixes #644

example-project/next-15-react-19-app/test/test.e2e.ts

example-project/react-app/tests/test.e2e.ts

christian-bromann · 2025-05-22T23:39:51Z

Update:

I spend more time trying to update for Next.js applications and made some progress. This has become much more complex as anticipated. Unfortunately while we see improvements in Next.js, we see now issues in Remix and React+Vite. I will take another stab at this tomorrow and next week. In the meantime I would appreciate feedback especially if you use Next.js. A dev build is available via:

npm i @stencil/ssr@0.0.1-dev.11747956973.17340fd0

Also I updated the docs and published a preview: https://stencil-docs-git-cb-ssr-doc-improvements-ionic1.vercel.app/docs/next/server-side-rendering

## [0.2.0](https://github.com/stenciljs/output-targets/compare/@stencil/ssr@0.1.0...@stencil/ssr@0.2.0) (2026-01-03) ### 🚀 Enhancement * **react:** enhance React output target with unified server/client imports and improved SSR property serialization ([132f9d9](132f9d9)) * Upgraded component-library-angular to Angular 20 and added a new Angular app to example-project ([#652](#652)) ([a6fefb6](a6fefb6)), closes [#643](#643) * **vue:** implement custom event property as source for v-model ([#689](#689)) ([bc385bb](bc385bb)) ### 🐛 Bug Fix * **#646:** react create components.ts file ([#647](#647)) ([7524cbf](7524cbf)), closes [#646](#646) [#646](#646) * **angular:** include outputs in angular component definition ([#688](#688)) ([16f1fd1](16f1fd1)), closes [#643](#643) [#643](#643) * **angular:** prettify code ([69e1cba](69e1cba)) * **angular:** use forwardRef in control value accessor directives. ([#697](#697)) ([dcb4bd2](dcb4bd2)) * **ci:** run in macos environment ([0631306](0631306)) * **dependabot:** don't run updates based on projects ([3d43687](3d43687)) * **dependabot:** group updates of minor and patch versions in a single PR ([47bdb20](47bdb20)) * **dependabot:** optimize configuration ([ce29757](ce29757)) * **internal:** update changelog ([4bb6cfc](4bb6cfc)) * nuxt ssr mismatch class errors ([#651](#651)) ([be797b1](be797b1)) * **react:** always use per-component CustomEvent types for event props ([#716](#716)) ([8ebba85](8ebba85)), closes [#531](#531) * **react:** better style to css transformation ([ccc76a7](ccc76a7)) * **react:** fixed wording in component wrapper ([a83bb4b](a83bb4b)) * **react:** forward ref to underlying web component ([#655](#655)) ([9f20ee0](9f20ee0)) * **react:** improved SSR for Next.js ([#683](#683)) ([c49a3b5](c49a3b5)) * **react:** make types compatible with v18 and v19 ([f887ae7](f887ae7)) * **react:** properly type generated component files ([3e7cc0c](3e7cc0c)) * **react:** revive esModules option ([d98df24](d98df24)) * revert model update event renaming ([#649](#649)) ([5c67692](5c67692)) * **ssr:** improved SSR handling in Next.js ([#641](#641)) ([22e075f](22e075f)) * **vue:** remove unnecessary vue patch ([34f7ce2](34f7ce2)) ### 📝 Documentation * **internal:** link release workflow ([0e69d0e](0e69d0e)) * **internal:** update contributing guidelines ([08c96fd](08c96fd))

* chore(release): @stencil/vue-output-target@0.11.0 [skip ci] ## [0.11.0](https://github.com/stenciljs/output-targets/compare/@stencil/vue-output-target@0.10.8...@stencil/vue-output-target@0.11.0) (2026-01-03) ### 🚀 Enhancement * **react:** enhance React output target with unified server/client imports and improved SSR property serialization ([132f9d9](132f9d9)) * **vue:** implement custom event property as source for v-model ([#689](#689)) ([bc385bb](bc385bb)) ### 🐛 Bug Fix * **angular:** include outputs in angular component definition ([#688](#688)) ([16f1fd1](16f1fd1)), closes [#643](#643) [#643](#643) * **angular:** prettify code ([69e1cba](69e1cba)) * **angular:** use forwardRef in control value accessor directives. ([#697](#697)) ([dcb4bd2](dcb4bd2)) * **dependabot:** don't run updates based on projects ([3d43687](3d43687)) * **dependabot:** group updates of minor and patch versions in a single PR ([47bdb20](47bdb20)) * **dependabot:** optimize configuration ([ce29757](ce29757)) * **internal:** update changelog ([4bb6cfc](4bb6cfc)) * **react:** always use per-component CustomEvent types for event props ([#716](#716)) ([8ebba85](8ebba85)), closes [#531](#531) * **react:** better style to css transformation ([ccc76a7](ccc76a7)) * **react:** forward ref to underlying web component ([#655](#655)) ([9f20ee0](9f20ee0)) * **react:** improved SSR for Next.js ([#683](#683)) ([c49a3b5](c49a3b5)) * **react:** properly type generated component files ([3e7cc0c](3e7cc0c)) * **vue:** remove unnecessary vue patch ([34f7ce2](34f7ce2)) ### 📝 Documentation * **internal:** link release workflow ([0e69d0e](0e69d0e)) * **internal:** update contributing guidelines ([08c96fd](08c96fd)) * chore(release): @stencil/react-output-target@1.2.1 [skip ci] ## [1.2.1](https://github.com/stenciljs/output-targets/compare/@stencil/react-output-target@1.2.0...@stencil/react-output-target@1.2.1) (2026-01-03) ### 🚀 Enhancement * **vue:** implement custom event property as source for v-model ([#689](#689)) ([bc385bb](bc385bb)) ### 🐛 Bug Fix * **angular:** include outputs in angular component definition ([#688](#688)) ([16f1fd1](16f1fd1)), closes [#643](#643) [#643](#643) * **angular:** use forwardRef in control value accessor directives. ([#697](#697)) ([dcb4bd2](dcb4bd2)) * **react:** always use per-component CustomEvent types for event props ([#716](#716)) ([8ebba85](8ebba85)), closes [#531](#531) ### 📝 Documentation * **internal:** link release workflow ([0e69d0e](0e69d0e)) * **internal:** update contributing guidelines ([08c96fd](08c96fd)) * chore(release): @stencil/ssr@0.2.0 [skip ci] ## [0.2.0](https://github.com/stenciljs/output-targets/compare/@stencil/ssr@0.1.0...@stencil/ssr@0.2.0) (2026-01-03) ### 🚀 Enhancement * **react:** enhance React output target with unified server/client imports and improved SSR property serialization ([132f9d9](132f9d9)) * Upgraded component-library-angular to Angular 20 and added a new Angular app to example-project ([#652](#652)) ([a6fefb6](a6fefb6)), closes [#643](#643) * **vue:** implement custom event property as source for v-model ([#689](#689)) ([bc385bb](bc385bb)) ### 🐛 Bug Fix * **#646:** react create components.ts file ([#647](#647)) ([7524cbf](7524cbf)), closes [#646](#646) [#646](#646) * **angular:** include outputs in angular component definition ([#688](#688)) ([16f1fd1](16f1fd1)), closes [#643](#643) [#643](#643) * **angular:** prettify code ([69e1cba](69e1cba)) * **angular:** use forwardRef in control value accessor directives. ([#697](#697)) ([dcb4bd2](dcb4bd2)) * **ci:** run in macos environment ([0631306](0631306)) * **dependabot:** don't run updates based on projects ([3d43687](3d43687)) * **dependabot:** group updates of minor and patch versions in a single PR ([47bdb20](47bdb20)) * **dependabot:** optimize configuration ([ce29757](ce29757)) * **internal:** update changelog ([4bb6cfc](4bb6cfc)) * nuxt ssr mismatch class errors ([#651](#651)) ([be797b1](be797b1)) * **react:** always use per-component CustomEvent types for event props ([#716](#716)) ([8ebba85](8ebba85)), closes [#531](#531) * **react:** better style to css transformation ([ccc76a7](ccc76a7)) * **react:** fixed wording in component wrapper ([a83bb4b](a83bb4b)) * **react:** forward ref to underlying web component ([#655](#655)) ([9f20ee0](9f20ee0)) * **react:** improved SSR for Next.js ([#683](#683)) ([c49a3b5](c49a3b5)) * **react:** make types compatible with v18 and v19 ([f887ae7](f887ae7)) * **react:** properly type generated component files ([3e7cc0c](3e7cc0c)) * **react:** revive esModules option ([d98df24](d98df24)) * revert model update event renaming ([#649](#649)) ([5c67692](5c67692)) * **ssr:** improved SSR handling in Next.js ([#641](#641)) ([22e075f](22e075f)) * **vue:** remove unnecessary vue patch ([34f7ce2](34f7ce2)) ### 📝 Documentation * **internal:** link release workflow ([0e69d0e](0e69d0e)) * **internal:** update contributing guidelines ([08c96fd](08c96fd)) * chore: * Update CHANGELOG.md --------- Co-authored-by: semantic-release-bot <semantic-release-bot@martynus.net> Co-authored-by: John Jenkins <johnljenkins@Hotmail.com> Co-authored-by: John Jenkins <john.jenkins@nanoporetech.com>

christian-bromann added 8 commits May 16, 2025 12:27

fix(ssr): improved SSR handling in Next.js

7dcd98d

implement support for modes

9a31d1b

remove data-id

549d381

prettier

2ca520b

resolve variable values

d20ebad

allow components to come from other modules

033b005

use TypeScript compiler

f141854

improved property parsing

3ed9ffe

christian-bromann requested a review from a team as a code owner May 19, 2025 23:36

christian-bromann added 6 commits May 20, 2025 15:34

merge imports

fd92d8d

better import merge

b585153

dynamically detect dev compile

ae75221

Merge branch 'main' into cb/ssr-improvements

26c626b

more progress

a3e05cc

prettier

7340fd0

christian-bromann commented May 22, 2025

View reviewed changes

example-project/next-15-react-19-app/test/test.e2e.ts Show resolved Hide resolved

example-project/react-app/tests/test.e2e.ts Outdated Show resolved Hide resolved

christian-bromann added 10 commits May 22, 2025 16:52

fix Vue and Nuxt build

fb3b217

fix Vue and Nuxt build also for Windows

04a2ce2

better parent detection check

9905985

enable style propagation

1443291

update tests

a9a9336

resolve vue issues

49ce40b

prettier

9db14a5

update stencil core

bcf4d3b

update components.d.ts

7746989

uncomment tests

5dbaba9

christian-bromann merged commit 22e075f into main May 28, 2025
2 of 3 checks passed

christian-bromann deleted the cb/ssr-improvements branch May 28, 2025 22:01

HenningWaack mentioned this pull request Jul 7, 2025

bug: vue-output-target breaks hydrated classes #686

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(ssr): improved SSR handling in Next.js#641

fix(ssr): improved SSR handling in Next.js#641
christian-bromann merged 24 commits intomainfrom
cb/ssr-improvements

christian-bromann commented May 19, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

christian-bromann commented May 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

christian-bromann commented May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request checklist

Variable Support

Transform Components from other sources

Support for Spread Properties

Support for Non-Dev Environments

Reduction of Hydration Errors in Next.js

Pull request type

Does this introduce a breaking change?

Other information

Uh oh!

Uh oh!

Uh oh!

christian-bromann commented May 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

christian-bromann commented May 19, 2025 •

edited

Loading