Reference
Stock blueprints
Stock blueprints ship inside the rcf-lite npm package. This reference lists the available patterns, what each provides and how to compose them.
This reference lists the stock blueprints currently available in the package and adds a row when each new blueprint ships. An unlisted blueprint is not yet available. How it works explains blueprints and composition.
Where they live and how to apply one
Tell your agent what you are building and ask it to list suitable stock blueprints. It proposes a pattern and adds the slug you choose.
I want to start with a shape off the shelf. What's there, and which fits what I'm building?rcf define blueprint list
rcf define blueprint add @stock/<slug>The agent proposes a shape off the packaged shelf (plus any library your project has registered) and adds the slug you pick. Behind the scenes: add composes the chosen blueprint onto the chain under its own namespace; the packaged shelf itself is documented on the stock-blueprints reference page (there is no CLI verb today that pretty-prints the shelf by category), and `rcf define blueprint list` prints the blueprints already applied to this project.
The stock blueprints ship inside the rcf-lite npm package itself, alongside the compose mechanism, which is why the agent can list and add them with no repository checkout and no filesystem path. The bare slug does the same as @stock/<slug>: rcf define blueprint add application-spa resolves to the same packaged shelf. A filesystem path still works too, for a blueprint of your own. Mistype a slug and the refusal prints every slug on the shelf back at you, so the error message doubles as the catalogue.
Each blueprint's directory inside the installed package carries its own README with the full anatomy, and a guide/ doc covering when to use it, when not to, and what stays your call. The same files are browsable in the public rcf-lite repository.
application
Whole-app shapes.
| Blueprint | Version | Gives you |
|---|---|---|
application-spa |
1.5.11 | A single-page application pattern: public and authenticated surfaces, session-based auth, dark and light themes, responsive by default. |
application-api-rest |
2.1.10 | A REST service pattern: versioned wire contract, problem-details errors, pagination envelope, four auth classes, no UI in scope. |
application-error-handling |
1.0.12 | A shared internal error model: process-level and framework-level boundaries, a common error record (code, category, message, correlationId, cause chain, redacted context), a transient / permanent / unknown classification vocabulary, and a substitutable transportWriter seam that keeps the wire mapping out of the record shape. |
application-admin-console |
1.3.6 | An admin console shell whose surfaces adapt to your applied auth blueprint. |
application-charts |
1.0.10 | A chart-shell contract that reads for both a screen-reader user and a keyboard-only user: a paired text-alternative table beside every plot, non-colour cues on every series (shape, pattern or label alongside colour), keyboard traversal across the data points, and a reduced-motion path for any animated transition. The shipped probe pack anchors those checks directly (non-colour distinction, paired text-alternative table, and keyboard traversal with reduced motion). |
application-dashboard |
1.0.9 | A dashboard surface with a packaged design-guidance asset alongside the anatomy, so your agent has a real component-library-agnostic layout brief to build against. |
application-datatable |
1.0.9 | A data-table base contract carrying a proper ARIA table (or grid) shape, sortable columns, a filter surface, Page N of M pagination, row selection, persisted table state, and keyboard-navigable columns. The shipped probe pack anchors six browser checks across those surfaces (ARIA shape, sort, filter, pagination, selection and keyboard-column) rather than the smaller aria-rowcount plus phrasing shape earlier drafts described. |
application-notifications-in-app |
1.2.8 | The in-app notification shape: a preseeded live-region wrapper on every declared route, a transient toast contract with a WCAG-compliant priority-to-role mapping, and an inbox surface with retention and an acknowledge round-trip. |
application-empty-error-states |
1.2.7 | An eight-state contract for the moments a surface has nothing useful to say: not-found, forbidden, server-error, offline, permission-denied, empty-list, no-search-results and error-boundary. |
application-file-upload |
1.2.7 | A file-upload surface with a WCAG-compliant labelled input, a drop-zone alternative, keyboard traversal, refusal messages for over-size and disallowed type, per-file progress, a resumable-upload transport contract, and a virus-scan hook applied before the file is offered downstream. |
application-forms-wizard |
1.2.6 | The GOV.UK Design System's task-list and summary-list patterns as a multi-step wizard: per-step validation timing per the declared policy alternatives (on-blur before the first submit, on-change after the first failure, and a full pass on submit), an error-summary at the top with skip-links to the offending field, and a save-and-return contract with a draft-store transport left elicited on purpose. Ships a probe pack anchoring the task-list, the summary-list, the error-summary and the save-and-return round-trip. |
application-account-settings |
1.2.7 | A self-service settings area with five capability-gated surfaces: profile, security, sessions, notification preferences and theme. Only the profile and security surfaces (and, per the auth flavour, sessions) come from an applied auth blueprint on its own; notifications require application-notifications-in-app alongside, and theme requires application-spa alongside. Sessions come from any auth provider declaring sessionInventory (or from a custom-auth blueprint with its custom-auth-provides-session-inventory elicit answered). |
application-onboarding-tour |
1.1.9 | A first-run tour built on the ARIA APG dialog-modal pattern's tooltip-as-dialog shape: keyboard-only Escape and focus-return contracts, a checklist-on-dashboard fallback that collapses gracefully into the settings surface, and completion-state persistence via a completion-state-store elicit: spa-local-storage (the default) or spa-session-storage for local-only persistence, or server-side-per-principal (which requires an applied persistence blueprint to store the completion state). |
security
Auth and secrets.
| Blueprint | Version | Gives you |
|---|---|---|
security-auth-magic-link |
1.2.7 | Passwordless magic-link sign-in with server-issued opaque cookie sessions, pluggable email delivery and a pluggable principal registry. |
security-auth-clerk |
1.5.4 | Hosted identity via Clerk. The vendor owns the sign-in surface, credential storage, MFA and account recovery; the project owns a framework-agnostic middleware boundary, a session verifier confined to one module, and a reduced principal shape the rest of the codebase reasons against. |
security-auth-oauth2 |
1.3.6 | Vendor-neutral delegated identity via OAuth2 authorisation-code plus PKCE against any project-configured IdP (Google, GitHub, Microsoft, Okta, Auth0, a corporate ADFS-fronted OIDC, a self-hosted issuer). |
security-auth-keycloak |
1.4.4 | Delegated identity to a Keycloak realm the operator runs, federated through OIDC. |
security-secrets-management |
1.1.5 | A vendor-agnostic secrets-management contract: a repo-root secrets.yaml catalogue of named secrets, a sole-reader facade that is the only module talking to the underlying secrets manager, a least-privilege slice per consumer, a metadata-only audit event on every fetch, a stdin-only interface for local development, and an ephemeral .env shape for a scoped process life. |
The four auth-family blueprints deliberately disagree with each other on the project's authentication model. Composing any two on one chain raises a globalAdrTopic conflict at rcf define blueprint add; the four documented resolutions (adopt the incoming, keep the existing, project-level supersede, or --resolve authModel=project:<ADR-id> on the add) apply as they do for every conflict.
email
Message delivery adapters.
| Blueprint | Version | Gives you |
|---|---|---|
email-smtp-resend |
1.1.7 | A Resend-backed SMTP mail adapter that fills the magic-link blueprint's email-delivery slot as a shipped default. |
persistence
Durable stores and migration discipline.
| Blueprint | Version | Gives you |
|---|---|---|
persistence-data-sqlite |
1.1.5 | A SQLite-first durable store behind a single facade, with a forward-only numbered migration catalog applied atomically at open and a downtime-free file-level backup procedure. |
persistence-data-d1 |
1.1.6 | Cloudflare D1 as the durable store for Workers-deployed applications, behind a request-scoped Worker-side facade. |
persistence-data-postgres |
1.1.10 | A Postgres-backed durable store behind a facade that is the sole reader of the pg client. |
Composing any two of persistence-data-sqlite, persistence-data-d1 and persistence-data-postgres raises deliberate conflicts on the durable-store and migration-discipline decisions; the same conflict resolutions apply.
object-storage
Blob and file storage behind an S3-shape facade.
| Blueprint | Version | Gives you |
|---|---|---|
object-storage-s3 |
1.2.9 | An S3-API object store with Cloudflare R2 as the first adapter and MinIO as the local dev target: put, get, delete, list, a presigned-URL contract with a bounded TTL, multipart upload above an elicited threshold, and metadata-only lifecycle events. |
object-storage-s3 is the first blueprint on this family. The name space is set up for sibling adapters when they land, and adapter-specific behaviours are named in the shipped guide rather than baked into the facade: R2 uses forcePathStyle: false and region auto; MinIO uses forcePathStyle: true for its local addressing model.
messaging
Producer and consumer facades over a real queue.
| Blueprint | Version | Gives you |
|---|---|---|
messaging-queue-cloudflare |
1.1.3 | A Cloudflare Queues producer facade, consumer registration on the Worker's queue handler, publish, consume, ack, retry with the attempt counter, dead-letter contract per Cloudflare's own defaults (three retries, four-day DLQ retention), batch consume, and metadata-only lifecycle events. |
jobs
Scheduled and delayed background work on top of an applied queue.
| Blueprint | Version | Gives you |
|---|---|---|
jobs-background |
1.1.10 | A background-jobs contract: named job definitions with a handler, an input schema, a retry policy and a timeout; a scheduler that accepts cron expressions and one-shot delayed runs; retries on top of the applied queue; and a metadata-only run-log. |
platform
Cloudflare platform primitives, exposed through facade blueprints.
| Blueprint | Version | Gives you |
|---|---|---|
platform-cloudflare-kv |
1.1.4 | A Workers KV facade as the sole reader of the KV namespace binding. |
platform-cloudflare-cron-triggers |
1.1.3 | A scheduled() handler contract with an expression-router, a skew-tolerance discipline, and metadata-only lifecycle events (cronReady, cronFired, cronSkewed, cronStalled, cronUnmatched). |
platform-cloudflare-durable-objects |
1.1.3 | Two Durable Object shapes in one blueprint: a strong-consistency single-cell for coordination and a hibernatable WebSocket hub for many-to-one broadcast. |
platform-docker-compose-host |
1.1.17 | A docker-compose platform on a Hetzner Cloud server (or any Linux VM with cloudHost declared): Docker Engine and the Compose plugin installed by the compose-host installer (the host project runs the shipped installer after the VM baseline settles), a canonical compose.yaml at the repo root with named networks and volumes, per-service healthchecks on HTTP-terminating services, restart: unless-stopped for long-running services and on-failure for one-shots, and a reverse-proxy contract (Caddy by default, Traefik as the elicited alternative) with zero-downtime reload. |
The three platform-cloudflare-* blueprints share the cf-platform fixture root and can be applied alongside each other on the same project without conflict; each is the sole reader of its own Cloudflare binding. platform-docker-compose-host sits on the same shelf as the three Cloudflare-line platform blueprints but describes a different runtime: a compose stack on a Linux VM rather than a Cloudflare binding. A project picks the platform primitive its deploy foot needs (the Cloudflare-line platforms compose alongside deploy-cloudflare-workers; the compose host composes alongside deploy-hetzner-server). Nothing in the CLI today refuses a project that applies both a Cloudflare-line platform and the compose host at once, so the operator is on the hook for that judgement.
edge
Gates that run at the Cloudflare edge before the origin sees a request.
| Blueprint | Version | Gives you |
|---|---|---|
edge-cloudflare-access |
1.1.4 | A Cloudflare Zero-Trust Access JWT validator as the sole reader of the Cf-Access-Jwt-Assertion header, an Access application shape, an audit-event record with metadata-only secrecy, and a real-account gated-URL probe that runs accountBound-skipped without a Cloudflare account. |
edge-cloudflare-turnstile |
1.1.3 | A Cloudflare Turnstile widget mount pinned to the vendor host, server-side siteverify against https://challenges.cloudflare.com/turnstile/v0/siteverify, a refuse-if-token-missing guard, and pinned public test sitekeys (always-pass, always-fail and forced-interactive) paired with their test secrets so CI needs no real Turnstile credentials to exercise the deterministic branches. |
edge-cloudflare-rate-limiting |
1.1.3 | A local manifest under cloudflare/rate-limits/*.json as the sole declaration of the zone-level rate-limit rules, a drift audit that compares the applied Cloudflare account against the manifest, an accountBound-skipped burst-and-429 probe that exercises the throttle behaviour end to end, and an edgeRateLimit capability declaration for downstream blueprints to consume. |
edge-cloudflare-tunnel |
1.1.3 | Cloudflare Tunnel as the ingress bridge from the Cloudflare edge to an off-edge origin. |
The four edge-cloudflare-* blueprints compose along the request path: Turnstile in front of a public form, Access in front of an admin surface, rate-limiting as the zone-level guard on top of both, and the tunnel as the bridge back to an off-edge origin. None of the four conflict with each other; each takes a slice of the ingress path. Access and the tunnel compose specifically: applying both attaches the Access AUD to the tunnel ingress rules through zeroTrustGate, so the JWT check runs at the connector.
delivery
Checks that gate incoming changes.
| Blueprint | Version | Gives you |
|---|---|---|
delivery-ci-workflows |
2.3.5 | A CI workflow set composed from a workflow shape you declare once in a small config file. In the default feature-branch mode two commit-triggered check workflows are materialised (pull-request checks and default-branch checks); a trunk-only mode without trunkPullRequests materialises default-branch-checks alone. |
observability
Health, readiness, probes, status pages.
| Blueprint | Version | Gives you |
|---|---|---|
observability-essentials |
2.1.6 | Liveness and readiness HTTP probes with strict semantics, a public status page with machine-readable incident notices, and a durable notification-outcome sink. |
observability-logging |
1.3.7 | A structured-logging surface: ECS-neutral single-line JSON emission, correlation-identifier acceptance / propagation / reflection, PII redaction at the emission boundary by named category, operator-elicited minimum level per environment, and a hermetic in-memory capture mode for tests. |
observability-probe-endpoints |
1.2.5 | A health probe interface derived from an operator-declared target integration profile: Kubernetes, load balancer, uptime monitor, systemd, docker healthcheck, reverse proxy, plus a custom:<name> slot. |
Composing observability-essentials v2.0.0 with observability-probe-endpoints v1.1.0 is a supported combination since the 0.18.0 shelf alignment. observability-probe-endpoints is the sole shelf-wide scope: global claimant on the health-probe and readiness-semantics topics, and observability-essentials reads the resolved probe path set from it. An essentials-alone project supplies the same paths itself via probeInterface.paths.
deploy
Deploying artefacts to a running target.
| Blueprint | Version | Gives you |
|---|---|---|
deploy-cloudflare-workers |
1.3.2 | Cloudflare Workers deploy with an artefact-upload plus explicit-promote model: three addressable URLs (per-version, stable preview alias, production), a single Deploy Adapter as the sole vendor caller, a repo-root wrangler manifest as the sole declaration of deploy shape, rollback-is-promote, and a served-surface verifier on every promote. |
deploy-hetzner-server |
1.1.17 | Hetzner Cloud server provisioner as the shipped Linux VM deploy foot, sibling to deploy-cloudflare-workers on the shelf. |
The two deploy-* blueprints use different global ADR topics (deployment-target for deploy-cloudflare-workers; linux-cloud-host-contract and snapshot-and-backup-cadence for deploy-hetzner-server), so composing both on one project does not raise a globalAdrTopic conflict today: the CLI does not enforce a deploy-family one-target-per-project rule. If you apply both, you carry two deploy targets on the same chain by design; the recorded acknowledgement of that choice is currently on the operator, and the finalise gate does not itself refuse the composition. Extending the conflict machinery to a shared deploy-family topic is on the shelf's roadmap.
Apply commands
The compose command is the same for each, and this list is generated from the packaged shelf at build time:
rcf define blueprint add @stock/application-account-settings
rcf define blueprint add @stock/application-admin-console
rcf define blueprint add @stock/application-api-rest
rcf define blueprint add @stock/application-charts
rcf define blueprint add @stock/application-dashboard
rcf define blueprint add @stock/application-datatable
rcf define blueprint add @stock/application-empty-error-states
rcf define blueprint add @stock/application-error-handling
rcf define blueprint add @stock/application-file-upload
rcf define blueprint add @stock/application-forms-wizard
rcf define blueprint add @stock/application-notifications-in-app
rcf define blueprint add @stock/application-onboarding-tour
rcf define blueprint add @stock/application-spa
rcf define blueprint add @stock/delivery-ci-workflows
rcf define blueprint add @stock/deploy-cloudflare-workers
rcf define blueprint add @stock/deploy-hetzner-server
rcf define blueprint add @stock/edge-cloudflare-access
rcf define blueprint add @stock/edge-cloudflare-rate-limiting
rcf define blueprint add @stock/edge-cloudflare-tunnel
rcf define blueprint add @stock/edge-cloudflare-turnstile
rcf define blueprint add @stock/email-smtp-resend
rcf define blueprint add @stock/jobs-background
rcf define blueprint add @stock/messaging-queue-cloudflare
rcf define blueprint add @stock/object-storage-s3
rcf define blueprint add @stock/observability-essentials
rcf define blueprint add @stock/observability-logging
rcf define blueprint add @stock/observability-probe-endpoints
rcf define blueprint add @stock/persistence-data-d1
rcf define blueprint add @stock/persistence-data-postgres
rcf define blueprint add @stock/persistence-data-sqlite
rcf define blueprint add @stock/platform-cloudflare-cron-triggers
rcf define blueprint add @stock/platform-cloudflare-durable-objects
rcf define blueprint add @stock/platform-cloudflare-kv
rcf define blueprint add @stock/platform-docker-compose-host
rcf define blueprint add @stock/security-auth-clerk
rcf define blueprint add @stock/security-auth-keycloak
rcf define blueprint add @stock/security-auth-magic-link
rcf define blueprint add @stock/security-auth-oauth2
rcf define blueprint add @stock/security-secrets-management
Most projects apply a handful, not the full set. Composing conflicting blueprints on the auth or persistence topics is refused at add time with both sides shown; the two deploy blueprints do not currently share a global topic and both can apply on one project (see the note under the deploy family above); some (object-storage-s3, jobs-background) refuse until their prerequisite is applied with a stable message id and a paired override flag. How it works covers the conflict machinery in detail.
Checking this page
The shelf above is checkable the same way the status page is: the packaged shelf inside the installed rcf-lite is the truth, and the slugs, versions and apply commands on this page are read from it at build time. rcf define blueprint list prints what is applied to your own project, and misspelling a slug at rcf define blueprint add prints the live shelf list back at you. If a blueprint listed here is missing from the package, that is a defect in this page.