Welcome to Ecopages

bunx degit ecopages/ecopages/examples/starter-jsx my-ecopages

Ecopages is a modern, basic web framework built on Bun.

No virtual DOM. No complex state management. No framework-specific mental models. Just TypeScript and HTML.

What Makes Ecopages Different?

Most frameworks require you to adopt an entirely new way of thinking: hooks, signals, reactivity systems, and layers of abstraction. Ecopages takes the opposite approach. You write functions that return HTML. That's it.

The result? Fast static pages, minimal dependencies, and code you can actually understand. When you need server-side logic, add it, but you'll find that static is often exactly what you need.

Key Features

1. Plain TypeScript: No framework DSL, no compiler magic. Write standard TypeScript functions that return HTML strings. Your IDE's autocomplete just works.

2. Web Fundamentals: Embrace HTML, CSS, and browser APIs directly. No virtual DOM abstraction layer between you and the web.

3. Static by Default: Generate HTML at build time. Host anywhere. No server costs for most sites.

4. Lightweight, Safe Backend:

   • Typed Handlers: Define API handlers with full type inference using defineHandlers.
   • Explicit Routing: Use app.get(), app.post(), etc. for granular control over your API endpoints.
   • Zero Overhead: The server module is tree-shaken away when you only build static pages.

5. AI-Ready Documentation:

   • Includes llms.txt to help AI agents understand your project structure and docs.
   • Designed with clear patterns that are easy for LLMs to generate and debug.

6. Choose Your Templating:

   • KitaJS – Fast JSX templates, compiles to string concatenation
   • React 19 – Full React with hydration when you need it
   • Lit – Web Components with SSR
   • MDX – Markdown with embedded components

7. TypeScript-First: Full type inference for routes, props, and API handlers. No runtime overhead.

8. Built on Bun: Leverages Bun's speed for fast builds, fast development, and fast production servers.

What Can You Build?

• Marketing sites – Static pages with excellent SEO
• Documentation – MDX-powered docs like the one you're reading
• Blogs – Dynamic routes with getStaticPaths for each post
• Portfolios – Beautiful static sites with interactive components
• Full-Stack Apps – Combine static pages with typed API handlers for dynamic features
• Dashboards – React or Lit components with live API data
• APIs – REST endpoints alongside your static pages
• Everything Else – Ecopages is flexible enough to build whatever you can imagine

Quick Example

Here's how you can combine static pages with a typed backend:

1. Create a Component

Use eco.component to create reusable components with isolated dependencies.

// src/components/Greeting.tsx
import { eco } from '@ecopages/core';
 
export const Greeting = eco.component<{ name: string }>({
  render: ({ name }) => {
    return <div class="greeting">Hello, {name}!</div>;
  },
});

2. Create a Page

Compose your page using components. Dependencies are automatically managed.

// src/pages/index.tsx
import { eco } from '@ecopages/core';
import { Greeting } from '../components/Greeting';
 
export default eco.page({
  dependencies: {
    stylesheets: ['../styles.css'],
    components: [Greeting],
  },
  metadata: () => ({
    title: 'Welcome to Ecopages',
  }),
  render: () => (
    <main>
      <h1>Welcome to Ecopages</h1>
      <Greeting name="Developer" />
    </main>
  ),
});

3. Add Typed API Handlers

You can define handlers inline or use defineApiHandler for better organization and type safety.

Inline Handler

Good for simple, quick endpoints.

// app.ts
import { EcopagesApp } from '@ecopages/core/adapters/bun/create-app';
import config from './eco.config';
 
const app = new EcopagesApp({ appConfig: config });
 
app.get('/api/hello', async (ctx) => {
  return ctx.response.json({ message: 'Hello world!' });
});

Organized & Type-Safe Handlers

For larger apps, define handlers in separate files using defineApiHandler. This gives you automatic type inference for body, query, and path parameters based on your schema.

// handlers/greet.ts
import { defineApiHandler } from '@ecopages/core/adapters/bun';
import { z } from 'zod';
 
export const greetHandler = defineApiHandler({
  path: '/api/greet',
  method: 'POST',
  schema: {
    body: z.object({ name: z.string() }),
  },
  handler: async (ctx) => {
    // ctx.body is automatically typed as { name: string }
    const { name } = ctx.body;
    return ctx.response.json({ message: `Hello, ${name}!` });
  },
});

// app.ts
import { greetHandler } from './handlers/greet';
 
// ... app initialization
 
app.post(greetHandler);

AI Agents & Ecopages

Ecopages is built to be friendly to AI coding assistants.

• Explicit APIs: Less "magic", making it easier for AI to infer logic.
• Standard Types: Uses standard TypeScript and Web APIs.
• Structure: Clear file-system routing and component organization.

Refer your AI agent to our llms.txt file (found at the root of our docs site) for context.

Getting Started

Ready to try Ecopages? Check out the Installation Guide to create your first project.

bunx degit ecopages/ecopages/examples/starter-jsx my-ecopages
cd my-ecopages
bun install
bun run dev