#@alepha/sigil

Reports page views, vitals and errors from an Alepha app to a Sigil instance.

#Installation

npm install @alepha/sigil

#Overview

The sigil an Alepha app reports under: page views, web vitals, and client and server errors, pushed to a sink that the app names.

Import this module in your WebModule and set SIGIL_KEY. That is the whole enrolment: the key authorises the reporting and names the project reported into, being shaped sg_<project>_<secret>. SIGIL_SINK defaults to the public Lore instance and is only needed to self-host, SIGIL_CONFIG is optional switches over what to collect, and SIGIL_SALT falls back to APP_SECRET. Without a key the module still captures, but nothing leaves the machine: errors go to the logger instead, aggregated.

Production only, on both halves. The browser bootstrap returns early outside production; the server sink captures locally and sends nothing. A key is a credential, not permission to report from a laptop - with only the key gating delivery, every alepha dev session and CI job counted as traffic on the project's own dashboard. A staging deployment that needs to prove its enrolment before production does sets {"reportOutsideProduction":true} in SIGIL_CONFIG, which turns the server half on and says so at boot.

The feedback button mounts itself. <SigilRoot /> is pushed into RootComponentsProvider, so importing this module is the whole integration: there is no second module and no JSX to place. The component renders null unless the sink hands out a feedbackUrl and the current path is not excluded, so an app with no sink configured sees nothing.

This entry therefore pulls React. That was once avoided so a headless API app could import the module without it, but react and react-dom are already peer dependencies of this package, so such an app had to install them anyway. The split bought one unused import at the cost of a second module every host had to know about. If a genuinely React-free consumer ever appears, move the register below into its own module behind @alepha/sigil.

An app that wants the link somewhere else in its own layout can still render it from useFeedbackUrl(); <SigilRoot /> hides itself when there is no URL, so the two do not fight.

Server services self-guard to the server; the browser bootstrap guards the browser.