Choosing Between dist and dist-custom-elements Output Targets for SSR Framework Integration

Goal

Publish a Stencil component library that will be consumed inside a server-side rendering framework, where components must render on the server and hydrate on the client without duplicate custom element registration.

Constraints and uncertainty

The default dist output target code-splits each component into its own lazy-loaded chunk, loaded on demand when the component first appears in the DOM. The dist-custom-elements target instead emits each component as a standalone, eagerly importable module that a bundler can tree-shake directly. The dist-hydrate-script target exists for server prerendering, but it serializes state into markup and expects the client runtime to reconcile it.

It is unclear which pairing is correct for an SSR host: lazy loading depends on dynamic imports served from a predictable asset path, which conflicts with some SSR bundling pipelines, while eager custom elements can double-register if the host framework also ships its own definitions. Documentation does not appear to give a single decision rule, and output target behavior has changed across Stencil major versions, so assume a recent v4.x install and verify against its changelog.

Questions

• For SSR with hydration, should consumers import from dist with the hydrate script, or from dist-custom-elements, and what breaks with the wrong choice?
• How should the loader's asset path be configured so lazy chunks resolve correctly when the SSR framework rewrites static asset URLs?
• What is the supported way to prevent duplicate custom element registration if the host app bundles some components eagerly while others lazy-load?