@foundrykit/seo-plugin 0.0.0-stage → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +270 -2
  2. package/dist/components/JsonLdEditor.d.ts +2 -0
  3. package/dist/components/JsonLdEditor.js +1184 -0
  4. package/dist/components/JsonLdEditor.js.map +1 -0
  5. package/dist/components/JsonLdTemplateRowLabel.d.ts +2 -0
  6. package/dist/components/JsonLdTemplateRowLabel.js +12 -0
  7. package/dist/components/JsonLdTemplateRowLabel.js.map +1 -0
  8. package/dist/components/MetaDescriptionComponent.d.ts +8 -0
  9. package/dist/components/MetaDescriptionComponent.js +101 -0
  10. package/dist/components/MetaDescriptionComponent.js.map +1 -0
  11. package/dist/components/MetaTitleComponent.d.ts +9 -0
  12. package/dist/components/MetaTitleComponent.js +193 -0
  13. package/dist/components/MetaTitleComponent.js.map +1 -0
  14. package/dist/components/OverviewComponent.d.ts +8 -0
  15. package/dist/components/OverviewComponent.js +64 -0
  16. package/dist/components/OverviewComponent.js.map +1 -0
  17. package/dist/components/PreviewComponent.d.ts +8 -0
  18. package/dist/components/PreviewComponent.js +51 -0
  19. package/dist/components/PreviewComponent.js.map +1 -0
  20. package/dist/exports/client.d.ts +6 -0
  21. package/dist/exports/client.js +8 -0
  22. package/dist/exports/client.js.map +1 -0
  23. package/dist/exports/next.d.ts +2 -0
  24. package/dist/exports/next.js +3 -0
  25. package/dist/exports/next.js.map +1 -0
  26. package/dist/exports/rsc.d.ts +1 -0
  27. package/dist/exports/rsc.js +5 -0
  28. package/dist/exports/rsc.js.map +1 -0
  29. package/dist/fields.d.ts +67 -0
  30. package/dist/fields.js +220 -0
  31. package/dist/fields.js.map +1 -0
  32. package/dist/global.d.ts +6 -0
  33. package/dist/global.js +93 -0
  34. package/dist/global.js.map +1 -0
  35. package/dist/helpers.d.ts +44 -0
  36. package/dist/helpers.js +23 -0
  37. package/dist/helpers.js.map +1 -0
  38. package/dist/helpers.test.d.ts +1 -0
  39. package/dist/helpers.test.js +234 -0
  40. package/dist/helpers.test.js.map +1 -0
  41. package/dist/hooks/autoAlternates.d.ts +18 -0
  42. package/dist/hooks/autoAlternates.js +63 -0
  43. package/dist/hooks/autoAlternates.js.map +1 -0
  44. package/dist/hooks/autoAlternates.test.d.ts +1 -0
  45. package/dist/hooks/autoAlternates.test.js +225 -0
  46. package/dist/hooks/autoAlternates.test.js.map +1 -0
  47. package/dist/hooks/generateMeta.d.ts +17 -0
  48. package/dist/hooks/generateMeta.js +58 -0
  49. package/dist/hooks/generateMeta.js.map +1 -0
  50. package/dist/hooks/generateMeta.test.d.ts +1 -0
  51. package/dist/hooks/generateMeta.test.js +132 -0
  52. package/dist/hooks/generateMeta.test.js.map +1 -0
  53. package/dist/hooks/ogImageGenerator.d.ts +19 -0
  54. package/dist/hooks/ogImageGenerator.js +96 -0
  55. package/dist/hooks/ogImageGenerator.js.map +1 -0
  56. package/dist/index.d.ts +87 -0
  57. package/dist/index.js +269 -0
  58. package/dist/index.js.map +1 -0
  59. package/dist/jsonld.d.ts +83 -0
  60. package/dist/jsonld.js +179 -0
  61. package/dist/jsonld.js.map +1 -0
  62. package/dist/jsonld.test.d.ts +1 -0
  63. package/dist/jsonld.test.js +214 -0
  64. package/dist/jsonld.test.js.map +1 -0
  65. package/dist/metadata.d.ts +53 -0
  66. package/dist/metadata.js +114 -0
  67. package/dist/metadata.js.map +1 -0
  68. package/dist/metadata.test.d.ts +1 -0
  69. package/dist/metadata.test.js +286 -0
  70. package/dist/metadata.test.js.map +1 -0
  71. package/package.json +99 -3
package/README.md CHANGED
@@ -1,3 +1,271 @@
1
- # Temporary Holding Version
1
+ # @foundrykit/seo-plugin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A comprehensive SEO plugin for [Payload CMS](https://payloadcms.com) v3. It injects a `meta` sidebar group into configured collections, registers a `global-seo` global for site defaults, and exports composable utilities for title/URL generation, hreflang alternates, OG image generation, and JSON-LD structured data.
4
+
5
+ This README documents the plugin features and shows how to use them in common scenarios (Payload config, Next.js App Router, and small helper examples).
6
+
7
+ ## What this plugin provides
8
+
9
+ - Meta sidebar group (per-document)
10
+ - `meta.title`, `meta.url` (canonical), `meta.image`, `meta.description`, `meta.noindex`, `meta.nofollow`, `meta.alternates` (hreflang), `meta.jsonLd`
11
+ - `global-seo` Global for site defaults and toggles
12
+ - Auto-generation hooks
13
+ - `generateTitle` and `generateURL` (run on save / beforeChange)
14
+ - `generateAlternateURL` (run on read to auto-fill hreflang alternates)
15
+ - `generateOgImage` (run on change/publish to create an OG image when missing)
16
+ - Helpers and builders
17
+ - `resolveMeta` — resolve final title/description/image/url/robots/alternates/jsonLd
18
+ - `toNextMetadata` — build Next.js `Metadata` objects from docs/globals
19
+ - JSON-LD builders: `webPageJsonLd`, `articleJsonLd`, `productJsonLd`, `organizationJsonLd`, `breadcrumbJsonLd`, `buildJsonLd`
20
+ - Field factories / UI components: overview, SERP preview, upload field, alternates, etc.
21
+ - Fully typed (TypeScript) exports for config and return values
22
+
23
+ ## Installation
24
+
25
+ ```bash
26
+ pnpm add @foundrykit/seo-plugin
27
+ # or
28
+ npm install @foundrykit/seo-plugin
29
+ ```
30
+
31
+ ## Quick start (Payload config)
32
+
33
+ Add the plugin to your `payload.config.ts` and enable it for the collections you want to enhance.
34
+
35
+ ```ts
36
+ // payload.config.ts
37
+ import { buildConfig } from 'payload';
38
+ import { seoPlugin } from '@foundrykit/seo-plugin';
39
+
40
+ export default buildConfig({
41
+ plugins: [
42
+ seoPlugin({
43
+ collections: { posts: true, pages: true },
44
+ // optional generators shown below
45
+ }),
46
+ ],
47
+ });
48
+ ```
49
+
50
+ After registering the plugin you will see a new `SEO` (meta) group in the admin sidebar for each configured collection. Editors can set values manually or rely on the auto-generation hooks.
51
+
52
+ ## Plugin options and usage
53
+
54
+ All options are exported typesafe. The most-used options are shown below with examples.
55
+
56
+ - `collections: Partial<Record<CollectionSlug, true>>` — which collections receive the meta group
57
+ - `disabled?: boolean` — set to `true` to disable behaviour while preserving schema
58
+ - `locales?: string[]` — BCP47 locale codes used by `generateAlternateURL`
59
+ - `mediaCollection?: string[]` — media collection slug(s) used by the image picker (default `['media']`)
60
+
61
+ Hook generators (each may return the expected value or `null` to skip):
62
+
63
+ - `generateTitle(args) => string | null | Promise<string | null>`
64
+ - Runs on `beforeChange` when `meta.title` is empty. Use to apply site title templates.
65
+
66
+ Example:
67
+
68
+ ```ts
69
+ seoPlugin({
70
+ collections: { posts: true },
71
+ generateTitle: ({ data }) => `${data.title} | My Site`,
72
+ });
73
+ ```
74
+
75
+ - `generateURL(args) => string | null | Promise<string | null>`
76
+ - Runs on `beforeChange` when `meta.url` is empty. Useful for canonical URL construction.
77
+
78
+ Example:
79
+
80
+ ```ts
81
+ seoPlugin({
82
+ collections: { posts: true },
83
+ generateURL: ({ data }) => `https://example.com/blog/${data.slug}`,
84
+ });
85
+ ```
86
+
87
+ - `generateAlternateURL({ collectionSlug, doc, locale }) => string | null | Promise<string | null>`
88
+ - Runs on `afterRead` once per configured locale when the `global-seo` global has `autoGenerateAlternates` enabled and the doc has no manual alternates entered.
89
+ - Return `null` to skip creating an alternate for a specific locale.
90
+
91
+ Example:
92
+
93
+ ```ts
94
+ seoPlugin({
95
+ collections: { posts: true },
96
+ locales: ['en', 'fr', 'de'],
97
+ generateAlternateURL: ({ doc, locale }) =>
98
+ `https://example.com/${locale}/blog/${doc.slug}`,
99
+ });
100
+ ```
101
+
102
+ - `generateOgImage({ collectionSlug, doc }) => Buffer | null | Promise<Buffer | null>`
103
+ - Runs on `afterChange` only when the document has no `meta.image` and the `global-seo` global has `enableOgGenerator` enabled.
104
+ - Return a PNG/JPEG buffer; the plugin saves it to the configured media collection and writes the media id back to `meta.image`.
105
+
106
+ Example using a hypothetical renderer:
107
+
108
+ ```ts
109
+ seoPlugin({
110
+ collections: { posts: true },
111
+ generateOgImage: async ({ doc }) => {
112
+ // renderOgImageBuffer should return a Buffer (PNG/JPEG)
113
+ return await renderOgImageBuffer({ title: doc.meta?.title ?? doc.title });
114
+ },
115
+ });
116
+ ```
117
+
118
+ Notes:
119
+
120
+ - Generators only run when a field is empty — manual editor input always wins.
121
+ - `generateTitle` and `generateURL` run in parallel on `beforeChange`.
122
+
123
+ ## Global SEO (admin global)
124
+
125
+ The plugin registers a `global-seo` global. Open **Admin → Globals → Global SEO** to configure:
126
+
127
+ - Site name and Twitter handle
128
+ - Default title, description, and default image
129
+ - Site-wide `robots` directive (e.g. `noindex, nofollow`) — used when per-doc checkboxes are not set
130
+ - `autoGenerateAlternates` toggle — enables `generateAlternateURL` behaviour
131
+ - `enableOgGenerator` toggle — enables `generateOgImage` behaviour
132
+ - JSON-LD templates you can reference from code
133
+
134
+ Use `payload.findGlobal({ slug: 'global-seo' })` to read global values in server code.
135
+
136
+ ## Helpers
137
+
138
+ - `resolveMeta(doc, { globals? })`
139
+ - Returns resolved values: `{ title, description, image, url, noindex, nofollow, alternates, jsonLd }`.
140
+ - Resolution order (highest → lowest):
141
+ - `title`: `meta.title` → `globals.defaultTitle` → `doc.title` → `''`
142
+ - `description`: `meta.description` → `globals.defaultDescription` → `doc.description` → `''`
143
+ - `image`: `meta.image` → `globals.defaultImage` → `null` (always returned as URL or `null`)
144
+ - `url`: `meta.url` → `''`
145
+ - `noindex` / `nofollow`: `meta.{noindex,nofollow}` → `false` (global `robots` used only when neither checkbox is set)
146
+ - `alternates`: `meta.alternates` (auto-generated alternates merged by `afterRead`)
147
+ - `jsonLd`: `meta.jsonLd` → `null`
148
+
149
+ Example:
150
+
151
+ ```ts
152
+ import { resolveMeta } from '@foundrykit/seo-plugin';
153
+
154
+ const globals = await payload.findGlobal({ slug: 'global-seo' });
155
+ const resolved = resolveMeta(doc, { globals });
156
+ // resolved.title, resolved.image, resolved.alternates, etc.
157
+ ```
158
+
159
+ - `toNextMetadata(doc, globals?, options?)`
160
+ - Build a Next.js `Metadata` object for the App Router. Recommended for pages in `app/`.
161
+
162
+ Example (app router):
163
+
164
+ ```ts
165
+ import { toNextMetadata } from '@foundrykit/seo-plugin/next';
166
+
167
+ export async function generateMetadata({ params }) {
168
+ const doc = await payload.findByID({ collection: 'posts', id: params.id });
169
+ const globals = await payload.findGlobal({ slug: 'global-seo' });
170
+ return toNextMetadata(doc, globals, { openGraphType: 'article' });
171
+ }
172
+ ```
173
+
174
+ What `toNextMetadata` sets for you: `title`, `description`, `robots`, `alternates.canonical`, `alternates.languages`, `openGraph`, and `twitter` with sensible defaults.
175
+
176
+ ## JSON-LD builders
177
+
178
+ Tree-shakeable builders help create structured data objects you can inject into the page head.
179
+
180
+ ```ts
181
+ import {
182
+ webPageJsonLd,
183
+ articleJsonLd,
184
+ productJsonLd,
185
+ organizationJsonLd,
186
+ breadcrumbJsonLd,
187
+ buildJsonLd,
188
+ } from '@foundrykit/seo-plugin';
189
+ ```
190
+
191
+ Examples:
192
+
193
+ ```ts
194
+ const pageLd = webPageJsonLd({
195
+ name: 'Home',
196
+ url: 'https://example.com',
197
+ description: 'Welcome',
198
+ });
199
+
200
+ const articleLd = articleJsonLd({
201
+ headline: 'My article',
202
+ url: 'https://example.com/article',
203
+ author: { name: 'Jane Smith' },
204
+ publisher: { name: 'Acme', logo: 'https://example.com/logo.png' },
205
+ datePublished: '2024-01-01',
206
+ });
207
+
208
+ const merged = buildJsonLd(articleLd, { headline: 'Overridden headline' });
209
+ ```
210
+
211
+ `buildJsonLd(base, overrides)` merges values while preserving `@context` and `@type` from the base template.
212
+
213
+ ## Field factories & admin UI components
214
+
215
+ All UI pieces are exported so you can compose custom admin layouts instead of using the default meta group.
216
+
217
+ ```ts
218
+ import {
219
+ OverviewField,
220
+ MetaTitleField,
221
+ MetaUrlField,
222
+ MetaImageField,
223
+ MetaDescriptionField,
224
+ MetaNoindexField,
225
+ MetaNofollowField,
226
+ AlternatesField,
227
+ PreviewField,
228
+ structuredDataRow,
229
+ } from '@foundrykit/seo-plugin';
230
+ ```
231
+
232
+ Common elements:
233
+
234
+ - `OverviewField` — character counts and warnings (title ≤ 60, description ≤ 160)
235
+ - `PreviewField` — Google SERP-style preview
236
+ - `AlternatesField` — array of `{ locale, url }`
237
+ - `structuredDataRow` — JSON editor for `meta.jsonLd`
238
+
239
+ You can import these and include them in your own collection fields if you prefer a customized layout.
240
+
241
+ ## Examples and edge cases
242
+
243
+ - Manual values always win. Generators only populate when the meta field is empty.
244
+ - Auto alternates run only when `global-seo.autoGenerateAlternates` is true and no manual alternates exist.
245
+ - OG generation runs only when `global-seo.enableOgGenerator` is true and `meta.image` is empty. The plugin writes the created media ID back to `meta.image`.
246
+
247
+ ## Development
248
+
249
+ To develop locally (the repo contains a dev Payload app under `dev/`):
250
+
251
+ ```bash
252
+ # Start the dev MongoDB
253
+ pnpm dev:db:up
254
+
255
+ # Start the dev server (Next.js + Payload dev app)
256
+ pnpm dev
257
+
258
+ # Run tests
259
+ pnpm test:int
260
+
261
+ # Build the plugin
262
+ pnpm build
263
+ ```
264
+
265
+ ## Contributing
266
+
267
+ If you plan to extend generators or add new JSON-LD templates, follow the existing naming and typing conventions and add unit tests for the generator hooks.
268
+
269
+ ## License
270
+
271
+ MIT
@@ -0,0 +1,2 @@
1
+ import type { JSONFieldClientComponent } from 'payload';
2
+ export declare const JsonLdEditorComponent: JSONFieldClientComponent;