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:

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

rootDir*string

setRootDir@default: .

The root directory of your project, used to resolve paths to your project files.

baseUrl*string

setBaseUrl

The base URL of your project, used for generating absolute URLs for your pages.

defaultMetadataPageMetadataProps

setDefaultMetadata@default: { title: 'Ecopages', description: 'This is a static site generated with Ecopages' }

Default metadata for your pages. This is merged with page-specific metadata when provided.

srcDirstring

setSrcDir@default: src

The directory containing your source files, relative to the root project directory.

publicDirstring

setPublicDir@default: public

The directory for static assets, relative to the src directory.

pagesDirstring

setPagesDir@default: pages

The directory containing your page files, relative to the src directory.

includesDirstring

setIncludesDir@default: includes

The directory for include templates, relative to the src directory.

layoutsDirstring

setLayoutsDir@default: layouts

The directory for layout components, relative to the src directory.

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.

distDirstring

setDistDir@default: dist

The output directory for the built files.

workDirstring

setWorkDir@default: .eco

The internal workspace used for development and runtime-only artifacts. This directory is not intended for deployment.

componentsDirstring

setComponentsDir@default: components

The directory containing your reusable components.

additionalWatchPathsstring[]

setAdditionalWatchPaths@default: []

Add additional files to monitor for changes. This is useful for tracking files that are not included in the Ecopages build process.

robotsTxt{ preferences: RobotsPreference }

setRobotsTxt@default: { preferences: { "*": [] } }

Configuration for the robots.txt file.

sitemapSitemapConfig

setSitemap@default: { enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }

Automatic sitemap.xml generation during static export. Disabled by default. See Sitemap for eligibility rules, exclude patterns, and extraUrls.

integrationsIntegrationPlugin[]

setIntegrations@default: []

An array of integration plugins to enhance Ecopages functionality.

processorsProcessor[]

setProcessors@default: []

An array of processors to handle file transformations (e.g., PostCSS, Images).

loadersEcoBuildPlugin[]

setLoaders@default: []

An array of build plugins to use as loaders for custom file types.

sourceTransformsEcoSourceTransform[]

setSourceTransforms@default: []

Filter-based module source rewrites for browser and HMR builds. See Source Transforms.

devToolbarDevToolbarConfig

setDevToolbar

Development-only in-browser inspector. Install @ecopages/dev-toolbar and call setDevToolbar(devToolbar()). See Dev toolbar.

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:

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:

Getting Started

Core Concepts

Server

Integrations

Ecosystem

Extending

Reference

Configuration

Configuration API

Integrations