create-shapio 0.3.0 → 0.4.0

package/templates/sveltekit/shapio/components/seo.json

@@ -0,0 +1,114 @@
+{
+  "apiKey": "seo",
+  "category": "Built-in",
+  "description": "Search and social metadata: title, description, image, canonical URL and indexing.",
+  "display": {
+    "titleFieldId": "3fe294a9-6af9-4019-8b32-43010822e45a"
+  },
+  "fields": [
+    {
+      "apiKey": "title",
+      "deprecated": false,
+      "editor": {
+        "id": "textInput",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "3fe294a9-6af9-4019-8b32-43010822e45a",
+      "label": "Title",
+      "localized": false,
+      "public": true,
+      "required": false,
+      "settings": {},
+      "sortable": false,
+      "type": "string",
+      "unique": false
+    },
+    {
+      "apiKey": "description",
+      "deprecated": false,
+      "editor": {
+        "id": "textarea",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "6d1917f3-94a2-4391-ba1f-a98d14577b93",
+      "label": "Description",
+      "localized": false,
+      "public": true,
+      "required": false,
+      "settings": {},
+      "sortable": false,
+      "type": "text",
+      "unique": false
+    },
+    {
+      "apiKey": "image",
+      "deprecated": false,
+      "editor": {
+        "id": "mediaPicker",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "d27c9354-4afc-4583-93b4-367214a7714a",
+      "label": "Social image",
+      "localized": false,
+      "public": true,
+      "required": false,
+      "settings": {
+        "allowedKinds": [
+          "image"
+        ],
+        "multiple": false
+      },
+      "sortable": false,
+      "type": "media",
+      "unique": false
+    },
+    {
+      "apiKey": "canonical",
+      "deprecated": false,
+      "editor": {
+        "id": "textInput",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "17b374b6-cd85-444e-8403-20c7458ed29e",
+      "label": "Canonical URL",
+      "localized": false,
+      "public": true,
+      "required": false,
+      "settings": {
+        "protocols": [
+          "https",
+          "http"
+        ]
+      },
+      "sortable": false,
+      "type": "url",
+      "unique": false
+    },
+    {
+      "apiKey": "noindex",
+      "deprecated": false,
+      "editor": {
+        "id": "toggle",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "e8346f99-dc3c-4b5c-906f-4854e03c9a57",
+      "label": "Hide from search engines",
+      "localized": false,
+      "public": true,
+      "required": false,
+      "settings": {},
+      "sortable": false,
+      "type": "boolean",
+      "unique": false
+    }
+  ],
+  "icon": "search",
+  "id": "f3905a00-d2a3-4c62-899a-c894bfd6cb9b",
+  "kind": "component",
+  "label": "SEO"
+}

package/templates/sveltekit/shapio/models/article.json

@@ -140,6 +140,27 @@
       "sortable": true,
       "type": "date",
       "unique": false
+    },
+    {
+      "apiKey": "seo",
+      "deprecated": false,
+      "editor": {
+        "id": "seoEditor",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "a3f1c0de-7b52-4e0a-9d1e-5c2b8e4f6a01",
+      "label": "SEO",
+      "localized": true,
+      "public": true,
+      "required": false,
+      "settings": {
+        "component": "f3905a00-d2a3-4c62-899a-c894bfd6cb9b",
+        "repeatable": false
+      },
+      "sortable": false,
+      "type": "component",
+      "unique": false
     }
   ],
   "id": "1679d89c-747f-4dfc-955f-7d47bd5e4f6b",

package/templates/sveltekit/shapio/models/page.json

@@ -83,6 +83,27 @@
       "sortable": false,
       "type": "dynamiczone",
       "unique": false
+    },
+    {
+      "apiKey": "seo",
+      "deprecated": false,
+      "editor": {
+        "id": "seoEditor",
+        "options": {}
+      },
+      "filterable": false,
+      "id": "b7e2d1af-3c64-4f1b-8e2a-6d3c9f5a7b02",
+      "label": "SEO",
+      "localized": true,
+      "public": true,
+      "required": false,
+      "settings": {
+        "component": "f3905a00-d2a3-4c62-899a-c894bfd6cb9b",
+        "repeatable": false
+      },
+      "sortable": false,
+      "type": "component",
+      "unique": false
     }
   ],
   "id": "4c09af05-f302-4d8f-ba03-bb838d3afbd2",

package/templates/sveltekit/src/env.ts

@@ -13,4 +13,5 @@ export const variables = defineEnvVars({
   SHAPIO_SNAPSHOT: { schema: optional },
   SHAPIO_SITE: { schema: optional },
   PUBLIC_SHAPIO_URL: { schema: optional },
+  SITE_URL: { schema: optional },
 });

package/templates/sveltekit/src/lib/components/Seo.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+  import type { DeliverySite, SeoResolved } from '@shapio/client';
+  import { page } from '$app/state';
+  import { seoHead, type SeoHead } from '../seo';
+  import { DEFAULT_LOCALE } from '../site';
+
+  /**
+   * The page's <head>: title, description, Open Graph, Twitter card, canonical and robots, from the entry's SEO
+   * fields (read with `seo=resolved`) over the site's SEO defaults. Pages without an entry pass their title only.
+   */
+  type Props = {
+    title: string;
+    seo?: SeoResolved | null;
+    type?: SeoHead['type'];
+    site: DeliverySite | null;
+    locale: string;
+    siteUrl: string | null;
+    noindex?: boolean;
+  };
+  let { title, seo = null, type = 'website', site, locale, siteUrl, noindex = false }: Props = $props();
+  const head = $derived(
+    seoHead({
+      seo,
+      site,
+      locale,
+      localeChain: [locale, DEFAULT_LOCALE],
+      title,
+      path: page.url.pathname,
+      siteUrl: siteUrl ?? undefined,
+      type,
+    }),
+  );
+</script>
+
+<svelte:head>
+  <title>{head.title}</title>
+  {#if head.description}
+    <meta name="description" content={head.description} />
+    <meta property="og:description" content={head.description} />
+    <meta name="twitter:description" content={head.description} />
+  {/if}
+  {#if noindex || head.noindex}
+    <meta name="robots" content="noindex" />
+  {/if}
+  {#if head.canonical}
+    <link rel="canonical" href={head.canonical} />
+    <meta property="og:url" content={head.canonical} />
+  {/if}
+  <meta property="og:type" content={head.type} />
+  <meta property="og:title" content={head.title} />
+  <meta property="og:locale" content={head.locale} />
+  {#if head.siteName}
+    <meta property="og:site_name" content={head.siteName} />
+  {/if}
+  {#if head.image}
+    <meta property="og:image" content={head.image.url} />
+    {#if head.image.width}
+      <meta property="og:image:width" content={String(head.image.width)} />
+    {/if}
+    {#if head.image.height}
+      <meta property="og:image:height" content={String(head.image.height)} />
+    {/if}
+    {#if head.image.alt}
+      <meta property="og:image:alt" content={head.image.alt} />
+    {/if}
+    <meta name="twitter:image" content={head.image.url} />
+  {/if}
+  <meta name="twitter:card" content={head.image ? 'summary_large_image' : 'summary'} />
+  {#if head.twitterHandle}
+    <meta name="twitter:site" content={head.twitterHandle} />
+  {/if}
+  <meta name="twitter:title" content={head.title} />
+</svelte:head>

package/templates/sveltekit/src/lib/preview.ts

@@ -45,6 +45,7 @@ export const loadDraft = async (shapioUrl: string, request: PreviewRequest): Pro
   const client = createClient({ baseUrl: shapioUrl, token: request.token });
   const params = new URLSearchParams({
     locale: request.locale,
+    richText: 'html',
     ...(request.modelKey === 'articles' ? { populate: 'author' } : {}),
   });
   const { data } = await client.request<DeliveryItem<Page | Article>>(

package/templates/sveltekit/src/lib/seo.ts

@@ -0,0 +1,69 @@
+import {
+  applyTitleTemplate,
+  seoDefaultsForLocale,
+  type DeliveryAsset,
+  type DeliverySite,
+  type SeoResolved,
+} from '@shapio/client';
+
+/**
+ * What a page puts in its <head> (title, description, Open Graph, Twitter card, canonical, robots), from an
+ * entry's SEO fields read with `?seo=resolved` and the site's SEO defaults (`GET /api/site`). Pages without an
+ * entry (listings, the colophon) pass their own title: it goes through the site's title template here.
+ */
+export type SeoHead = {
+  title: string;
+  description: string | null;
+  image: { url: string; width: number | null; height: number | null; alt: string | null } | null;
+  /** The entry's canonical URL, else this page's URL on SITE_URL; null when neither is known. */
+  canonical: string | null;
+  noindex: boolean;
+  siteName: string | null;
+  twitterHandle: string | null;
+  /** `article` for articles, `website` for everything else (`og:type`). */
+  type: 'website' | 'article';
+  /** `og:locale`, e.g. `en` or `fr`. */
+  locale: string;
+};
+
+export type SeoHeadInput = {
+  /** The entry's resolved SEO fields; absent on pages without an entry. */
+  seo?: SeoResolved | null;
+  /** The site and its defaults; null when it could not be read (the page still renders a title). */
+  site: DeliverySite | null;
+  locale: string;
+  /** The locales whose defaults apply, in order (the page's locale, then the default one). */
+  localeChain: readonly string[];
+  /** The page's own title (entry pages: used only when the entry has no SEO fields). */
+  title: string;
+  /** This page's path, e.g. `/en/articles/x/`; with `siteUrl` it makes the canonical URL. */
+  path: string;
+  siteUrl?: string | undefined;
+  type?: SeoHead['type'];
+};
+
+const imageOf = (asset: DeliveryAsset | null | undefined): SeoHead['image'] =>
+  asset ? { url: asset.url, width: asset.width, height: asset.height, alt: asset.alt } : null;
+
+const canonicalOf = (own: string | null | undefined, path: string, siteUrl: string | undefined) => {
+  if (own) {
+    return own;
+  }
+  return siteUrl ? new URL(path, siteUrl).href : null;
+};
+
+export const seoHead = (input: SeoHeadInput): SeoHead => {
+  const defaults = seoDefaultsForLocale(input.site?.seo ?? { locales: {} }, input.localeChain);
+  const { seo } = input;
+  return {
+    title: seo?.title ?? applyTitleTemplate(input.title, defaults.titleTemplate),
+    description: seo?.description ?? defaults.description ?? null,
+    image: imageOf(seo?.image ?? input.site?.seo.image),
+    canonical: canonicalOf(seo?.canonical, input.path, input.siteUrl),
+    noindex: seo?.noindex ?? false,
+    siteName: defaults.siteName ?? null,
+    twitterHandle: input.site?.seo.twitterHandle ?? null,
+    type: input.type ?? 'website',
+    locale: input.locale,
+  };
+};

package/templates/sveltekit/src/lib/server/config.ts

@@ -4,6 +4,7 @@ import {
   SHAPIO_SITE,
   SHAPIO_SNAPSHOT,
   SHAPIO_URL,
+  SITE_URL,
 } from '$app/env/private';
 
 /**
@@ -15,6 +16,8 @@ import {
  *   snapshot when prerendering starts, so every page shows the same moment.
  * - SHAPIO_SITE: optional; the site key on a multi-site Shapio (default: the token's site, else the primary).
  * - PUBLIC_SHAPIO_URL: the Shapio URL the browser calls for previews (defaults to SHAPIO_URL).
+ * - SITE_URL: optional; this site's public origin, e.g. https://www.example.com. Pages then carry a canonical
+ *   URL (and `og:url`) unless the entry sets its own.
  */
 export const shapioUrl = () => SHAPIO_URL ?? 'http://localhost:4300';
 
@@ -44,3 +47,5 @@ export const configuredSnapshot = (): number | undefined => {
   }
   return snapshot;
 };
+
+export const siteUrl = () => SITE_URL;

package/templates/sveltekit/src/lib/server/shapio.ts

@@ -1,4 +1,4 @@
-import { createClient, ShapioApiError, type DeliveryListQuery } from '@shapio/client';
+import { createClient, ShapioApiError, type DeliveryListQuery, type DeliverySite } from '@shapio/client';
 import type { Locale } from '../site';
 import type { Article, Page, SiteSettings } from '../types';
 import { configuredSnapshot, deliveryToken, shapioUrl, siteKey } from './config';
@@ -16,8 +16,8 @@ const ARTICLES = 'articles';
 const SITE_SETTINGS = 'siteSettings';
 
 /** The fields each read renders (`fields=`): smaller responses, and accurate field usage in Shapio. */
-const PAGE_FIELDS = ['title', 'slug', 'description', 'sections'];
-const ARTICLE_FIELDS = ['title', 'slug', 'excerpt', 'body', 'cover', 'author', 'publishedOn'];
+const PAGE_FIELDS = ['title', 'slug', 'description', 'sections', 'seo'];
+const ARTICLE_FIELDS = ['title', 'slug', 'excerpt', 'body', 'cover', 'author', 'publishedOn', 'seo'];
 const SITE_SETTINGS_FIELDS = ['siteName', 'tagline', 'footer', 'colophon'];
 
 const createShapio = () => createClient({ baseUrl: shapioUrl(), token: deliveryToken(), site: siteKey() });
@@ -48,6 +48,10 @@ const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T
   for (let page = 1; ; page += 1) {
     const result = await shapio().delivery.list<T>(routeKey, {
       ...query,
+      // The site renders the server's sanitized HTML, so it asks for that instead of the JSON document, and
+      // its SEO fields with the site's defaults filled in.
+      richText: 'html',
+      seo: 'resolved',
       snapshot: await snapshot(),
       page,
       pageSize: PAGE_SIZE,
@@ -82,6 +86,7 @@ const readSiteSettings = async (locale: Locale): Promise<SiteSettings | null> =>
       locale,
       snapshot: await snapshot(),
       fields: SITE_SETTINGS_FIELDS,
+      richText: 'html',
     });
     return data;
   } catch (error) {
@@ -91,3 +96,19 @@ const readSiteSettings = async (locale: Locale): Promise<SiteSettings | null> =>
     throw error;
   }
 };
+
+/**
+ * The site and its SEO defaults (name and title template per locale, default image, Twitter handle), once per
+ * build. Null when the Shapio predates them (the pages still render, with plain titles).
+ */
+export const getSite = (): Promise<DeliverySite | null> =>
+  once('site', async () => {
+    try {
+      return await shapio().site.get();
+    } catch (error) {
+      if (error instanceof ShapioApiError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  });

package/templates/sveltekit/src/lib/types.ts

@@ -1,3 +1,5 @@
+import type { SeoResolved } from '@shapio/client';
+
 /**
  * Content as the Shapio delivery API returns it for the starter's models (shapio/). Delivery
  * entries are flat: system attributes next to the fields, keyed by API key. Media fields are asset views,
@@ -24,6 +26,7 @@ export type Media = {
   variants: MediaVariant[];
 };
 
+/** Rich text as delivery returns it with `richText=html`: sanitized HTML rendered from the document. */
 export type RichText = { format: 'shapio-richtext'; version: number; html: string };
 
 type EntryBase = {
@@ -61,6 +64,8 @@ export type Page = EntryBase & {
   slug: string;
   description: string | null;
   sections: Section[];
+  /** The built-in SEO fields, read with `seo=resolved` (the site's defaults filled in). */
+  seo: SeoResolved;
 };
 
 export type Author = EntryBase & { name: string; bio: string | null; avatar: Media | null };
@@ -74,6 +79,8 @@ export type Article = EntryBase & {
   /** Populated (`populate=author`) or just the ID; null when the author is not published. */
   author: Author | string | null;
   publishedOn: string;
+  /** The built-in SEO fields, read with `seo=resolved` (the site's defaults filled in). */
+  seo: SeoResolved;
 };
 
 /** The `siteSettings` singleton: one entry per site, read by its API ID. */

package/templates/sveltekit/src/routes/[locale]/+layout.server.ts

@@ -1,9 +1,13 @@
 import { error } from '@sveltejs/kit';
-import { getSiteSettings } from '#lib/server/shapio.ts';
+import { siteUrl } from '#lib/server/config.ts';
+import { getSite, getSiteSettings } from '#lib/server/shapio.ts';
 import { isLocale, stringsFor } from '#lib/site.ts';
 import type { LayoutServerLoad } from './$types';
 
-/** The locale's site settings (the siteSettings singleton) and UI strings, for the header and footer. */
+/**
+ * The locale's site settings (the siteSettings singleton) and UI strings, for the header and footer; the site's
+ * SEO defaults and public URL, for every page's <head>.
+ */
 export const load: LayoutServerLoad = async ({ params }) => {
   if (!isLocale(params.locale)) {
     error(404, 'Not found');
@@ -12,5 +16,7 @@ export const load: LayoutServerLoad = async ({ params }) => {
     locale: params.locale,
     strings: stringsFor(params.locale),
     settings: await getSiteSettings(params.locale),
+    site: await getSite(),
+    siteUrl: siteUrl() ?? null,
   };
 };

package/templates/sveltekit/src/routes/[locale]/[...slug]/+page.svelte

@@ -1,15 +1,11 @@
 <script lang="ts">
+  import Seo from '#lib/components/Seo.svelte';
   import Sections from '#lib/components/Sections.svelte';
   import type { PageProps } from './$types';
 
   let { data }: PageProps = $props();
 </script>
 
-<svelte:head>
-  <title>{data.page.title} · {data.settings?.siteName ?? data.strings.siteName}</title>
-  {#if data.page.description}
-    <meta name="description" content={data.page.description} />
-  {/if}
-</svelte:head>
+<Seo title={data.page.title} seo={data.page.seo} site={data.site} locale={data.locale} siteUrl={data.siteUrl} />
 
 <Sections page={data.page} />

package/templates/sveltekit/src/routes/[locale]/articles/+page.svelte

@@ -1,13 +1,12 @@
 <script lang="ts">
+  import Seo from '#lib/components/Seo.svelte';
   import ArticleCard from '#lib/components/ArticleCard.svelte';
   import type { PageProps } from './$types';
 
   let { data }: PageProps = $props();
 </script>
 
-<svelte:head>
-  <title>{data.strings.articles} · {data.settings?.siteName ?? data.strings.siteName}</title>
-</svelte:head>
+<Seo title={data.strings.articles} site={data.site} locale={data.locale} siteUrl={data.siteUrl} />
 
 <h1 class="page-title">{data.strings.articles}</h1>
 <ul class="cards">

package/templates/sveltekit/src/routes/[locale]/articles/[slug]/+page.svelte

@@ -1,15 +1,11 @@
 <script lang="ts">
+  import Seo from '#lib/components/Seo.svelte';
   import ArticleView from '#lib/components/ArticleView.svelte';
   import type { PageProps } from './$types';
 
   let { data }: PageProps = $props();
 </script>
 
-<svelte:head>
-  <title>{data.article.title} · {data.settings?.siteName ?? data.strings.siteName}</title>
-  {#if data.article.excerpt}
-    <meta name="description" content={data.article.excerpt} />
-  {/if}
-</svelte:head>
+<Seo title={data.article.title} seo={data.article.seo} type="article" site={data.site} locale={data.locale} siteUrl={data.siteUrl} />
 
 <ArticleView article={data.article} locale={data.locale} strings={data.strings} />

package/templates/sveltekit/src/routes/[locale]/colophon/+page.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import Seo from '#lib/components/Seo.svelte';
   import RichText from '#lib/components/RichText.svelte';
   import type { PageProps } from './$types';
 
@@ -6,9 +7,7 @@
   let { data }: PageProps = $props();
 </script>
 
-<svelte:head>
-  <title>{data.strings.colophon} · {data.settings?.siteName ?? data.strings.siteName}</title>
-</svelte:head>
+<Seo title={data.strings.colophon} site={data.site} locale={data.locale} siteUrl={data.siteUrl} />
 
 <h1 class="page-title">{data.strings.colophon}</h1>
 {#if data.settings?.tagline}