Island Hosts
Hydratable component instances stamp a small, integration-agnostic attribute set on their SSR root. Dev tools (such as the dev toolbar Islands panel) and future runtime features use these markers to discover interactive islands without integration-specific selectors.
Attributes
| Attribute | Purpose |
|---|---|
data-eco-island | Marks the element as an interactive island host |
data-eco-island-integration | Owning integration (react, lit, kitajs, ecopages-jsx, …) |
data-eco-component-id | Stable instance id from the render pipeline |
data-eco-component-key | Optional module key used by client hydration (React) |
data-eco-props | Optional props snapshot for hydration: base64 of UTF-8 JSON |
React may replace the SSR host with <eco-island> after hydration. The marker is applied at SSR time on the component root.
When stamping happens
Core applies island host metadata through finalizeIslandComponentRender() when all of the following are true:
integrationContext.componentInstanceIdis present- The render result can attach attributes to a single root element (
canAttachAttributes) - The component itself ships at least one client
script
Scripts of Foreign Children, components of another integration nested inside it, do not count. A Lit component without scripts that wraps a React island is not stamped as an island host.
Island client modules come from the page client plan: every component whose integration differs from its parent's, except the Html shell. A component is an island if any of its parents belongs to another integration, and it is listed once.
Integrations that extend the contract (for example React's component key and props snapshot) should build on buildIslandHostAttributes() from @ecopages/core rather than inventing per-demo selectors.
Integration coverage
| Integration | Stamping |
|---|---|
| React | buildIslandHostAttributes() in component SSR |
| Lit | finalizeIslandComponentRender() in the Lit renderer |
| KitaJS, MDX, string-markup | finalizeIslandComponentRender() via the string-markup renderer path |
| Ecopages JSX | finalizeIslandComponentRender() in the Ecopages JSX renderer |
Using the helpers in custom integrations
If you author a custom integration plugin, call finalizeIslandComponentRender() on component render results. Pass the component's own assets as the third argument, excluding those of Foreign Children, so scripts from nested islands of other integrations do not mark the component as an island:
import { finalizeIslandComponentRender } from '@ecopages/core';
return finalizeIslandComponentRender(input, {
html,
canAttachAttributes: true,
integrationName: 'my-integration',
}, ownAssets);For integrations that need extra hydration metadata, use buildIslandHostAttributes() and merge the result into rootAttributes before the foreign-subtree layer applies them to the first element.
Related
- Components —
eco.component, dependencies, and client scripts - Integrations overview — choosing and mixing renderers