Ecopages0.10.0

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). The HTML template can also be plain HTML, src/includes/html.html; see Plain HTML template. An app has one html template file: html.tsx and html.html together are an error.

Configuration

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

import { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';

export default defineConfig({
	integrations: [ecopagesJsxPlugin()],
});

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 { JsxRenderable } from '@ecopages/jsx';

const Html = eco.html<JsxRenderable>({
	dependencies: {
		stylesheets: ['./html.css'],
	},
	render: ({ children, language = 'en' }) => <html lang={language}>{children}</html>,
});

export default Html;

Plain HTML template

src/includes/html.html is the HTML template written in plain HTML. It needs an <html> element with <head> and <body>, and exactly one <!-- eco:children --> comment where page content goes:

<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>My site</title>
		<link rel="stylesheet" href="./site.css">
	</head>
	<body>
		<!-- eco:children -->
	</body>
</html>

Relative stylesheets and scripts resolve against the template file and are processed the same way as in an HTML Page. Ecopages always emits one doctype, so the template does not need one.

The template has no props, so it cannot render metadata. For HTML Pages that is fine: its title and description are fallbacks that each page's own head tags replace. For pages from other integrations, its <title> and description stay as written (core still adds their stylesheets, scripts, and robots tag), so if your app also has eco.page() Pages that set metadata, use a JSX or React html.* template instead.

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({
	render: ({ metadata, children }: PageHeadProps<JsxRenderable>) => (
	<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';

const Seo = eco.component({
	render: ({ title, description, image, keywords }: PageMetadataProps) => <>
		<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