Ecopages0.2.0-rc.1

Getting Started

Core Concepts

Server

Integrations

Ecosystem

Extending

Reference

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

AttributePurpose
data-eco-islandMarks the element as an interactive island host
data-eco-island-integrationOwning integration (react, lit, kitajs, ecopages-jsx, …)
data-eco-component-idStable instance id from the render pipeline
data-eco-component-keyOptional module key used by client hydration (React)
data-eco-propsOptional base64 JSON props snapshot for hydration

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:

  1. integrationContext.componentInstanceId is present
  2. The render result can attach attributes to a single root element (canAttachAttributes)
  3. The render emits at least one client script asset

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

IntegrationStamping
ReactbuildIslandHostAttributes() in component SSR
LitfinalizeIslandComponentRender() in the Lit renderer
KitaJS, MDX, string-markupfinalizeIslandComponentRender() via the string-markup renderer path
Ecopages JSXfinalizeIslandComponentRender() in the Ecopages JSX renderer

Using the helpers in custom integrations

If you author a custom integration plugin, call finalizeIslandComponentRender() on component render results that ship client scripts:

import { finalizeIslandComponentRender } from '@ecopages/core';
 
return finalizeIslandComponentRender(input, {
	html,
	canAttachAttributes: true,
	rootTag: 'section',
	integrationName: 'my-integration',
	assets,
});

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