KitaJS Integration

The @ecopages/kitajs package integrates KitaJS HTML so Ecopages can own .kita.tsx Pages.

Installation

Install the integration package:

Also install Kita's required peer packages in your app: @kitajs/html and @kitajs/ts-html-plugin.

Usage

Register the kitajsPlugin in your Ecopages configuration:

import { ConfigBuilder } from '@ecopages/core/config-builder';
import { kitajsPlugin } from '@ecopages/kitajs';
 
const appRoot = process.cwd();
 
const config = await new ConfigBuilder()
	.setRootDir(appRoot)
	.setBaseUrl(process.env.ECOPAGES_BASE_URL ?? 'http://localhost:3000')
	.setIntegrations([kitajsPlugin()])
	.build();
 
export default config;Copy

By default, KitaJS owns .kita.tsx route files and renders them through @kitajs/html.

Creating Pages with KitaJS

Create routes with a .kita.tsx suffix so the Kita integration can claim them. For example, src/pages/index.kita.tsx:

import { BaseLayout } from '@/layouts/base-layout';
import { eco } from '@ecopages/core';
 
export default eco.page({
	layout: BaseLayout,
	render: () => (
		<>
			<h1>Welcome to Ecopages</h1>
		</>
	),
});Copy

Key Features

• HTML-first JSX: Kita renders JSX to HTML strings through @kitajs/html.
• Owned route suffixes: Kita owns .kita.tsx routes rather than generic .tsx files.
• Outer-shell friendly: Kita works well as the HTML-first shell in mixed-renderer apps.
• Dependency-driven rendering: Declare nested component dependencies so Ecopages can preserve renderer ownership correctly.

Interactive Kita components with client scripts stamp island host attributes on their SSR root.

Best Practices

1. Layouts: Create layout components (like BaseLayout in the example) to maintain consistent page structures.
2. Route naming: Use .kita.tsx for Kita-owned route files.
3. Dependency declarations: In mixed-integration apps, foreign children must appear in the dependency graph. Direct local imports are discovered automatically; use explicit dependencies.components for export * barrels, packages, or other imports discovery cannot follow.
4. Cross-integration shells: Use EcoEmbed from @ecopages/kitajs/eco-embed when a Kita page nests foreign-integration shells or passes children across integration boundaries. Plain opaque objects fail fast at core foreign-subtree queue boundaries — use EcoEmbed or already-serialized HTML instead. See Ecopages JSX — Mixed Rendering.

Integration with Other Plugins

KitaJS works well with other Ecopages plugins. For example, you can pair it with the standalone MDX integration when MDX should compile against the same non-React JSX runtime:

import { ConfigBuilder } from '@ecopages/core/config-builder';
import { kitajsPlugin } from '@ecopages/kitajs';
import { mdxPlugin } from '@ecopages/mdx';
 
const appRoot = process.cwd();
 
const config = await new ConfigBuilder()
	.setRootDir(appRoot)
	.setBaseUrl(process.env.ECOPAGES_BASE_URL ?? 'http://localhost:3000')
	.setIntegrations([
		kitajsPlugin(),
		mdxPlugin({
			compilerOptions: {
				jsxImportSource: '@kitajs/html',
			},
		}),
	])
	.build();
 
export default config;Copy

This setup allows both KitaJS and MDX in the same project, giving flexibility in how pages and components are authored. Pair standalone mdxPlugin() with compilerOptions.jsxImportSource: '@kitajs/html' when MDX should compile against the KitaJS runtime.