@ampless/plugin-seo 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @ampless/plugin-seo
+
+SEO plugin for [ampless](https://github.com/heavymoons/ampless). Generates per-post and per-site metadata (Open Graph, Twitter card, canonical) and keeps a `sitemap.xml` regenerated to S3 whenever the post set changes.
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+## Install
+
+```bash
+npm install @ampless/plugin-seo@alpha
+```
+
+## Configure
+
+In `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import seoPlugin from '@ampless/plugin-seo'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    seoPlugin({
+      // defaultOgImage: 'https://example.com/og-default.png',
+      // twitterSite: '@example',
+      // twitterCreator: '@author',
+      // twitterCard: 'summary_large_image',
+    }),
+  ],
+})
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `defaultOgImage` | none | Falls through to `og:image` and `twitter:image` for every post when set |
+| `twitterSite` | none | `@handle` of the site |
+| `twitterCreator` | none | `@handle` of the post author |
+| `twitterCard` | `'summary_large_image'` | Card style |
+| `siteUrl` | `site.url` | Override base URL (e.g. for staging) |
+| `priority` / `changefreq` / `limit` | (sitemap defaults) | Sitemap entry tuning |
+
+## What it produces
+
+- **Per-post metadata** (Next.js `generateMetadata` shape): `title`, `description`, `alternates.canonical`, `openGraph` (article type, url, images), `twitter` (card, handles, images)
+- **Site-level metadata**: defaults for the root layout — title, description, og:website
+- **`/sitemap.xml`** — full URL set, regenerated to `s3://<bucket>/public/plugins/seo/sitemap.xml` on every `content.published` / `content.unpublished` / `content.deleted` / `content.updated` event. Served by the template's `/sitemap.xml` route handler.
+
+## Trust level
+
+`trusted` — the sitemap regeneration runs in the trusted Lambda processor with read access to the post table and write access under `public/plugins/seo/` in the site's S3 bucket. The metadata helpers (`metadata` / `siteMetadata`) are pure functions that run during Next.js SSR and do not need any AWS access.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Post, Config, PluginMetadata, AmplessPlugin } from 'ampless';
+
+interface SitemapOptions {
+    /** Maximum number of URLs to include. Default 5000. */
+    limit?: number;
+    /** Override base URL (defaults to config.site.url). */
+    siteUrl?: string;
+    /** Default changefreq for post URLs. */
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    /** Default priority (0..1) for post URLs. */
+    priority?: number;
+}
+declare function buildSitemap(posts: Post[], site: Config['site'], options?: SitemapOptions): string;
+
+interface SeoMetadataOptions {
+    /** Default OGP image URL when a post has no image override. */
+    defaultOgImage?: string;
+    /** Twitter site handle, e.g. "@example". */
+    twitterSite?: string;
+    /** Twitter creator handle, e.g. "@author". */
+    twitterCreator?: string;
+    /** OGP card type for post pages. Default 'summary_large_image'. */
+    twitterCard?: 'summary' | 'summary_large_image';
+}
+declare function buildPostMetadata(post: Post, site: Config['site'], options?: SeoMetadataOptions): PluginMetadata;
+declare function buildSiteMetadata(site: Config['site'], options?: SeoMetadataOptions): PluginMetadata;
+
+interface SeoPluginOptions extends SitemapOptions, SeoMetadataOptions {
+}
+/**
+ * SEO plugin: regenerates `sitemap.xml` whenever a post's published state
+ * changes, and provides Next.js `generateMetadata`-compatible per-post and
+ * per-site metadata (title, description, OGP, Twitter card, canonical).
+ *
+ * Lambda side stores the sitemap at
+ * `s3://{bucket}/public/plugins/seo/sitemap.xml`. The Next.js
+ * `/sitemap.xml` route streams that object through.
+ */
+declare function seoPlugin(options?: SeoPluginOptions): AmplessPlugin;
+
+export { type SeoMetadataOptions, type SeoPluginOptions, type SitemapOptions, buildPostMetadata, buildSiteMetadata, buildSitemap, seoPlugin as default };

package/dist/index.js

@@ -0,0 +1,120 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+
+// src/sitemap.ts
+import { escapeXml } from "ampless";
+var toIsoDate = (iso) => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? "" : d.toISOString();
+};
+function buildSitemap(posts, site, options = {}) {
+  const baseUrl = (options.siteUrl ?? site.url).replace(/\/$/, "");
+  const limit = options.limit ?? 5e3;
+  const changefreq = options.changefreq ?? "weekly";
+  const priority = options.priority ?? 0.7;
+  const homeEntry = `  <url>
+    <loc>${escapeXml(baseUrl + "/")}</loc>
+    <changefreq>daily</changefreq>
+    <priority>1.0</priority>
+  </url>`;
+  const postEntries = posts.filter((p) => p.status === "published").slice(0, limit).map((post) => {
+    const url = `${baseUrl}/${post.slug}`;
+    const lastmod = post.publishedAt ? toIsoDate(post.publishedAt) : "";
+    const lastmodTag = lastmod ? `
+    <lastmod>${lastmod}</lastmod>` : "";
+    return `  <url>
+    <loc>${escapeXml(url)}</loc>${lastmodTag}
+    <changefreq>${changefreq}</changefreq>
+    <priority>${priority}</priority>
+  </url>`;
+  }).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${homeEntry}
+${postEntries}
+</urlset>
+`;
+}
+
+// src/metadata.ts
+function buildPostMetadata(post, site, options = {}) {
+  const baseUrl = site.url.replace(/\/$/, "");
+  const url = `${baseUrl}/${post.slug}`;
+  const description = post.excerpt ?? site.description ?? "";
+  const ogImage = options.defaultOgImage;
+  return {
+    title: post.title,
+    description,
+    openGraph: {
+      title: post.title,
+      description,
+      type: "article",
+      url,
+      ...ogImage && { images: [{ url: ogImage }] }
+    },
+    twitter: {
+      card: options.twitterCard ?? "summary_large_image",
+      title: post.title,
+      description,
+      ...options.twitterSite && { site: options.twitterSite },
+      ...options.twitterCreator && { creator: options.twitterCreator },
+      ...ogImage && { images: [ogImage] }
+    },
+    alternates: { canonical: url }
+  };
+}
+function buildSiteMetadata(site, options = {}) {
+  const description = site.description ?? site.name;
+  return {
+    title: site.name,
+    description,
+    openGraph: {
+      title: site.name,
+      description,
+      type: "website",
+      url: site.url,
+      ...options.defaultOgImage && { images: [{ url: options.defaultOgImage }] }
+    },
+    twitter: {
+      card: "summary",
+      title: site.name,
+      description,
+      ...options.twitterSite && { site: options.twitterSite }
+    }
+  };
+}
+
+// src/index.ts
+function seoPlugin(options = {}) {
+  async function rebuild(_event, ctx) {
+    const posts = await ctx.listPublishedPosts();
+    const xml = buildSitemap(posts, ctx.site, options);
+    await ctx.writePublicAsset("sitemap.xml", xml, "application/xml; charset=utf-8");
+  }
+  return definePlugin({
+    name: "seo",
+    apiVersion: 1,
+    trust_level: "trusted",
+    hooks: {
+      "content.published": rebuild,
+      "content.unpublished": rebuild,
+      "content.deleted": rebuild,
+      // Updates can change title/slug of an already-published post, so we
+      // regenerate on every update too. listPublishedPosts() filters
+      // drafts, so an update on a draft just produces the same XML.
+      "content.updated": rebuild
+    },
+    metadata(post, site) {
+      return buildPostMetadata(post, site, options);
+    },
+    siteMetadata(site) {
+      return buildSiteMetadata(site, options);
+    }
+  });
+}
+export {
+  buildPostMetadata,
+  buildSiteMetadata,
+  buildSitemap,
+  seoPlugin as default
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ampless/plugin-seo",
+  "version": "0.2.0-alpha.0",
+  "description": "SEO plugin for ampless",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-seo"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "0.2.0-alpha.0"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "seo"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}