Integration notes

Sercrod is designed to stay small and focused. It does not try to own your whole stack. Instead, you drop it into existing pages, docs, or applications where attribute-based behavior is helpful.

This page describes common integration patterns and what to pay attention to when combining Sercrod with other tools.

1. Plain HTML pages

The simplest integration is a static HTML file with a Sercrod host in it. The rough steps are:

1. Include sercrod.js on the page.
2. Add one or more <serc-rod> hosts.
3. Use directives such as *let, *print, *if, *for, or *input inside each host.

A minimal example is shown in Guide: first page. In that setup, existing HTML can stay as it is. Only the parts that need behavior are wrapped in a host.

You do not have to restructure the whole site into components just to use Sercrod. It works well for a few interactive blocks on an otherwise static page.

2. Docs and content sites

A common use case is documentation or content-heavy sites where:

• most of the page is static text,
• you want a few live examples, forms, or filters,
• and you do not want to introduce a large framework.

In that pattern:

• main content is written as normal HTML (or generated from Markdown),
• live examples are wrapped in <serc-rod> with small data objects and a few directives,
• the rest of the page stays framework free.

When using Markdown or a CMS, make sure it does not escape or strip:

• the <serc-rod> tag itself,
• directives like *let, *for,
• and interpolation markers such as %name%.

If your content pipeline rewrites HTML aggressively, it may be better to keep Sercrod examples in separate partial files and include them as raw HTML.

3. With static site generators and SSR

For static site generation or server side rendering, Sercrod can be run in a headless browser using tools like Playwright. In that mode it acts as an attribute based templating layer:

• the source HTML contains Sercrod hosts and directives,
• a build step renders them once and writes plain HTML to disk,
• the output can optionally keep or drop Sercrod specific attributes depending on your cleanup settings.

The details of this pipeline, including template files and the Node or Playwright setup, are described in SSG and SSR.

4. As a leaf inside other frameworks

Sercrod can be used as a leaf component inside other frameworks or libraries. In this pattern:

• the outer framework (for example a UI library or SPA) renders a wrapper element,
• inside that wrapper you place a <serc-rod> host, often with a static template,
• the outer framework passes data down through attributes or properties, and Sercrod takes care of rendering its subtree.

A typical contract looks like this:

• parent sets host.data = {...} when something changes,
• Sercrod re-renders that host based on the new data,
• results are reflected in the DOM inside the host only.

This works well when you want to keep a template in plain HTML but still connect it to a parent state. It is not intended for bidirectional state sharing or deep cross integration. In most cases, Sercrod should own only a small, well defined subtree.

5. With CMS or existing backends

When integrating with a CMS or existing backend:

• keep HTML templates as close to normal as possible and use directives only where needed,
• use lifecycle helpers such as *fetch and *post for small JSON endpoints, not for reimplementing a full client API,
• ensure the CMS editor does not strip custom tags or attributes.

If the CMS has a block or component system, Sercrod can be used to implement a few blocks that rely on attributes and small JSON fragments, while the rest of the site keeps using the CMS standard features.

6. Progressive enhancement

Where possible, use Sercrod as progressive enhancement:

• write fallback content inside hosts so the page still makes sense without JavaScript,
• keep basic form behavior working with plain HTML where feasible,
• avoid hiding primary navigation or important text behind Sercrod only behavior.

In this style, Sercrod improves the experience when available, but the site remains functional and readable otherwise.

7. When not to use Sercrod

Sercrod is not a replacement for a full application framework. You may not want to use it when:

• the entire page is already driven by a single reactive framework that owns all state,
• you need complex routing, global state management, or animation systems that another tool already provides,
• you would be duplicating state between Sercrod and another layer for the same DOM subtree.

Used in the right scope, Sercrod is a small, predictable layer that lets you keep HTML in control while adding just enough behavior where attributes make sense.