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.

For the design principles behind Sercrod's coexistence model, see Coexistence by design.

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. Platform results and API calls

Platform plugins can also stay outside Sercrod while still feeding Sercrod data. Keep the plugin-specific JavaScript small, assign the result to host data, and use communication directives for the server request.

How remote push delivery flows

A remote push notification is not sent from Sercrod directly to a device. The app first registers with a push provider and obtains a device token. It hands that token to the application endpoint. Later, the application server asks the appropriate provider to deliver a notification to that token.

Application server
├─ Android token → FCM  → Android device
└─ iOS token     → APNs → iPhone

A project may instead use a service that presents one server-side API and relays messages to the platform providers. The final Apple delivery path still uses APNs. Provider selection, account setup, credentials, pricing, quotas, and production configuration are provider concerns; check the current Firebase Cloud Messaging documentation, Apple Push Notification service documentation, and the documentation for the plugin or delivery service selected by the application.

<p *push="/api/push"></p>
<button *if="$push && $push.needs_action" *push.register>
  Enable notifications
</button>

The adapter obtains the provider registration and POSTs { action, registration } to the explicitly declared endpoint. Use custom native code plus *api only for a provider or plugin that the push adapter does not support. Token storage, provider credentials, and production policy remain application-side responsibilities.

Responsibility boundary

• Sercrod client integration may expose permission checks, device registration results, tokens, registration errors, received notifications, and notification actions as explicit application data and events.
• *push hands a normalized registration only to the endpoint explicitly declared by the application. Sercrod does not choose or operate that endpoint.
• The application operator owns the provider account, private server credentials, token database, hosting, server-side delivery, recipient selection, and production notification policy.
• Examples may show placeholder fields, but real provider passwords, service-account private keys, APNs private keys, and server send credentials must not be placed in public HTML, client-side JavaScript, app bundles, Sercrod adapter code, or this repository.

This boundary is implemented by the optional sercrod.push adapter and *push directive family. Applications must load the adapter explicitly and provide the selected platform plugin or browser setup.

7. 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.

8. 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.