@foundrykit/seo-plugin 0.0.0-stage → 0.3.0
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.
- package/README.md +270 -2
- package/dist/components/JsonLdEditor.d.ts +2 -0
- package/dist/components/JsonLdEditor.js +1184 -0
- package/dist/components/JsonLdEditor.js.map +1 -0
- package/dist/components/JsonLdTemplateRowLabel.d.ts +2 -0
- package/dist/components/JsonLdTemplateRowLabel.js +12 -0
- package/dist/components/JsonLdTemplateRowLabel.js.map +1 -0
- package/dist/components/MetaDescriptionComponent.d.ts +8 -0
- package/dist/components/MetaDescriptionComponent.js +101 -0
- package/dist/components/MetaDescriptionComponent.js.map +1 -0
- package/dist/components/MetaTitleComponent.d.ts +9 -0
- package/dist/components/MetaTitleComponent.js +193 -0
- package/dist/components/MetaTitleComponent.js.map +1 -0
- package/dist/components/OverviewComponent.d.ts +8 -0
- package/dist/components/OverviewComponent.js +64 -0
- package/dist/components/OverviewComponent.js.map +1 -0
- package/dist/components/PreviewComponent.d.ts +8 -0
- package/dist/components/PreviewComponent.js +51 -0
- package/dist/components/PreviewComponent.js.map +1 -0
- package/dist/exports/client.d.ts +6 -0
- package/dist/exports/client.js +8 -0
- package/dist/exports/client.js.map +1 -0
- package/dist/exports/next.d.ts +2 -0
- package/dist/exports/next.js +3 -0
- package/dist/exports/next.js.map +1 -0
- package/dist/exports/rsc.d.ts +1 -0
- package/dist/exports/rsc.js +5 -0
- package/dist/exports/rsc.js.map +1 -0
- package/dist/fields.d.ts +67 -0
- package/dist/fields.js +220 -0
- package/dist/fields.js.map +1 -0
- package/dist/global.d.ts +6 -0
- package/dist/global.js +93 -0
- package/dist/global.js.map +1 -0
- package/dist/helpers.d.ts +44 -0
- package/dist/helpers.js +23 -0
- package/dist/helpers.js.map +1 -0
- package/dist/helpers.test.d.ts +1 -0
- package/dist/helpers.test.js +234 -0
- package/dist/helpers.test.js.map +1 -0
- package/dist/hooks/autoAlternates.d.ts +18 -0
- package/dist/hooks/autoAlternates.js +63 -0
- package/dist/hooks/autoAlternates.js.map +1 -0
- package/dist/hooks/autoAlternates.test.d.ts +1 -0
- package/dist/hooks/autoAlternates.test.js +225 -0
- package/dist/hooks/autoAlternates.test.js.map +1 -0
- package/dist/hooks/generateMeta.d.ts +17 -0
- package/dist/hooks/generateMeta.js +58 -0
- package/dist/hooks/generateMeta.js.map +1 -0
- package/dist/hooks/generateMeta.test.d.ts +1 -0
- package/dist/hooks/generateMeta.test.js +132 -0
- package/dist/hooks/generateMeta.test.js.map +1 -0
- package/dist/hooks/ogImageGenerator.d.ts +19 -0
- package/dist/hooks/ogImageGenerator.js +96 -0
- package/dist/hooks/ogImageGenerator.js.map +1 -0
- package/dist/index.d.ts +87 -0
- package/dist/index.js +269 -0
- package/dist/index.js.map +1 -0
- package/dist/jsonld.d.ts +83 -0
- package/dist/jsonld.js +179 -0
- package/dist/jsonld.js.map +1 -0
- package/dist/jsonld.test.d.ts +1 -0
- package/dist/jsonld.test.js +214 -0
- package/dist/jsonld.test.js.map +1 -0
- package/dist/metadata.d.ts +53 -0
- package/dist/metadata.js +114 -0
- package/dist/metadata.js.map +1 -0
- package/dist/metadata.test.d.ts +1 -0
- package/dist/metadata.test.js +286 -0
- package/dist/metadata.test.js.map +1 -0
- package/package.json +100 -3
package/README.md
CHANGED
|
@@ -1,3 +1,271 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @foundrykit/seo-plugin
|
|
2
2
|
|
|
3
|
-
|
|
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
|