alpine - chirp-ui

Alpine runtime detection for chirp-ui.

chirp-ui has a small, enumerable set of macros that require chirpui-alpine.jsto work at runtime (theme toggle, dialogs, dropdowns, collapsible sidebar, etc). When an app ships a layout that imports those macros but forgets the script tag, every interactive component breaks silently.

This module exposes the manifest of Alpine-requiring factories and a purecheck_alpine_runtime() helper. Chirp's use_chirp_ui(app) calls the helper against the first rendered response at freeze time so the mistake surfaces as a warning (or a raised error, in dev) at startup rather than as broken UI in production.

Example::

from chirp_ui.alpine import check_alpine_runtime

result = check_alpine_runtime(rendered_html)
if not result.ok:
    missing = ", ".join(sorted(result.missing))
    raise RuntimeError(
        f"layout uses Alpine factories {{{missing}}} but "
        "chirpui-alpine.js is not in the rendered HTML"
    )

alpine

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

class AlpineRequirement

A single Alpine factory and the macros that emit it.

factory is the identifier used inx-data="chirpuiXxx(...)"— the grep target inside rendered HTML.…

class AlpineRuntimeCheck

Result ofcheck_alpine_runtime().

script_loaded —chirpui-alpine.jssubstring appears in the HTML.

factories_used — named chirp-ui factories detected inx-data=attributes. Empty when no…

function check_alpine_runtime

Scan rendered HTML for chirp-ui Alpine factories and the runtime script.

Pure function: no I/O, no framework coupling. Pass the full rendered HTML of…

AlpineRequirement

class

A single Alpine factory and the macros that emit it.

factory is the identifier used inx-data="chirpuiXxx(...)"— the grep target inside rendered HTML.

macros are the chirp-ui template macros that emit this factory. Included for documentation; detection is purely by factory name.

conditional describes the macro argument combination that triggers the requirement when it is not unconditional. Informational only.

AlpineRuntimeCheck

class

Result ofcheck_alpine_runtime().

script_loaded —chirpui-alpine.jssubstring appears in the HTML.

factories_used — named chirp-ui factories detected inx-data= attributes. Empty when no interactive chirp-ui components rendered.

missing — factories used in the HTML that are not in the ALPINE_REQUIRED_COMPONENTSmanifest (useful for drift detection) OR, when script_loaded is False, all factories_used.

ok —Truewhen no factories are used, or when the chirpui-alpine.js script tag is present. Falsewhen at least one Alpine-requiring component rendered but the script is missing. This is the narrow registration-script check; it intentionally does not consider Alpine core (see below).

core_loaded — an Alpine core<script>is present (detected by analpinejs@/@alpinejs/csp src or Chirp's data-chirp="alpine" marker). chirp-ui factories need bothchirpui-alpine.js(to register them) and Alpine core (to run them).

core_url_valid — an Alpine core script is present and uses the browser build (path ends in/dist/cdn.min.js). A bare alpinejs@<version>resolves to the CommonJS main and fails silently in browsers — the exact footgunproblemsflags.

core_loaded / core_url_valid are only meaningful against a fully injected response or a hand-authored page. At pre-injection layout freeze time Alpine core is not in the HTML yet, so rely on ok / script_loaded there.

check_alpine_runtime

function

def check_alpine_runtime(html: str) -> AlpineRuntimeCheck

Scan rendered HTML for chirp-ui Alpine factories and the runtime script.

Pure function: no I/O, no framework coupling. Pass the full rendered HTML of a layout (or any page) and inspect the result.

The scan matchesx-data="chirpuiXxx("— double or single quoted, identifier must begin withchirpui, and must be followed by an opening paren (anonymous Alpine state likex-data="{ shown: false }" is intentionally ignored; those only need Alpine core, not chirpui-alpine.js).

The script marker match is a plain substring search for chirpui-alpine.js. Any path prefix or minification suffix is fine as long as the filename appears somewhere in the HTML.

Alpine core detection (core_loaded / core_url_valid) scans for analpinejs@/@alpinejs/cspscript src or Chirp's data-chirp="alpine"marker, and verifies the browser build suffix /dist/cdn.min.js. These are only meaningful against fully-injected HTML — at pre-injection freeze time Alpine core is not in the page yet.

Parameters

Name	Type	Default	Description
`html`	`str`	—

View source · /home/runner/work/chirp-ui/chirp-ui/site/../src/chirp_ui/alpine.py:1