v 0.1.41

Understanding Ecopages Core

Before diving into the specifics of writing code for Ecopages, it's important to understand how the core of Ecopages works. This knowledge will help you make better decisions when structuring your project and writing your code.

Integration System

Ecopages uses a flexible integration system to extend its functionality. Each integration plugin can provide:

  1. Template extensions
  2. Custom loaders
  3. Build hooks

For example, the KitaJS integration might set up template extensions like this:

  .setIncludesTemplates({
    head: 'head.kita.tsx',
    html: 'html.kita.tsx',
    seo: 'seo.kita.tsx',
  })

This configuration tells Ecopages which files to use for specific parts of the page structure.

CSS Processing

By default, Ecopages uses plain css for styling. We currently provide a simple Postcss and Tailwind (v3) plugin that provides a powerful and flexible system for managing your styles. You can customize this in your eco.config.ts file:

const config = await new ConfigBuilder()
  // ... other configurations
  .setProcessors([
    postcssProcessorPlugin()
  ])
  .build();

Script and CSS Loading

Ecopages handles script and CSS loading efficiently.

Please note that in order to have the scripts and css loaded, you need to set the dependencies property in the component's config.

This will chain all hte dependencies and remove duplicates, permitting you to ship just the scripts you need.

  1. CSS Loading: CSS files are typically loaded as separate files. They are referenced in the component's config and are automatically included in the final HTML.

  2. Script Loading: Scripts essential for the initial page render are loaded immediately.

Script File Detection

Ecopages uses a default extension prefix to detect script files: script.ts. This means that any file with the name pattern *.script.ts will be automatically recognized as a script file by Ecopages. For example:

These files will be processed and included in the build according to the dependencies specified in your component configurations.

import { RadiantCounter } from '@/components/radiant-counter';
import { BaseLayout } from '@/layouts/base-layout';
import { type EcoComponent, type GetMetadata, html } from '@ecopages/core';

const HomePage: EcoComponent = () => html`${BaseLayout({
    class: 'main-content',
    children: html`
      <h1>Ecopages</h1>
      !${RadiantCounter({
        count: 5,
      })}
    `,
  })}`;

HomePage.config = {
    importMeta: import.meta,
    dependencies: {
      components: [BaseLayout, RadiantCounter],
    },
};

Robots.txt Generation

Ecopages automatically generates a robots.txt file based on your configuration. You can customize this in your eco.config.ts file:

Loaders

Ecopages uses loaders to process your files. Each loader is responsible for processing a specific type of file.

In bun loaders are used to process your files. You can find more information about loaders in the bun documentation.

You can add it to your bunfig.toml file:

preload = ["@ecopages/bun-postcss-loader", "@ecopages/bun-mdx-kitajs-loader"]

Import CSS as String in JS Files

Ecopages provides a way to load CSS directly into your JavaScript files as strings using Bun's preload tools. This feature is available through the @ecopages/bun-postcss-loader package.

Import Mdx as a Component

Ecopages allows you to import MDX files as components. This is useful for creating reusable components that can be used across your site. This is possible thanks to the @ecopages/bun-mdx-kitajs-loader.

import Component from '@/components/mdx-component';

const MyPage = () => html`${Component()}`;

Project Structure

Ecopages expects a specific project structure:

my-project/
├── src/
│   ├── pages/
│   ├── layouts/
│   ├── components/
│   └── includes/
├── public/
├── eco.config.ts
└── package.json

This structure helps Ecopages efficiently process and build your site.

Runtime Origin and API Requests

When fetching data in getStaticPaths or getStaticProps, Ecopages provides different approaches. For most cases, calling your data functions directly is recommended for better performance and reliability.

Direct Function Calls (Recommended)

For the best performance during static generation, call your data layer functions directly:

import { getAllBlogPosts, getBlogPost } from '@/data/blog';

export const getStaticPaths: GetStaticPaths = async () => {
  const posts = getAllBlogPosts();
  
  return {
    paths: posts.map(post => ({
      params: { slug: post.slug }
    }))
  };
};

export const getStaticProps: GetStaticProps = async ({ pathname }) => {
  const slug = pathname.params.slug as string;
  const post = getBlogPost(slug);
  
  if (!post) {
    throw new Error(`Post not found: ${slug}`);
  }
  
  return { props: { post } };
};

HTTP Requests to External APIs

For external data sources, HTTP requests are necessary:

export const getStaticPaths: GetStaticPaths = async () => {
  const response = await fetch('https://external-api.com/posts');
  const posts = await response.json();
  
  return {
    paths: posts.map(post => ({
      params: { slug: post.slug }
    }))
  };
};

Runtime Support

Currently, Ecopages is designed to work exclusively with the Bun runtime. While the architecture supports multiple runtime adapters, at the moment only the Bun adapter is implemented and maintained.

This means you'll need to:

Server and API Handlers

Ecopages provides a simple and intuitive way to create API endpoints and handle server-side logic. You can find more details in the Server API documentation.

import { EcopagesApp } from '@ecopages/core/adapters/bun/create-app';
import appConfig from './eco.config';

const app = new EcopagesApp({ appConfig });

app.get('/api/hello', async () => {
  return new Response(JSON.stringify({ message: 'Hello world!' }));
});

await app.start();

Additional Features