Ecopages0.6.1

Getting Started

Core Concepts

Server

Integrations

Ecosystem

Extending

Reference

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>.

When one process needs to create more than one app from the same config module, export a factory so each app gets fresh plugin instances:

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

An object config containing integrations, processors, or loaders can create one app. Loading it again for another app throws because those plugin instances carry app state.

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. If the restarted dev server exits with an error, for example because of an invalid eco.config.ts, ecopages dev waits for the next change in the project or a linked workspace package and starts again. Page and component files still hot-reload without a full restart.

Configuration API

rootDirstring
@default: process.cwd()

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

baseUrlstring
@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
@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
@default: src

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

publicDirstring
@default: public

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

pagesDirstring
@default: pages

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

includesDirstring
@default: includes

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

layoutsDirstring
@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 template 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.

eco.config.ts has no field for these filenames. 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
@default: dist

The build output directory. Public files go into its client/ subdirectory and private server output goes into server/. ecopages start does not read this option: it runs the only <dir>/server/manifest.json one level below the app root. Use ecopages start --dist-dir <dir> when there are several outputs (such as dist-<scope> per build target) or the output is nested (out/web) or a symlink.

workDirstring
@default: .eco

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

componentsDirstring
@default: components

The directory containing your reusable components.

additionalWatchPathsstring[]
@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. An entry containing * is a glob pattern, such as content/**/*.md or **/*.config.ts; any other entry is a plain path, even with brackets. Globs are anchored at the project root: *.css matches only top-level files, and **/*.css matches at any depth. Ecopages watches the folder before the first wildcard (content, or the project root for a pattern starting with **) and reacts only to files that match. * and ** do not match names starting with a dot unless the pattern spells the dot, as in .github/**/*.yml. To match a literal bracket in a glob, write [[], as in src/pages/[[]slug]/*.md. A matching change invalidates server modules, notifies processors, and reloads the browser.

serverFilesstring[]

Globs, relative to the project root, of files copied into dist/server/ at build so production code can read them next to import.meta. Two matches that share a basename fail the build. Prefer public/ for static files the browser should fetch.

robotsTxt{ preferences: RobotsPreference }
@default: { preferences: { "*": [] } }

Configuration for the robots.txt file.

sitemapSitemapConfig
@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[]
@default: []

An array of integration plugins to enhance Ecopages functionality.

processorsProcessor[]
@default: []

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

loadersEcoBuildPlugin[]
@default: []

An array of build plugins to use as loaders for custom file types. A plugin can also rewrite module source with its transform hook; there is no separate source-transform config option. See Source Transforms.

cacheCacheConfig

Page cache settings: store (default 'memory'), defaultStrategy for Pages that set none (default 'static'), enabled (on in production builds, off in watch mode unless set), and maxEntries for the memory store (default 1000). See Caching.

devPrewarmPathsstring[]
@default: []

Routes such as / or /docs to render in the background when the development server starts, so the first visit is fast.

devToolbarDevToolbarConfig

Development-only in-browser inspector. Install @ecopages/dev-toolbar and set devToolbar: 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: