morph: Instructions file for Codex

Morph — Documentation for AI Agents

This document provides structured information for LLM agents to effectively build web applications using Morph.

Overview

Morph is a server-side rendering library for building web UIs with HTMX and Hono. Key characteristics:

• Runtime: Deno, Bun, or Node.js
• No build step: TypeScript runs directly
• Server-rendered: All components execute on the server
• HTMX-powered: Partial page updates without client JavaScript

Project Setup

File Structure (Minimal)

project/
├── deno.json        # or package.json for Node/Bun
└── main.ts          # entry point

File Structure (Recommended)

project/
├── deno.json
├── main.ts
├── components/
│   ├── layout.ts    # wrapper, navigation
│   ├── pages/       # page components
│   └── partials/    # HTMX-updatable components
└── tests/
    └── *.test.ts

Dependencies

// deno.json
{
  "imports": {
    "@hono/hono": "jsr:@hono/hono@4",
    "@vseplet/morph": "jsr:@vseplet/morph"
  }
}

Core Concepts

1. Components

Components are functions that return HTML templates.

import { component, html } from "@vseplet/morph";

// Basic component (no props)
const header = component(() =>
  html`
    <header>
      <h1>My App</h1>
    </header>
  `
);

// Component with typed props
const userCard = component<{ name: string; email: string }>((props) =>
  html`
    <div class="user-card">
      <h3>${props.name}</h3>
      <p>${props.email}</p>
    </div>
  `
);

// Async component (can fetch data)
const userList = component(async (props) => {
  const users = await fetchUsers();
  return html`
    <ul>
      ${users.map((u) => userCard({ name: u.name, email: u.email }))}
    </ul>
  `;
});

2. Available Props in Components

Every component receives MorphPageProps:

interface MorphPageProps {
  request: Request; // Raw HTTP request
  route: string; // Current route path
  params: Record<string, string>; // URL params (:id -> params.id)
  query: Record<string, string>; // Query string (?foo=bar -> query.foo)
  headers: Record<string, string>; // Request headers
  hx: () => string; // Returns hx-get attribute for self-refresh
}