Installation

To create a new Ecopages project, you can install the core package and desired integrations using Bun:

bun jsr add @ecopages/core @ecopages/kitajs @ecopages/mdx

This example installs the core package along with the KitaJS and MDX integrations. You can add or remove integrations based on your project needs.

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 { ConfigBuilder } from '@ecopages/core';
import { kitajsPlugin } from '@ecopages/kitajs';
import { mdxPlugin } from '@ecopages/mdx';

const config = await new ConfigBuilder()
  .setRootDir(import.meta.dir)
  // Optional: Set the canonical base URL for your site.
  // Used for generating absolute URLs in production builds.
  // If omitted, it defaults to http://localhost:3000 during development.
  // Can be overridden by the ECOPAGES_BASE_URL environment variable.
  .setBaseUrl('https://your-production-domain.com') 
  .setIntegrations([kitajsPlugin(), mdxPlugin()])
  .build();

export default config;

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=true 

Configuration Precedence:

• Server Hostname/Port: Command Line Flags (--hostname, --port) > Environment Variables (ECOPAGES_HOSTNAME, ECOPAGES_PORT) > Defaults (localhost:3000).
• Canonical Base URL: Environment Variable (ECOPAGES_BASE_URL) > eco.config.ts (setBaseUrl) > 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., .mdx, .kita.tsx, .lit.tsx)
• src/layouts/: Holds layout components
• src/components/: Stores reusable components
• src/includes/: Contains include templates (e.g., head.kita.tsx, html.kita.tsx)
• 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 { EcopagesApp } from '@ecopages/core';
import config from './eco.config.ts';

await new EcopagesApp(config).run(); 

Add the following scripts to your package.json:

{
  "scripts": {
    "dev": "bun run app.ts --dev",
    "build": "bun run app.ts --build",
    "start": "bun run app.ts --start",
    "preview": "bun run app.ts --preview",
    "watch:dev": "bun --watch run app.ts --dev" 
  }
}

Now you can use these commands:

• bun run dev: Starts the development server (with HMR). You can override the host/port with flags (bun run dev --port 4000) or environment variables.
• bun run build: Builds your project for production into the dist directory. Uses the configured baseUrl.
• bun run start: Serves the production build from the dist directory. Uses the configured baseUrl.
• bun run preview: Builds and serves the production build locally for previewing.

Next Steps

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