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 { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
 
export default defineConfig({
	integrations: [ecopagesJsxPlugin()],
	defaultMetadata: {
		title: 'Your Site Title',
		description: 'Your site description',
		image: 'https://your-domain.com/og-image.png',
	},
});

createApp() loads and finalizes this file automatically. Override the path with createApp({ configFile }), ECOPAGES_CONFIG_FILE, or ecopages dev --config <file>.

In development, adding, changing, or removing eco.config.ts or a supported project .env file restarts the dev server so integrations, directories, and environment values reload. Supported files are .env, .env.local, .env.[NODE_ENV], and .env.[NODE_ENV].local. Page and component files still hot-reload without a full restart.

Configuration API

rootDirstring

setRootDir@default: process.cwd()

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

baseUrlstring

setBaseUrl@default: http://localhost:3000

The base URL of your project, used for generating absolute URLs for your pages. ECOPAGES_BASE_URL overrides the default when baseUrl is omitted.

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 no pages/500.* file or app.serverError() loader is configured, the page pipeline serves a built-in HTML 500 page. In development, custom and default 500 pages can show message and stack from the thrown error; the built-in page also includes a Copy error button.

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 or directories to monitor during development. Paths are resolved from the project root, so src/registry watches every file inside that folder. Glob patterns such as **/*.config.ts are also supported. A matching change invalidates server modules, notifies processors, and reloads the browser.

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 { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
 
export default defineConfig({
	rootDir: import.meta.dirname,
	baseUrl: process.env.ECOPAGES_BASE_URL ?? 'http://localhost:3000',
	integrations: [ecopagesJsxPlugin()],
});

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