digirati-co-uk/ssr-pipeline
.agents/skills/ssr-pipeline/SKILL.md
Trace or modify Madoc TS server-side rendering for site and admin. Use when changing SSR output, template injection, dev HMR SSR wiring, or debugging SSR redirects and template tokens in services/madoc-ts.
$ install --global
skillsauthnpx skillsauth add digirati-co-uk/madoc-platform ssr-pipelineInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 16, 2026, 3:52 PM12.6s2 files scanned
SKILL.md
- name:
- ssr-pipeline
- description:
- Trace or modify Madoc TS server-side rendering for site and admin. Use when changing SSR output, template injection, dev HMR SSR wiring, or debugging SSR redirects and template tokens in services/madoc-ts.
SSR Pipeline (Madoc TS)
Overview
Explain how server-side rendering is performed for site and admin, how SSR output is injected into HTML templates, and how dev-mode HMR SSR output is constructed.
Key Entry Points
- Site SSR handler:
services/madoc-ts/src/routes/frontend/site-frontend.ts - Admin SSR handler:
services/madoc-ts/src/routes/frontend/admin-frontend.ts - Site template:
services/madoc-ts/src/site.html - Admin template:
services/madoc-ts/src/admin.html - Client entrypoints referenced in templates:
services/madoc-ts/src/frontend/site/client.tsservices/madoc-ts/src/frontend/admin/client.tsx
SSR Flow Summary (Based on Source)
- Both site and admin handlers set
context.staticPageto an async renderer. - Each renderer calls a corresponding
render*function:- Site:
renderSitefromsrc/frontend/site/server - Admin:
renderAdminfromsrc/frontend/admin/server
- Site:
- The render result includes
body,head,htmlAttributes, andbodyAttributes. - If
result.type === 'redirect', the handler returns a redirect (statusresult.status || 307) or a404if notois provided. - In
NODE_ENV === 'development', HTML is built inline with Vite HMR scripts and a dynamic host-based dev URL (port3088). - In non-dev,
context.siteTemplateorcontext.adminTemplateis used, with token replacement:<!--ssr-outlet-->replaced byresult.body<!--ssr-head-->replaced byresult.head<html>and<body>tags are replaced to include attributes from SSR output.
Quick Start Workflow
- Inspect
site-frontend.tsandadmin-frontend.tsto see howcontext.staticPageis set and how SSR results are injected. - Confirm template token usage in
site.htmlandadmin.html. - For dev SSR, verify HMR and client script injection for the correct entrypoints:
- Site:
/src/frontend/site/client.ts - Admin:
/src/frontend/admin/client.tsx
- Site:
- If changing SSR output shape, ensure callers handle
result.type === 'redirect'andresult.body/headexpectations.
Development Mode Details
- Dev HTML includes
@react-refreshand aviteProtocolderived from TLS certs at/home/node/app/openssl-certs. - Hostname is taken from
context.request.hostname. - Site adds a stylesheet link to
src/frontend/site/index.cssin dev mode.
Common Tasks
- Update SSR head/body injection
- Debug SSR redirect behavior
- Add SSR-injected assets (ensure matching template tokens)
- Troubleshoot dev HMR SSR boot failures
Pitfalls
- Missing or renamed template tokens (
<!--ssr-head-->,<!--ssr-outlet-->) - Mismatch between SSR output and template replacement
- HMR dev URLs breaking on custom hostnames or protocol mismatch
Suggested Checks
- One request to a site page (SSR HTML contains
result.headandresult.body) - One request to an admin page (SSR HTML contains
result.headandresult.body) - In dev, confirm the HMR preamble loads and the client entrypoints are correct
Related Skills
digirati-co-uk/utility-core
tools
VerifiedTrustedCommunity
Work on Madoc TS shared utility helpers (JWT, metadata, errors, IIIF helpers, auth helpers). Use when changing core utility functions or shared helpers in services/madoc-ts.
56SKILL.mdUpdated Apr 16, 2026
digirati-co-uk/types-schemas
development
VerifiedTrustedCommunity
Work on Madoc TS shared type definitions and schema contracts. Use when updating TypeScript types, JSON schema shapes, or cross-layer data contracts in services/madoc-ts.
56SKILL.mdUpdated Apr 16, 2026
digirati-co-uk/tasks-automation
tools
VerifiedTrustedCommunity
Understand and extend Madoc TS task automation, including bots and task-related extensions. Use when adding task automation, bot behavior, or task metadata resolution in services/madoc-ts.
56SKILL.mdUpdated Apr 16, 2026
digirati-co-uk/ssr-site
development
VerifiedTrustedCommunity
Work on Madoc TS site SSR pipeline, HTML template injection, and site render data wiring. Use when changing site SSR behavior, template tokens, or site SSR data wiring in services/madoc-ts.
56SKILL.mdUpdated Apr 16, 2026