@the-smithy/create-hearth-site 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,7 +29,7 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.15.0"
+    "@the-smithy/hearth-schema": "^0.16.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts"

package/template/README.md

@@ -67,8 +67,14 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
   - Headings can mark words with `*asterisks*` to highlight them (see `Emphasis` in `src/components/ui.tsx`).
   - To leave a block type out, delete its line in `src/components/blocks/index.tsx` and ask for it to be turned
     off for the site in Hearth.
-- **SEO is already handled.** Page titles, descriptions, canonical URLs, share images and structured data all
-  come from Hearth's SEO settings. There's nothing to wire up per page.
+- **SEO comes from Hearth.** Titles, descriptions, canonical addresses, share images, structured data, the
+  sitemap, robots.txt, redirects for old addresses, Search Console verification and the page's language all come
+  from Hearth (`siteMetadata`, `generatePageMetadata`, `sitemapWith`, `robots`, `redirectOrNotFound`). Preview deploys
+  and sites hidden in Hearth are kept out of search engines. What's still yours:
+  - Pages your own code serves (like `/events`) need their own `generateMetadata` and a place in `src/app/sitemap.ts`.
+  - Use `<Img priority>` for the image at the top of a page, and keep one `<h1>` per page (the Hero block renders it).
+  - Add both the bare domain and `www` to the site in Netlify, with the one Hearth uses as primary: Netlify then
+    redirects the other to it.
 
 ### Where things live
 

package/template/src/app/[[...slug]]/page.tsx

@@ -2,7 +2,6 @@ import { normalizeSlug } from "@the-smithy/hearth";
 import { metadataFromMeta } from "@the-smithy/hearth/next";
 import { JsonLd } from "@the-smithy/hearth/react";
 import type { Metadata } from "next";
-import { notFound } from "next/navigation";
 import { Blocks } from "@/components/blocks";
 import { EventView } from "@/components/EventView";
 import { hearthNext } from "@/lib/hearth";
@@ -42,7 +41,8 @@ export default async function Page({ params }: Props) {
 
   const event = await collectionEvent(slug);
   if (event) return <EventView event={event} />;
-  notFound();
+  // An old address (a renamed page, or the site before it moved to Hearth) redirects; anything else is a 404.
+  return hearthNext.redirectOrNotFound(slug);
 }
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {

package/template/src/app/apple-icon.tsx

@@ -0,0 +1,31 @@
+import { ImageResponse } from "next/og";
+import { hearthNext } from "@/lib/hearth";
+
+export const size = { width: 180, height: 180 };
+export const contentType = "image/png";
+
+/** The home-screen icon on iPhones and iPads: like icon.tsx, larger. Replace with apple-icon.png when there's a real one. */
+export default async function AppleIcon() {
+  const site = await hearthNext.getSite();
+  const seo = site.settings.seo;
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          background: seo.ogBackground ?? "#141413",
+          color: seo.ogAccent ?? seo.ogText ?? "#FFFFFF",
+          fontSize: 110,
+          fontWeight: 700,
+        }}
+      >
+        {site.name.trim().charAt(0).toUpperCase() || "•"}
+      </div>
+    ),
+    size,
+  );
+}

package/template/src/app/donate/page.tsx

@@ -5,7 +5,15 @@ import { Section } from "@/components/ui";
 import { hearthNext } from "@/lib/hearth";
 import { hasFeature } from "@/lib/site";
 
-export const metadata: Metadata = { title: "Donate", alternates: { canonical: "/donate" } };
+export async function generateMetadata(): Promise<Metadata> {
+  const site = await hearthNext.getSite();
+  return {
+    title: "Donate",
+    description: `Support ${site.name} with a donation.`,
+    alternates: { canonical: "/donate" },
+    openGraph: { title: "Donate", url: "/donate" },
+  };
+}
 
 /**
  * A general donation page (sites with Giving). Ask staff to reserve "donate" on the site's Plan card in Hearth so

package/template/src/app/events/[slug]/page.tsx

@@ -1,5 +1,5 @@
 import { metadataFromMeta } from "@the-smithy/hearth/next";
-import { notFound, permanentRedirect } from "next/navigation";
+import { permanentRedirect } from "next/navigation";
 import { EventView } from "@/components/EventView";
 import { hearthNext } from "@/lib/hearth";
 import { hasFeature } from "@/lib/site";
@@ -18,8 +18,9 @@ export async function generateMetadata({ params }: Props) {
 
 /** Events without a type live here. Events in a collection (e.g. Talks) live at their collection's address. */
 export default async function EventPage({ params }: Props) {
-  const event = await load((await params).slug);
-  if (!event) notFound();
+  const slug = (await params).slug;
+  const event = await load(slug);
+  if (!event) return hearthNext.redirectOrNotFound(`/events/${slug}`);
   if (event.path !== `/events/${event.slug}`) permanentRedirect(event.path);
   return <EventView event={event} />;
 }

package/template/src/app/events/page.tsx

@@ -5,7 +5,15 @@ import { Section } from "@/components/ui";
 import { hearthNext } from "@/lib/hearth";
 import { hasFeature } from "@/lib/site";
 
-export const metadata: Metadata = { title: "Events", alternates: { canonical: "/events" } };
+export async function generateMetadata(): Promise<Metadata> {
+  const site = await hearthNext.getSite();
+  return {
+    title: "Events",
+    description: `Upcoming events from ${site.name}.`,
+    alternates: { canonical: "/events" },
+    openGraph: { title: "Events", url: "/events" },
+  };
+}
 
 /** Upcoming events (only on sites with the Events feature in Hearth). */
 export default async function EventsPage() {

package/template/src/app/fundraisers/[slug]/page.tsx

@@ -1,6 +1,5 @@
 import { metadataFromMeta } from "@the-smithy/hearth/next";
 import { JsonLd } from "@the-smithy/hearth/react";
-import { notFound } from "next/navigation";
 import { Blocks } from "@/components/blocks";
 import { Progress } from "@/components/blocks/giving";
 import { DonateForm } from "@/components/DonateForm";
@@ -22,8 +21,9 @@ export async function generateMetadata({ params }: Props) {
 
 /** A fundraiser's page: progress and a donation form, then its story blocks. */
 export default async function FundraiserPage({ params }: Props) {
-  const loaded = await load((await params).slug);
-  if (!loaded?.fundraiser) notFound();
+  const slug = (await params).slug;
+  const loaded = await load(slug);
+  if (!loaded?.fundraiser) return hearthNext.redirectOrNotFound(`/fundraisers/${slug}`);
   const { site, fundraiser: f } = loaded;
   const giving = site.settings.giving;
 

package/template/src/app/fundraisers/page.tsx

@@ -5,7 +5,15 @@ import { Section } from "@/components/ui";
 import { hearthNext } from "@/lib/hearth";
 import { hasFeature } from "@/lib/site";
 
-export const metadata: Metadata = { title: "Fundraisers", alternates: { canonical: "/fundraisers" } };
+export async function generateMetadata(): Promise<Metadata> {
+  const site = await hearthNext.getSite();
+  return {
+    title: "Fundraisers",
+    description: `Fundraisers and campaigns from ${site.name}: see how each is doing and give.`,
+    alternates: { canonical: "/fundraisers" },
+    openGraph: { title: "Fundraisers", url: "/fundraisers" },
+  };
+}
 
 /** Active fundraisers, then completed ones (only on sites with the Giving feature in Hearth). */
 export default async function FundraisersPage() {

package/template/src/app/icon.tsx

@@ -0,0 +1,35 @@
+import { ImageResponse } from "next/og";
+import { hearthNext } from "@/lib/hearth";
+
+export const size = { width: 64, height: 64 };
+export const contentType = "image/png";
+
+/**
+ * The browser tab icon: the site's first letter in its share-image colors from Hearth. Replace this file with an
+ * icon.png (or favicon.ico) once the client has a proper one.
+ */
+export default async function Icon() {
+  const site = await hearthNext.getSite();
+  const seo = site.settings.seo;
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          borderRadius: 14,
+          background: seo.ogBackground ?? "#141413",
+          color: seo.ogAccent ?? seo.ogText ?? "#FFFFFF",
+          fontSize: 40,
+          fontWeight: 700,
+        }}
+      >
+        {site.name.trim().charAt(0).toUpperCase() || "•"}
+      </div>
+    ),
+    size,
+  );
+}

package/template/src/app/layout.tsx

@@ -1,27 +1,22 @@
-import type { Metadata } from "next";
 import type { ReactNode } from "react";
+import { siteLang } from "@the-smithy/hearth/next";
 import { HearthPreview } from "@the-smithy/hearth/preview";
 import { SiteFooter } from "@/components/SiteFooter";
 import { SiteHeader } from "@/components/SiteHeader";
 import { hearthNext } from "@/lib/hearth";
-import { siteUrl } from "@/lib/site";
 import "./globals.css";
 
-export async function generateMetadata(): Promise<Metadata> {
-  const site = await hearthNext.getSite();
-  const base = siteUrl(site);
-  return {
-    // Pages set their own full title, description, canonical and share image from Hearth.
-    title: { default: site.name, template: site.settings.seo.titleTemplate ?? `%s | ${site.name}` },
-    description: site.settings.seo.description,
-    ...(base ? { metadataBase: new URL(base) } : {}),
-  };
-}
+/**
+ * What every page starts from: full links, the title pattern, the default description and share image, the site's
+ * language, Google and Bing verification, and no indexing on preview deploys or while the site is hidden in Hearth.
+ * Pages from Hearth then set their own title, description, canonical address and share image.
+ */
+export const generateMetadata = () => hearthNext.siteMetadata();
 
 export default async function RootLayout({ children }: { children: ReactNode }) {
   const site = await hearthNext.getSite();
   return (
-    <html lang="en">
+    <html lang={siteLang(site)}>
       <body className="flex min-h-dvh flex-col">
         <a href="#main" className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-50 focus:rounded focus:bg-surface focus:px-4 focus:py-2">
           Skip to content

package/template/src/app/robots.ts

@@ -1,10 +1,7 @@
-import type { MetadataRoute } from "next";
 import { hearthNext } from "@/lib/hearth";
-import { siteUrl } from "@/lib/site";
 
-export default async function robots(): Promise<MetadataRoute.Robots> {
-  const base = siteUrl(await hearthNext.getSite());
-  // Until the site's domain is set in Hearth (e.g. on a preview URL), keep search engines out.
-  if (!base) return { rules: { userAgent: "*", disallow: "/" } };
-  return { rules: { userAgent: "*", allow: "/", disallow: "/api/" }, sitemap: `${base}/sitemap.xml` };
-}
+/**
+ * Keeps crawlers out until the site has a domain in Hearth, while it's hidden from search engines there, and on
+ * preview deploys; otherwise allows everything and points at the sitemap.
+ */
+export default hearthNext.robots;

package/template/src/app/sitemap.ts

@@ -1,4 +1,9 @@
 import { hearthNext } from "@/lib/hearth";
+import { hasFeature } from "@/lib/site";
 
-/** Every indexable page and event, as listed by Hearth. */
-export default hearthNext.sitemap;
+/** Every indexable page, event and fundraiser in Hearth, plus the pages this site's own code serves. */
+export default async function sitemap() {
+  const site = await hearthNext.getSite();
+  const own = [...(hasFeature(site, "events") ? ["/events"] : []), ...(hasFeature(site, "giving") ? ["/fundraisers", "/donate"] : [])];
+  return hearthNext.sitemapWith(own)();
+}

package/template/src/components/blocks/content.tsx

@@ -5,9 +5,9 @@ export function Hero({ block }: { block: BlockOf<"hero"> }) {
   const d = block.data;
   return (
     <section className="relative overflow-hidden bg-inverse text-inverse-ink">
-      {d.image ? <Img image={d.image} className="absolute inset-0 size-full object-cover opacity-35" /> : null}
+      {d.image ? <Img image={d.image} priority className="absolute inset-0 size-full object-cover opacity-35" /> : null}
       <div className={`relative mx-auto max-w-site px-4 sm:px-6 ${d.size === "full" ? "py-28 sm:py-36" : "py-16 sm:py-20"}`}>
-        {d.logo ? <Img image={d.logo} className="mb-6 h-20 w-auto sm:h-24" /> : null}
+        {d.logo ? <Img image={d.logo} priority className="mb-6 h-20 w-auto sm:h-24" /> : null}
         {d.eyebrow ? <p className="mb-4 text-sm font-semibold uppercase tracking-[0.18em] opacity-80">{d.eyebrow}</p> : null}
         <h1 className="max-w-4xl text-[clamp(36px,5vw,64px)] font-bold leading-[1.05] tracking-tight">
           <Emphasis text={d.heading} className="underline decoration-2 underline-offset-[6px]" />

package/template/src/components/ui.tsx

@@ -99,7 +99,30 @@ export function Button({ link, variant = "primary", dark }: { link?: LinkRef; va
   );
 }
 
+/**
+ * An image from Hearth. Its width and height (from Hearth's media library) reserve its space, so the page doesn't jump
+ * as it loads. `priority` loads it first: use it for the image at the top of the page (the hero), which is usually
+ * the largest thing on screen; everything else loads as it scrolls into view.
+ */
 /* eslint-disable @next/next/no-img-element -- Hearth serves media from its CDN at the uploaded size */
-export function Img({ image, className = "" }: { image: { src: string; alt: string }; className?: string }) {
-  return <img src={image.src} alt={image.alt} loading="lazy" decoding="async" className={className} />;
+export function Img({
+  image,
+  className = "",
+  priority = false,
+}: {
+  image: { src: string; alt: string; width?: number; height?: number };
+  className?: string;
+  priority?: boolean;
+}) {
+  return (
+    <img
+      src={image.src}
+      alt={image.alt}
+      {...(image.width && image.height ? { width: image.width, height: image.height } : {})}
+      loading={priority ? "eager" : "lazy"}
+      fetchPriority={priority ? "high" : "auto"}
+      decoding={priority ? "sync" : "async"}
+      className={className}
+    />
+  );
 }