@bradleywilkerson/site

Shared building blocks every ABC Agency client site depends on. Client sites are created from client-site-template and consume this package.

The contract

Client sites pin ^, so minors reach them automatically. That makes one rule non-negotiable:

New config fields are always optional with a default.

Adding a required field to ClientConfig is a breaking change and needs a major. It is also the mistake most likely to happen, because it feels harmless while you are writing it.

Three things are the contract: the ClientConfig shape, component prop signatures, and export names. Everything else is free to change.

Exports

| Import | What it gives you | |---|---| | @bradleywilkerson/site/config | ClientConfig, displayPhone, formatPhone, validateConfig | | @bradleywilkerson/site/schema | localBusinessSchema, articleSchema | | @bradleywilkerson/site/tracking | Tracking.astro | | @bradleywilkerson/site/images | Img.astro | | @bradleywilkerson/site/reviews | Reviews.astro | | @bradleywilkerson/site/forms | ContactForm.astro | | @bradleywilkerson/site/middleware | createAbMiddleware | | @bradleywilkerson/site/content | articlesCollection |

Installing in a client site

npm install @bradleywilkerson/site

Public on npm. No token, no .npmrc, nothing to configure in any build environment.

Behaviour worth knowing

Tracking ids that are blank emit nothing. A tag pointing at nothing looks installed in an audit while collecting nothing, which is worse than absent.

GA4 loads directly only when there is no GTM container. Loading both double-counts every pageview, and it is the most common tracking mistake on the sites we audit.

Meta Pixel and CallRail inject directly only when there is no container. With one, they belong inside it.

Form fields are defined per client, not hardcoded. Every trade asks something different, and the server stores the payload as jsonb, so adding a field is a template change with no backend work:

<ContactForm client={client} formId="quote" fields={[
  { name: "name", label: "Name", required: true, autocomplete: "name" },
  { name: "roof_type", label: "Roof type", type: "select", options: ["Asphalt shingle", "Metal", "Tile"] },
]} />

The contact form always shows a direct channel, not only on failure. Client lead capture must not depend on our uptime. For a local service business that channel is the phone, and the call is the primary conversion anyway; online-only clients with no phone fall back to the business email.

Online-only clients (businessType OnlineStore) may omit phone, address, geo, serviceArea and openingHours. The structured data omits what is absent rather than publishing empty facts, and services holds product names, emitted as a Product offer catalog. productSchema generates per-product markup.

The reviews component emits no AggregateRating. Google stopped showing rich-result stars for self-serving review markup in 2019. This block is for conversion; the ranking value is in getting reviews onto Google.

Releasing

Publishing does not push anything live. A client site only picks up a new version when that repo is rebuilt, so a rollout means triggering a deploy per client.

theabcagency.com consumes this package as client zero, so a breaking change lands on our own property before anyone's client.