Ecopages0.2.0-rc.4

Getting Started

Core Concepts

Server

Integrations

Ecosystem

Extending

Reference

Includes in Ecopages

Includes are special templates that define the structure of your pages. They help maintain consistency across your site and allow you to configure common elements like the HTML head and SEO meta tags.

Basic Structure

By default, Ecopages looks for three main include files:

  1. html.{ext}: The root HTML template
  2. head.{ext}: The HTML head section
  3. seo.{ext}: SEO-related meta tags

The extension depends on your chosen integration (e.g. .tsx for Ecopages JSX, .kita.tsx, .lit.tsx).

Configuration

You can configure includes in your eco.config.ts:

import { ConfigBuilder } from '@ecopages/core/config-builder';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
 
const config = await new ConfigBuilder()
	.setIntegrations([ecopagesJsxPlugin()])
	.build();

Ecopages resolves src/includes/html.* automatically using the registered integration extensions.

Include Templates

HTML Template

The HTML template defines the overall structure of your pages. Use eco.html() to clearly signal that this component owns the full document shell:

import { eco } from '@ecopages/core';
import type { HtmlTemplateProps } from '@ecopages/core';
import type { JsxRenderable } from '@ecopages/jsx';
 
const Html = eco.html<HtmlTemplateProps<JsxRenderable>, JsxRenderable>({
	dependencies: {
		stylesheets: ['./html.css'],
	},
	render: ({ children, language = 'en' }) => <html lang={language}>{children}</html>,
});
 
export default Html;

Head Template

The head template manages your document's head section:

import { eco, type PageHeadProps } from '@ecopages/core';
import type { JsxRenderable } from '@ecopages/jsx';
 
const Head = eco.component<PageHeadProps<JsxRenderable>, JsxRenderable>({
	render: ({ metadata, children }) => (
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>{metadata.title}</title>
		{children}
	</head>
	)
});
 
export default Head;

SEO Template

The SEO template handles meta tags for search engines and social sharing:

import { eco, type PageMetadataProps } from '@ecopages/core';
import type { JsxRenderable } from '@ecopages/jsx';
 
const Seo = eco.component<PageMetadataProps, JsxRenderable>({
	render: ({ title, description, image, keywords }) => <>
		<meta name="description" content={description} />
		<meta name="keywords" content={keywords?.join(',')} />
		<meta property="og:title" content={title} />
		<meta property="og:description" content={description} />
		{image ? <meta property="og:image" content={image} /> : null}
	</>
});
 
export default Seo;

Best Practices

  1. Keep Templates Simple: Include templates should focus on structure and essential metadata
  2. Use TypeScript: Define proper interfaces for your template props
  3. Maintain Consistency: Use the same extension for all includes
  4. Configure Properly: Always set up includes in your config file
  5. Handle Dependencies: If your includes need scripts or styles, declare them in the config