AbsoluteJS

Includes & Layouts

HTML and HTMX pages share markup through build-time includes. The build replaces each <abs-include> with the file it names, so the served page is plain HTML. There is no runtime cost and no expression language.

#Partials

<abs-include src="…" /> is replaced with the contents of the file in src. The path is relative to the file that contains the tag. Included files can include others. The paired form, <abs-include src="…"></abs-include>, works the same. <abs-slot> and <template slot="…"> can be self-closing too, anywhere, including inside other includes.

HTML
<!-- html/partials/header.html -->
<header>
  <a href="/">Home</a>
  <a href="/about">About</a>
</header>

<!-- html/pages/Contact.html -->
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Contact</title>
  </head>
  <body>
    <abs-include src="../partials/header.html" />
    <main>…</main>
  </body>
</html>

#Layouts and Slots

A layout marks where content goes with <abs-slot>. The default slot has no name. Other slots have a name. Whatever a slot contains is its fallback, used when the page doesn't fill it.

HTML
<!-- html/layouts/base.html -->
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <abs-slot name="head"><title>My site</title></abs-slot>
  </head>
  <body>
    <abs-include src="../partials/header.html" />
    <main><abs-slot /></main>
    <abs-slot name="footer"><footer>Default footer</footer></abs-slot>
  </body>
</html>

A page fills the slots with the include's children. Put content for a named slot in <template slot="name">. Everything else goes to the default slot. Here the page sets the title, fills the main content, and keeps the default footer.

HTML
<!-- html/pages/About.html -->
<abs-include src="../layouts/base.html">
  <template slot="head"><title>About us</title></template>
  <h1>About us</h1>
  <abs-include src="../partials/team.html" />
</abs-include>
TS
// backend/server.ts
import { asset, handleHTMLPageRequest } from '@absolutejs/absolute';

new Elysia()
  .get('/about', () => handleHTMLPageRequest(asset(manifest, 'About')))
  .get('/post', () => handleHTMLPageRequest(asset(manifest, 'Post')));

#Nested Layouts

A layout can include another layout and pass its own slots on. Put an <abs-slot> inside the content it gives the outer layout.

HTML
<!-- html/layouts/article.html -->
<abs-include src="base.html">
  <template slot="head"><abs-slot name="head" /></template>
  <article><abs-slot /></article>
</abs-include>

<!-- html/pages/Post.html -->
<abs-include src="../layouts/article.html">
  <template slot="head"><title>A post</title></template>
  <h1>A post</h1>
</abs-include>

#What Counts as a Page

Only the .html files directly inside pages/ are pages. They get a manifest entry and can be served with handleHTMLPageRequest or handleHTMXPageRequest. Keep partials and layouts in a sibling directory inside your HTML or HTMX directory. The dev server watches them, and they never become pages.

TXT
src/frontend/html/
├── pages/          # each .html file directly in here is a page
│   ├── About.html
│   └── Post.html
├── layouts/        # included only, never served on their own
│   ├── base.html
│   └── article.html
└── partials/
    ├── header.html
    └── team.html

#Build-Time Resolution

The build expands includes in each copied page before anything else processes it. Included markup gets everything a page's own markup gets: <absolute-island> tags are server-rendered and hydrated, stylesheet and script links get their hashed paths, and images are optimized.

Stylesheet and script links are matched by file name, so a relative path in a partial works wherever the partial is included. Root-relative URLs such as /assets/… pass through unchanged, as they do in pages.

#Errors

An include cycle fails the build. The error names the file that includes itself and the whole include chain.

TXT
error: Include cycle: src/frontend/html/partials/a.html includes itself
  include chain: src/frontend/html/pages/Loop.html → src/frontend/html/partials/a.html → src/frontend/html/partials/b.html → src/frontend/html/partials/a.html

A missing file fails the build the same way.

TXT
error: <abs-include src="../partials/missing.html"> in src/frontend/html/pages/Loop.html: file not found (/home/you/app/src/frontend/html/partials/missing.html)
  include chain: src/frontend/html/pages/Loop.html → src/frontend/html/partials/missing.html

An <abs-include> or <abs-slot> that is never closed fails the build too. The error gives the file and line.

TXT
error: Unclosed <abs-include src="../partials/header.html"> in src/frontend/html/pages/Contact.html:8: close it with </abs-include> or make it self-closing (<abs-include … />)
  include chain: src/frontend/html/pages/Contact.html

#Dev HMR

In absolute dev, editing a page live-updates it. Editing a partial or a layout live-updates every open page that includes it, directly or through another include. Each tab gets its own page with its own slot content and the partial's new text, so two tabs on two pages that share a layout both stay correct.

Text that a script changed on an element with an id, such as a counter, is kept across live updates. Text you edit in the markup always shows the new version.