@ecopages/react

Ecopages React Integration Plugin

The @ecopages/react package introduces first-class integration with React version 19, enabling developers to leverage React's robust ecosystem and component model within the Ecopages platform. This integration provides a seamless experience for using React components in your Ecopages projects, combining React's declarative UI library with the flexibility and simplicity of Ecopages.

Install

bunx jsr add @ecopages/react

Usage

To incorporate the React integration into your Ecopages project, configure your project as follows:

import { ConfigBuilder } from '@ecopages/core';
import { reactPlugin } from '@ecopages/react';

const config = await new ConfigBuilder()
	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
	.setIntegrations([reactPlugin()])
	.build();

export default config;

MDX Support

The React plugin includes optional MDX support. When enabled, you can write .mdx pages alongside .tsx pages with unified client-side routing, hydration, and HMR.

import { ConfigBuilder } from '@ecopages/core';
import { reactPlugin } from '@ecopages/react';

const config = await new ConfigBuilder()
	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
	.setIntegrations([
		reactPlugin({
			mdx: {
				enabled: true,
				compilerOptions: {
					// Optional: remark/rehype plugins
				},
			},
		}),
	])
	.build();

export default config;

This approach is recommended when using a client-side router (e.g., @ecopages/react-router) as it ensures consistent navigation between TSX and MDX pages.

Component-Level Islands

Current behavior:

• SSR output keeps the authored component DOM structure (no synthetic wrapper element).
• A stable data-eco-component-id attribute is attached to the component SSR root when a single root element is available.
• Client bootstrap resolves the component export and mounts with createRoot() into that root boundary.
• Component assets are emitted through the shared dependency pipeline and deduplicated with other integrations.

This design preserves global CSS/layout selectors while keeping runtime ownership isolated per island instance.

For full React pages with client-side navigation, prefer @ecopages/react-router, where routing and hydration are handled by the React-specific runtime.