Sigment Architecture – HTML-First Approach

Introduction

Sigment is a framework that allows developers to build highly efficient web applications by leveraging a hybrid architecture that combines SSR (Server-Side Rendering) with client-side interactivity. This approach optimizes load times and performance by allowing critical content to be rendered on the server while enabling dynamic features on the client.

In this guide, we’ll go through the process of setting up the HTML-First Architecture with Sigment and how to use components, layouts, routing, and runtime loading.

Folder Structure

src/
├── html/
│   ├── layouts/
│   │   └── index.html
│   ├── about/
│   │   └── index.html
│   └── assets/
│       └── styles.css
├── components/
│   ├── Header.js
│   ├── Footer.js
│   └── About.js
├── router/
│   └── Routes.js
└── loadAtRuntime.js

1. HTML Folder & Layouts

The html/ folder contains all the HTML files and layout templates. Layout templates like index.html can be overridden by specific pages such as about/index.html.

1.1 src/html/layouts/index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>Sigment HTML-First Architecture</title>
  <link rel="stylesheet" href="/assets/styles.css">
</head>
<body>

<header>
  <div data-component="Header" runAtServer></div>
</header>

<main>
  <div data-part="sectionA"></div>
  <div data-part="sectionB"></div>
  <div data-part="sectionC"></div>
</main>

<footer>
  <div data-component="Footer" runAtServer></div>
</footer>

</body>
</html>

1.2 src/html/about/index.html

<layout data-layout="layouts/index.html"></layout>
<description data-description="About Us Page"></description>
<keywords data-keywords="about, sigment"></keywords>

<div data-part="sectionA">
  <h1>About Sigment</h1>
  <p>This page shows the About component.</p>
  <div data-component="About" runAtServer></div>
</div>

2. Components

2.1 src/components/Header.js

import 'sigment';

function Header() {
  return div("Welcome to Sigment!");
}

export default Header;

2.2 src/components/Footer.js

import 'sigment';

function Footer() {
  return div("© 2025 Sigment. Built with love for developers");
}

export default Footer;

2.3 src/components/About.js

import 'sigment';

function About() {
  return div(
    h1("About Sigment"),
    p("Sigment is a lightweight framework for building modern, fast web applications.")
  );
}

export default About;

3. Routing

const Routes = {
  "/": {
    loader: () => import('../components/Home.js')
  },
  about: {
    path: '/about/:id?/:pageid?',
    loader: () => import('../components/About.js')
  },
  fallback: {
    path: "*",
    loader: () => import("../components/NotFound.js")
  }
};

export default Routes;

4. Runtime Loading

Sigment allows you to dynamically load components at runtime — ideal for global or reusable UI parts that can appear anywhere in your app, independent of routes.

const loadAtRunTime = {
  defaultKey: "/",     
  "header": () => import('../components/Header.js'),
  "footer": () => import('../components/Footer.js')
};

export default loadAtRunTime;

These components can be injected directly into any HTML page using:

<div data-component="Header" runAtServer></div>

This makes it easy to reuse global parts like Header or Footer across multiple pages without defining them in routes.

5. Server Rendering with `runAtServer`

The runAtServer attribute is handled during the build process, not at runtime. When the compiler encounters an element with runAtServer, it pre-renders that component into static HTML. This ensures that the generated HTML in the dist folder already contains the final markup, improving SEO and initial load performance.

When the page loads in the browser, Sigment automatically hydrates that server-rendered HTML — attaching client-side interactivity. If you remove runAtServer, the component will only render on the client (no SSR).

Rules

Components declared with data-component must be empty containers:
```
<div data-component="Header" runAtServer></div>
```
Never include inner HTML inside the component container.
Use runAtServer for components that benefit from pre-rendered content such as headers, meta sections, or above-the-fold elements that impact SEO.

🔀 Routing vs ⚙️ Runtime Loading

Sigment supports two methods for dynamically loading components — Routing and Runtime Loading — each designed for different use cases.

⚙️ Runtime Loading

Folder: /load-at-runtime/components.js
Best for global, reusable UI components (Header, Footer, Widgets)

🔀 Routing

Folder: /router/Routes.js
Best for page-level components or views that depend on URL routes and parameters

const Routes = {
  "/about": () => import('../pages/About.js'),
  "/blog/:id": () => import('../pages/BlogPost.js'),
};

🧭 When to Use Each

Situation	Recommended
Component reused globally (e.g. header, footer)	Runtime Loading
Component tied to specific URL (e.g. /about, /user/:id)	Routing
Component needs route params or guards	Routing
Component can appear on any page	Runtime Loading

6. Styles

:root {
  --bg: #0f0f11;
  --fg: #ffffff;
  --primary: #ff3e00;
  --secondary: #1e1e22;
  --muted: #888;
}
/* ... rest of the CSS ... */

7. Building and Running the Project

npm run build
npm run dev
npm run start

8. Project Repository

To see a live example and explore the code further, visit the official GitHub repository: Sigment HTML-First Architecture Example

Conclusion

This guide provides the foundation for building an HTML-First architecture application using Sigment. It combines SSR for initial fast rendering with client-side hydration for dynamic components, optimizing the performance of modern web applications.