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

Answer

For SSR with hydration, import components from the dist-custom-elements output target. This avoids dynamic lazy‑chunk loading and works reliably when the SSR framework rewrites static asset URLs. Using the dist target with the hydrate script is only safe if you can guarantee the loader’s asset path matches the public path used by the SSR host; otherwise lazy chunks may 404 and hydration will fail.

Steps to set up dist-custom-elements

1. In stencil.config.ts keep only the dist-custom-elements output target (or add it alongside dist if you need other builds).
2. Publish the package; consumers import components directly, e.g.:

   import { MyComponent } from 'my-lib/dist-custom-elements/my-component.js';

3. No special loader configuration is required because the modules are eagerly imported.

If you must use dist with the hydrate script

1. Set the loader’s base URL to match the SSR host’s public asset path. In Stencil config:

   outputTargets: [
     { type: 'dist', baseUrl: '/_next/static/' },
     { type: 'dist-hydrate-script' }
   ]

   (adjust the path to whatever your SSR framework uses, e.g., /assets/ for Vite SSR).
2. Ensure the SSR middleware serves the generated dist folder at that public path.
3. Before loading the lazy loader, you can optionally override window.__STENCIL_LOADER__ with the correct prefix if the framework rewrites URLs after the script loads.

Preventing duplicate custom element registration

• Guard each definition: if (!customElements.get('my-tag')) { customElements.define('my-tag', MyComponent); }
• Or, when using both eager and lazy builds, list the components that should stay lazy in excludeComponents of the dist-custom-elements target so they are not defined twice.

Confirmed facts (based on Stencil v4.x changelog)

• The dist-custom-elements target was introduced to provide eagerly importable, tree‑shakable modules and is the recommended target for SSR when you want to avoid dynamic imports.
• The dist target relies on runtime lazy chunks; if the asset path does not match the host’s public path, those chunks 404 and hydration never occurs.
• Duplicate customElements.define calls throw a DOMException and break hydration.

Missing diagnostic detail that could change the recommendation: Does your SSR framework rewrite static asset URLs (e.g., via assetPrefix in Next.js or similar)? If yes, you must configure baseUrl or override window.__STENCIL_LOADER__ when using the dist target; otherwise the default dist-custom-elements approach works without extra configuration.