---
title: 'Configuration'
description: 'Customize your Ecopages project through eco.config.ts — integrations, processors, metadata, and watch paths.'
order: 3
---

import { ApiField } from '@/components/api-field/api-field';

# Configuration

Ecopages can be customized to fit your project's needs through a configuration file. Create a file named `eco.config.ts` in your project's root directory to get started.

Here's a basic example of an Ecopages configuration:

```typescript
import { ConfigBuilder } from '@ecopages/core/config-builder';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';

const appRoot = process.cwd();

const config = await new ConfigBuilder()
	.setRootDir(appRoot)
	.setBaseUrl(process.env.ECOPAGES_BASE_URL ?? 'http://localhost:3000')
	.setIntegrations([ecopagesJsxPlugin()])
	.setDefaultMetadata({
		title: 'Your Site Title',
		description: 'Your site description',
		image: 'https://your-domain.com/og-image.png',
	})
	.build();

export default config;
```

## Configuration API

<ApiField name="rootDir" mandatory defaultValue="." type="string" setter="setRootDir">
	The root directory of your project, used to resolve paths to your project files.
</ApiField>

<ApiField name="baseUrl" mandatory type="string" setter="setBaseUrl">
	The base URL of your project, used for generating absolute URLs for your pages.
</ApiField>

<ApiField
	name="defaultMetadata"
	type="PageMetadataProps"
	defaultValue="{ title: 'Ecopages', description: 'This is a static site generated with Ecopages' }"
	setter="setDefaultMetadata"
>
	Default metadata for your pages. This is merged with page-specific metadata when provided.
</ApiField>

<ApiField name="srcDir" type="string" defaultValue="src" setter="setSrcDir">
	The directory containing your source files, relative to the root project directory.
</ApiField>

<ApiField name="publicDir" type="string" defaultValue="public" setter="setPublicDir">
	The directory for static assets, relative to the src directory.
</ApiField>

<ApiField name="pagesDir" type="string" defaultValue="pages" setter="setPagesDir">
	The directory containing your page files, relative to the src directory.
</ApiField>

<ApiField name="includesDir" type="string" defaultValue="includes" setter="setIncludesDir">
	The directory for include templates, relative to the src directory.
</ApiField>

<ApiField name="layoutsDir" type="string" defaultValue="layouts" setter="setLayoutsDir">
	The directory for layout components, relative to the src directory.
</ApiField>

Ecopages now discovers the document shell and error pages semantically:

- `src/includes/html.*` resolves the HTML shell by basename and integration extension.
- `src/pages/404.*` resolves the not-found page by basename and integration extension.
- `src/pages/500.*` resolves the server-error page by basename and integration extension.

No template filename setter is required in `eco.config.ts`. If `500.*` is missing or fails while rendering, the page pipeline falls back to plain-text `Internal Server Error`. In development, the custom 500 page receives `message` and `stack` props from the thrown error.

<ApiField name="distDir" type="string" defaultValue="dist" setter="setDistDir">
	The output directory for the built files.
</ApiField>

<ApiField name="workDir" type="string" defaultValue=".eco" setter="setWorkDir">
	The internal workspace used for development and runtime-only artifacts. This directory is not intended for
	deployment.
</ApiField>

<ApiField name="componentsDir" type="string" defaultValue="components" setter="setComponentsDir">
	The directory containing your reusable components.
</ApiField>

<ApiField name="additionalWatchPaths" type="string[]" defaultValue="[]" setter="setAdditionalWatchPaths">
	Add additional files to monitor for changes. This is useful for tracking files that are not included in the Ecopages
	build process.
</ApiField>

<ApiField
	name="robotsTxt"
	type="{ preferences: RobotsPreference }"
	defaultValue={`{ preferences: { "*": [] } }`}
	setter="setRobotsTxt"
>
	Configuration for the robots.txt file.
</ApiField>

<ApiField
	name="sitemap"
	type="SitemapConfig"
	defaultValue="{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }"
	setter="setSitemap"
>
	Automatic <code>sitemap.xml</code> generation during static export. Disabled by default. See{' '}
	<a href="/docs/core/sitemap">Sitemap</a> for eligibility rules, <code>exclude</code> patterns, and{' '}
	<code>extraUrls</code>.
</ApiField>

<ApiField name="integrations" type="IntegrationPlugin[]" defaultValue="[]" setter="setIntegrations">
	An array of integration plugins to enhance Ecopages functionality.
</ApiField>

<ApiField name="processors" type="Processor[]" defaultValue="[]" setter="setProcessors">
	An array of processors to handle file transformations (e.g., PostCSS, Images).
</ApiField>

<ApiField name="loaders" type="EcoBuildPlugin[]" defaultValue="[]" setter="setLoaders">
	An array of build plugins to use as loaders for custom file types.
</ApiField>

<ApiField name="sourceTransforms" type="EcoSourceTransform[]" defaultValue="[]" setter="setSourceTransforms">
	Filter-based module source rewrites for browser and HMR builds. See [Source
	Transforms](/docs/plugins/source-transforms).
</ApiField>

<ApiField name="devToolbar" type="DevToolbarConfig" setter="setDevToolbar">
	Development-only in-browser inspector. Install `@ecopages/dev-toolbar` and call `setDevToolbar(devToolbar())`. See
	[Dev toolbar](/docs/core/dev-toolbar).
</ApiField>

## Integrations

Ecopages supports various integrations to extend its capabilities. Here are some commonly used integrations:

- **Ecopages JSX**: Default stack for `.tsx` Pages and optional Radiant hydration
- **React**: React Pages or component islands
- **Lit**: Web Components
- **MDX**: Standalone Markdown on a non-React JSX runtime
- **KitaJS**: `.kita.tsx` Pages via `@kitajs/html`

To use an integration, install it and add it to your configuration. For example:

```typescript
import { ConfigBuilder } from '@ecopages/core/config-builder';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';

const appRoot = process.cwd();

const config = await new ConfigBuilder()
	.setRootDir(appRoot)
	.setBaseUrl(process.env.ECOPAGES_BASE_URL ?? 'http://localhost:3000')
	.setIntegrations([ecopagesJsxPlugin()])
	.build();

export default config;
```

For more details on specific integrations, refer to their respective documentation pages:

- [Ecopages JSX Integration](/docs/integrations/ecopages-jsx)
- [KitaJS Integration](/docs/integrations/kitajs)
- [Lit Integration](/docs/integrations/lit)
- [MDX Integration](/docs/integrations/mdx)
- [React Integration](/docs/integrations/react)