Installation

To create a new Ecopages project, install the core package plus the rendering integration you want to start with. The example below uses Ecopages JSX for standard .tsx routes.

This example installs the default stack: the core package plus Ecopages JSX and its peer runtimes. Register React, Lit, standalone MDX, or KitaJS when those Integrations should own routes.

Configuration

After installation, create an eco.config.ts file in your project's root directory to configure Ecopages. This file defines your site's structure, integrations, and canonical base URL.

// filepath: eco.config.ts
import { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
 
export default defineConfig({
	rootDir: import.meta.dirname,
	baseUrl: 'https://your-production-domain.com',
	integrations: [ecopagesJsxPlugin()],
});Copy

Environment Variables

Ecopages uses environment variables for configuration overrides. Create a .env file in your project root (and add it to .gitignore).

# filepath: .env.example
# Overrides the baseUrl set in eco.config.ts (e.g., for different deployment stages)
ECOPAGES_BASE_URL=https://staging.your-production-domain.com
 
# Overrides the hostname the server listens on (Default: localhost)
ECOPAGES_HOSTNAME=0.0.0.0
 
# Overrides the port the server listens on (Default: 3000)
ECOPAGES_PORT=8080
 
# Enable debug logging (Default: false)
ECOPAGES_LOGGER_DEBUG=trueCopy

Configuration Precedence:

• Server Hostname/Port: Constructor serverOptions > Environment Variables (ECOPAGES_HOSTNAME, ECOPAGES_PORT) > Defaults (localhost:3000).
• Canonical Base URL: eco.config.ts (setBaseUrl) > Environment Variable (ECOPAGES_BASE_URL) > Default (http://localhost:3000).

Project Structure

A typical Ecopages project structure looks like this:

my-project/
├── src/
│ ├── pages/
│ ├── layouts/
│ ├── components/
│ └── includes/
├── public/
├── app.ts # Your application entry point
├── eco.config.ts # Ecopages configuration
├── package.json
└── .env # Environment variables (optional)

• src/pages/: Contains your page files (e.g., .tsx, .mdx, .kita.tsx, .lit.tsx)
• src/layouts/: Holds layout components
• src/components/: Stores reusable components
• src/includes/: Contains include templates (e.g., head.tsx, html.tsx or integration-specific suffixes)
• public/: Static assets that will be copied to the build directory
• app.ts: The main script to run Ecopages commands.
• eco.config.ts: Ecopages configuration file.

Usage

Create an entry point file (e.g., app.ts) to initialize and run Ecopages:

// filepath: app.ts
import { createApp } from '@ecopages/core/create-app';
 
const app = await createApp();
await app.start();Copy

Add the following scripts to your package.json:

{
	"scripts": {
		"build": "ecopages build",
		"dev": "ecopages dev",
		"preview": "ecopages preview",
		"start": "ecopages start",
		"watch:dev": "ecopages dev:watch"
	}
}Copy

Now you can use these commands:

• pnpm run dev (or bun run dev): Starts the development server. You can override the host, port, base URL, and runtime with CLI flags or environment variables.
• pnpm run build (or bun run build): Builds your project for production into the dist directory.
• pnpm run start (or bun run start): Starts the production server from the existing dist build output.
• pnpm run preview (or bun run preview): Rebuilds dist and then serves that production output locally for verification.

Next Steps

With Ecopages installed and configured, you're ready to start building your site. Check out the Pages guide to learn how to create content using different integrations.