Architecture Overview

Ecopages is designed to be modular, leveraging the speed of Bun and the flexibility of multiple rendering engines. This guide provides a brief overview of how things connect under the hood.

Request Lifecycle

When a request hits your Ecopages application, it follows this simplified flow:

1. Bun.serve: Bun receives the HTTP request and passes it to the Ecopages adapter.
2. Router: The router matching logic identifies if the path corresponds to a static file, an API route, or a page file in src/pages.
3. Route Resolver: If it's a page, Ecopages determines which integration handles the file extension (e.g., KitaJS for .kita.tsx).
4. Integration Renderer: The specific renderer (React, Lit, etc.) is invoked with the page component and props.
5. Template Composition: The page content is wrapped in the specified HtmlTemplate, Head, and Seo includes.
6. Response: The final HTML (or JSON for APIs) is sent back to the client.

Core Modules

For those wishing to dive deeper, we recommend exploring the source code:

• EcopagesApp: The main entry point and orchestrator.
• BunServerAdapter: Handles the low-level Bun server interface.
• IntegrationPlugin: The base class for all templating integrations.
• ConfigBuilder: Validates and constructs your application state.

Design Philosophy

• Minimal Configuration: Sensible defaults for structure and asset loading, with a simple config file to override them.
• Explicit Dependencies: Components declare their own scripts and styles, preventing global bloat.
• Hybrid by Choice: Optimization for static builds while maintaining full server capabilities.