---
title: "Includes"
description: "Define shared head and shell templates that structure every rendered page."
order: 10
---

# 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`:

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

export default defineConfig({
	rootDir: import.meta.dirname,
	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:

```tsx
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:

```tsx
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:

```typescript
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