docs: README
- options (cms alias of public.seo.enabled, breadcrumbs, links.newTabHint, rootFiles, resolveFiles), the new runtime keys and the moved purge keys - the resolve and site answer contract, one JSON-LD graph, root files, the purge route, 404 report, labels and tokens, the smoke runs
This commit is contained in:
Jakub Zych
82
README.md
82
README.md
@@ -1,6 +1,12 @@
|
||||
# vue-seo-layer
|
||||
|
||||
The Nuxt half of the SummerCMS SEO plugin ([sm-seo-plugin](https://git.golem15.com/golem15/sm-seo-plugin), plugin ID `golem15.seo`). For every page it asks the plugin for the redirect decision and the effective SEO, enforces the decision, and sets the head from the answer. It also reports 404s to the plugin's 404 log and serves the verification files at the site root.
|
||||
The Nuxt half of the SummerCMS SEO plugin ([sm-seo-plugin](https://git.golem15.com/golem15/sm-seo-plugin), plugin ID `golem15.seo`). For every page it asks the plugin for the redirect decision and the effective SEO, enforces the decision, and sets the head from the answer, including hreflang and one JSON-LD `@graph`. It also serves the site's root files from the backend (verification files, and with SEO v0.2.0 robots.txt, the sitemaps, llms.txt and the IndexNow key), reports 404s to the plugin's 404 log, and owns the shared site cache purge route.
|
||||
|
||||
## Install
|
||||
|
||||
```json
|
||||
"vue-seo-layer": "git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.2.0"
|
||||
```
|
||||
|
||||
```ts
|
||||
// nuxt.config.ts of the app
|
||||
@@ -9,48 +15,86 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
```json
|
||||
"vue-seo-layer": "git+https://git.golem15.com/golem15/vue-seo-layer.git#v0.1.1"
|
||||
```
|
||||
Pin a tag; the features marked "v0.2.0" below need that tag and, where they read new answer keys, the SEO plugin's v0.2.0 backend. With an older backend the layer behaves as v0.1.1.
|
||||
|
||||
The layer declares no Nuxt modules and works next to `@nuxtjs/seo`, the Journal layer or an app's own `useSeoMeta`.
|
||||
The layer's only module is its own local one (`lib/seo-module.ts`); it pulls in no package and no `@nuxtjs/i18n`. It works next to `@nuxtjs/seo`, the Journal layer or an app's own `useSeoMeta`; its options share the `seo` config key with nuxt-seo-utils and use none of its names.
|
||||
|
||||
## What it does
|
||||
|
||||
- **Resolve.** A global route middleware calls `GET <apiBase>/resolve?url=<path and query>` before the page runs, on the server for the first request and in the browser on each client-side navigation (the server's answer travels in the payload, so hydration fetches nothing). Nuxt's own paths (`/_…`, `/api/…`) are never resolved. A call that fails, times out (`timeoutMs`) or answers anything unexpected is ignored: the page renders with its own head.
|
||||
- **Redirects.** `redirect` answers 301 or 302 with `Location`. A target on the site's own origin (the origin of the answer's `url`) becomes a path, so a staging or preview host keeps the visitor even when the backend's site URL names production; a target on another host stays absolute. The redirect wins over the route, so an old address no page matches still redirects.
|
||||
- **Resolve.** Every page request is resolved with `GET <apiBase>/resolve?url=<path and query>` before Nuxt renders it, in a Nitro middleware, so the render uses the same answer and makes no second call. Answers are cached (v0.2.0): path and query as the key, `seo.resolveCacheTtl` seconds (default 60), at most 1000 entries, and concurrent requests for one path share one call; the site cache purge empties the cache. In the browser a global route middleware resolves each client-side navigation with the public base (the server's answer travels in the payload, so hydration fetches nothing). Nuxt's own paths (`/_…`, `/api/…`) and asset files are never resolved by the middleware (files with an extension in `resolveFiles`, default `pdf`, are, so an old PDF address can redirect); the route middleware still resolves a page under a dotted path. A call that fails, times out (`timeoutMs`) or answers anything unexpected is ignored: the page renders with its own head (fail open).
|
||||
- **Redirects.** `redirect` answers 301 or 302 with `Location`, before the page and before Nitro's route cache, so a redirect added for an `swr`-cached page applies on the next request after the resolve cache entry expires or the site cache is purged. A target on the site's own origin (the origin of the answer's `url`) becomes a path, so a staging or preview host keeps the visitor even when the backend's site URL names production; a target on another host stays absolute. Nothing from the request (Host, X-Forwarded-Host, path, query) goes into the Location. The redirect wins over the route, so an old address no page matches still redirects.
|
||||
- **410.** `gone` answers 410 with the app's error page, also on a route that would render.
|
||||
- **Head.** An `ok` answer sets the title (final; the plugin applies its templates, so the app's `titleTemplate` is replaced by `%s`), `description`, `canonical`, `robots`, `og:title`, `og:description`, `og:image`, `og:url`, `twitter:card`, `twitter:site` and the verification meta tags. The entry has `tagPriority: 'critical'`, so its tags win over the same tags set by a page, a layer or a module; a value the answer leaves empty adds no tag, and the page's own stays. A canonical, `og:url` or `og:image` the plugin answers as a path (a backend without `golem15.seo.site_url` or `app.url`) is made absolute on the request's origin; set the site URL on the backend so it names the public origin. `not_found` answers (pages the plugin does not know: listings, search, author pages, static pages without a URL rule) leave the head to the page.
|
||||
- **Robots and staging.** A `staging` answer (the backend outside `SUMMER_ENV=production`) makes every page `noindex, nofollow`, known or not. The `X-Robots-Tag` response header follows the same value.
|
||||
- **404 log.** Each page view answered 404 (a GET that accepts `text/html`, from an unknown route or a page that throws a 404) is reported with `POST <apiBase>/notfound`, `{"url", "referer"}` and `Authorization: Bearer <notfoundToken>`, after the response. Without a token nothing is reported.
|
||||
- **Verification files.** A request for a single-segment `.html`, `.txt` or `.xml` file (`/google0123.html`, `/BingSiteAuth.xml`) is looked up under `GET <apiBase>/verification/<name>` and served with `X-Content-Type-Options: nosniff`, a sandboxing CSP and `X-Robots-Tag: noindex` when the plugin has it; otherwise it falls through to the app's routes. `robots.txt`, `sitemap.xml`, `sitemap.xsl`, `rss.xml`, `feed.xml`, `atom.xml` and `llms.txt` are never looked up.
|
||||
- **404 for a bad page number (v0.2.0).** A `not_found` answer with `pagination.invalid` (`?page=abc`) is a 404. Every other `not_found` is left to Nuxt's routing and the pages.
|
||||
- **Head.** An `ok` answer sets the title (final; the plugin applies its templates, so the app's `titleTemplate` is replaced by `%s`), `description`, `canonical`, `robots`, `og:title`, `og:description`, `og:image`, `og:url`, `twitter:card`, `twitter:site` and the verification meta tags, and from v0.2.0 answers `<html lang>` (`html_lang`), `og:locale`, one `og:locale:alternate` per value, one `<link rel="alternate" hreflang>` per entry of `alternates`, and exactly one `<script type="application/ld+json">` holding one `@graph`. The entry has `tagPriority: 'critical'`, so its tags win over the same tags set by a page, a layer or a module; a value the answer leaves empty adds no tag, and the page's own stays. A canonical, `og:url`, `og:image` or alternate URL the plugin answers as a path (a backend without `golem15.seo.site_url` or `app.url`) is made absolute on the request's origin; set the site URL on the backend so it names the public origin. `not_found` answers leave the head to the page. One app plugin (`seo-head`, through `useCmsSeo`) applies the head on every route; pages and other layers do not set CMS values themselves.
|
||||
- **One JSON-LD graph (v0.2.0).** The graph holds the CMS nodes (the answer's `jsonld`) plus the nodes pages and layers add with `useSchemaNode(node)`, merged by `@id`: a node whose `@id` the CMS already has fills in only the keys the CMS node lacks; a new `@id` (or none) is appended. No node at all, no script. unhead escapes `<` inside the JSON, so a value cannot end the script element.
|
||||
- **Robots and staging.** A `staging` answer (the backend outside `SUMMER_ENV=production`) makes every page `noindex, nofollow`, known or not. The `X-Robots-Tag` response header follows the same value, or the page's `x_robots_tag`; a redirect carries none.
|
||||
- **404 log.** Each page view answered 404 (a GET that accepts `text/html`, from an unknown route or a page that throws a 404) is reported once with `POST <apiBase>/notfound`, `{"url", "referer"}` and `Authorization: Bearer <notfoundToken>`, after the response, so it never delays it. Without a token nothing is reported.
|
||||
- **Root files.** With a backend that answers `GET <apiBase>/site` (v0.2.0), `/robots.txt`, `/sitemap.xml`, `/llms.txt` and `/sitemap-<name>.xml` (served from the backend's `/_sitemap/files/`) are proxied to `backendBase`, and so is each one-segment `.html`, `.txt` or `.xml` file the site answer lists in `root_files`: a verification file (`<apiBase>/verification/<name>`) or the IndexNow key file (`/_sitemap/indexnow/<key>.txt`). The backend's status, content type and `X-Robots-Tag` are passed on, with `X-Content-Type-Options: nosniff`; a backend that does not answer or answers 5xx gives 503 with `Retry-After: 60`, so crawlers retry instead of reading a missing robots.txt as "everything allowed". Any other path passes through to the app. The site answer is cached for 300 seconds and cleared by the purge. With a backend whose `/site` answers 404 (before v0.2.0, or no SEO plugin), robots.txt and the sitemaps are not proxied (route them to the backend in the site's proxy) and verification files keep the v0.1.1 lookup: a request for a single-segment `.html`, `.txt` or `.xml` file (`/google0123.html`, `/BingSiteAuth.xml`) is looked up under `GET <apiBase>/verification/<name>` and served with `X-Content-Type-Options: nosniff`, a sandboxing CSP and `X-Robots-Tag: noindex` when the plugin has it; otherwise it falls through to the app's routes. `robots.txt`, `sitemap.xml`, `sitemap.xsl`, `rss.xml`, `feed.xml`, `atom.xml` and `llms.txt` are never looked up that way. `rootFiles: false` turns both off.
|
||||
- **Site cache purge (v0.2.0).** `POST /api/__site__/cache/purge` (moved here from vue-journal-layer, vue-menu-layer and vue-faq-layer, same contract) removes every Nitro route-cache entry and empties the layer's resolve and site caches, so an admin save shows on the next page view. The backend calls it on loopback after the save commits, with `Authorization: Bearer <cachePurge.token>` and `{"kind","slug"}`; the answer is `{"purged": <n>}`. It answers 404 without a token of at least 32 characters and for any proxied request (X-Forwarded-For, X-Real-IP or Forwarded) unless `cachePurge.allowProxied` is true, and 401 for a missing or wrong bearer. `/api/__site__/**` is never route-cached. While another layer still ships its own copy of the route and that copy answers, `server/plugins/seo-cache-purge.ts` empties the SEO caches after any 200 purge (also after the journal's deprecated `/api/__journal__/cache/purge`).
|
||||
- **Visitor address.** The server calls forward the visitor's `X-Forwarded-For` plus the address of the peer that reached Nuxt, also on route-cached (`swr`) renders, so the plugin's per-IP throttles (`seo-resolve`, `seo-notfound`, 600 a minute) keep one bucket per visitor. List the Nuxt server's address in the backend's `http.trusted_proxies`.
|
||||
|
||||
## Options
|
||||
|
||||
Module options under the `seo` key of the app's `nuxt.config.ts` (v0.2.0). They are copied to `runtimeConfig.public.seo`, so each can also be set at run time (`NUXT_PUBLIC_SEO_<NAME>`).
|
||||
|
||||
| Option | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `cms` | `true` | `false` turns every CMS call off (no resolve, no head from the CMS, no redirects, no root files, no 404 reports), for a site without the SEO plugin. An alias of `public.seo.enabled`, which keeps working: either one `false` switches the layer off. |
|
||||
| `breadcrumbs` | `true` | Breadcrumbs from the CMS (`breadcrumbs` of the answer). |
|
||||
| `links.newTabHint` | `true` | A visually hidden "(opens in a new tab)" inside external links while the CMS's `links_new_tab` is on; copied to `runtimeConfig.public.seo.links.newTabHint` for the body-link rules. |
|
||||
| `rootFiles` | `true` | Serve robots.txt, the sitemaps, llms.txt and the root files from the backend (see Root files). |
|
||||
| `resolveFiles` | `['pdf']` | File extensions the Nitro middleware still resolves. |
|
||||
|
||||
## Configuration
|
||||
|
||||
| Runtime config | Env | Default | Meaning |
|
||||
|---|---|---|---|
|
||||
| `seo.apiBase` | `NUXT_SEO_API_BASE` | `http://127.0.0.1:8096/_seo/api/v1` | Server-only base of the plugin's API for SSR calls and 404 reports. |
|
||||
| `seo.apiBase` | `NUXT_SEO_API_BASE` | `http://127.0.0.1:8096/_seo/api/v1` | Server-only base of the plugin's API for SSR calls, the site answer, verification files and 404 reports. |
|
||||
| `seo.backendBase` | `NUXT_SEO_BACKEND_BASE` | `""` | Server-only origin of the Go binary for robots.txt, llms.txt and the sitemap and IndexNow files (v0.2.0). Empty: `apiBase` without `/_seo/api/v1`. |
|
||||
| `seo.notfoundToken` | `NUXT_SEO_NOTFOUND_TOKEN` | `""` | The backend's `golem15.seo.notfound_token`. Empty: 404s are not reported. Server-only; not under `NUXT_SITE_*`, which nuxt-site-config publishes in every page's payload. |
|
||||
| `seo.routeReportToken` | `NUXT_SEO_ROUTE_REPORT_TOKEN` | `""` | Bearer token of the route report to the plugin's page registry (v0.2.0). Empty: `notfoundToken`. |
|
||||
| `seo.timeoutMs` | `NUXT_SEO_TIMEOUT_MS` | `1500` | How long a call may take before the page renders without it. |
|
||||
| `public.seo.apiBase` | `NUXT_PUBLIC_SEO_API_BASE` | `/_seo/api/v1` | Same-origin base for client-side navigations. The site's proxy must route `GET <base>/resolve` to the backend. |
|
||||
| `public.seo.enabled` | `NUXT_PUBLIC_SEO_ENABLED` | `true` | `false` turns the layer off: no calls, no head, no redirects, no reports. |
|
||||
| `seo.resolveCacheTtl` | `NUXT_SEO_RESOLVE_CACHE_TTL` | `60` | Seconds a resolve answer stays cached (v0.2.0). `0` turns the cache off; concurrent requests for one path still share one call. |
|
||||
| `cachePurge.token` | `NUXT_CACHE_PURGE_TOKEN` | `""` | Bearer token of the site cache purge route, the backend's `site_cache.purge_token`. Shorter than 32 characters: the route answers 404. |
|
||||
| `cachePurge.allowProxied` | `NUXT_CACHE_PURGE_ALLOW_PROXIED` | `false` | `true` when the backend reaches the site through a TLS-terminating proxy; the bearer token is then the only gate. |
|
||||
| `siteCache.purgeToken`, `siteCache.allowProxied` | `NUXT_SITE_CACHE_PURGE_TOKEN`, `NUXT_SITE_CACHE_ALLOW_PROXIED` | | Deprecated names of the two above, read when the new ones are unset; the layer strips them from nuxt-site-config's site config and logs one warning. Rotate a token that was ever set under the old name. |
|
||||
| `public.seo.apiBase` | `NUXT_PUBLIC_SEO_API_BASE` | `/_seo/api/v1` | Same-origin base for client-side navigations. The site's proxy must route `GET <base>/resolve` to the backend. Set it to `/api/__seo__` to resolve through the Nuxt server (`GET /api/__seo__/resolve?url=`, the server's cache, no proxy rule needed). |
|
||||
| `public.seo.enabled` | `NUXT_PUBLIC_SEO_ENABLED` | `true` | `false` turns the layer off: no calls, no head, no redirects, no root files, no reports. Same as the option `cms: false`. |
|
||||
|
||||
The plugin serves `/robots.txt` itself; route that path to the backend (and turn off another robots.txt route, such as the one of `@nuxtjs/robots`).
|
||||
## Resolve answer
|
||||
|
||||
The layer reads the answer of `GET /_seo/api/v1/resolve` (`app/utils/types.ts`): `action` (`ok`, `not_found`, `redirect`, `gone`), `status`, `location`, `url`, `locale`, `staging`, and on `ok` answers `seo` with `title`, `description`, `canonical`, `robots`, `x_robots_tag`, `og` (`title`, `description`, `image`, `url`, and from v0.2.0 `locale`, `locale_alternates`), `twitter` (`card`, `site`) and `verification` (`[{name, content}]`). SEO plugin v0.2.0 adds `html_lang`, `alternates` (`[{hreflang, url}]`, absolute, the page itself and `x-default` included), `jsonld` (one `{"@context", "@graph"}` object or null), `breadcrumbs` (`[{name, url, path}]`), `pagination` (`{form, param, segment, page, invalid}`, only when the request carries a page), `outbound`, `autolinks` and `autolink_max`. Absent keys are treated as empty. The site answer (`GET /_seo/api/v1/site`) carries `site_url`, `default_locale`, `locales`, `unprefixed_locale`, `links.new_tab`, `html_sitemap`, `routes`, `root_files`, `llms`, `pagination` and `home_crumb`.
|
||||
|
||||
## Composables and utils
|
||||
|
||||
- `useSeoAnswer()`: the resolve answer of the current page (`SeoResolveAnswer | null`), shared state.
|
||||
- `resolveSeo(url)`: one resolve call with the server or public base; `null` on any failure.
|
||||
- `resolveSeo(url)`: one resolve call with the server or public base; `null` on any failure. During SSR it takes the answer the Nitro middleware resolved for the request.
|
||||
- `useCmsSeo(answer)`: the head from an answer ref (the layer's plugin calls it; apps do not).
|
||||
- `useSchemaNode(node)`: adds a schema.org node (an object, a ref or a getter) to the page's one `@graph` for as long as the calling component lives (v0.2.0).
|
||||
- `useSeoLabels()`: the label dictionary of the page's content locale (v0.2.0, see Labels and tokens).
|
||||
- `mergeGraph(cmsJsonld, nodes)`, `isPagePath(path, resolveFiles)`, `pickLabels(locale, htmlLang, overrides)`, `formatSeoLabel(template, values)`, `seoEnabled(publicSeo)`: pure helpers (v0.2.0).
|
||||
- `seoHeadInput`, `seoAbsolute`, `seoRedirectTarget`, `seoRobots`, `seoXRobotsTag`, `seoResolvableUrl`, `seoAnswer`, `seoVerificationName`: the pure helpers behind them (`app/utils/seo.ts`), auto-imported.
|
||||
|
||||
## Labels and tokens
|
||||
|
||||
`useSeoLabels()` returns the strings of the layer's public components in the page's content locale: the answer's `locale`, then the primary subtag of `html_lang`, then `en`. The layer ships `en` and `pl` (`app/utils/labels.ts`); an app overrides keys or adds a locale in its `app.config.ts`, and component props override both:
|
||||
|
||||
```ts
|
||||
export default defineAppConfig({
|
||||
seo: { labels: { pl: { sitemap: { title: 'Spis stron' } }, de: { pagination: { next: 'Nächste Seite' } } } },
|
||||
})
|
||||
```
|
||||
|
||||
`app/assets/css/seo-tokens.css` defines the tokens (`--seo-space-1` to `--seo-space-5`, `--seo-target-size`, `--seo-sitemap-column-width`, `--seo-color-muted`, `--seo-color-accent`, `--seo-color-on-accent`, `--seo-color-border`, `--seo-font-size-small`, `--seo-breadcrumbs-separator`) and `seo-base.css` the base styles, which target only `.seo-*` classes (`.seo-visually-hidden` and the focus ring of layer links). Both load before the app's CSS; override a token on `:root:root` in the app's own CSS.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm test # node --test on the helpers
|
||||
pnpm test # node --test on the helpers, the cache, the purge and the labels
|
||||
pnpm build:playground
|
||||
pnpm smoke:ssr # the playground against testing/fixture-api.mjs and testing/expect.txt
|
||||
pnpm smoke:ssr # the playground against testing/fixture-api.mjs, six runs
|
||||
pnpm purge:check # testing/purge-check.mjs and purge-token-check.mjs
|
||||
```
|
||||
|
||||
`testing/fixture-api.mjs` stands in for the plugin's public API (resolve answers from `testing/fixtures/resolve.json`, the 404 report with `FIXTURE_NOTFOUND_TOKEN`, verification files from `testing/fixtures/verification/`). `testing/smoke-ssr.mjs` checks status, body, content type and headers (`header=Name: text`) per line, and `report PATH` lines require a 404 report for `PATH`.
|
||||
`testing/fixture-api.mjs` stands in for the plugin's public API and the Go binary's root files: resolve answers from `testing/fixtures/seo/resolve.json` and `testing/fixtures/resolve.json`, the site answer from `testing/fixtures/seo/site.json`, the 404 report with `FIXTURE_NOTFOUND_TOKEN`, verification files, root files and the IndexNow key under `testing/fixtures/seo/`. `testing/smoke-ssr.mjs` checks status, body, content type and headers per line (`contains=`, `notcontains=`, `count=TEXT:N`, `type=`, `header=Name: value`, `noheader=`, `reqheader=`, each repeatable), `report` and `noreport` lines for the 404 reports, and `resolves PATH N` and `apicalls N` lines for the calls the API saw; `--no-site` makes the API answer `/site` with 404, as an older backend does. `pnpm smoke:ssr` runs `testing/expect.txt` (the v0.1.1 behaviour, against a backend without `/site`), `testing/expect-seo.txt`, `testing/expect-seo-off.txt` (with `NUXT_PUBLIC_SEO_CMS=false` and with `NUXT_PUBLIC_SEO_ENABLED=false`), `testing/expect-seo-down.txt` (the backend unreachable) and `testing/expect-seo-notoken.txt`. `testing/purge-check.mjs` proves on the route-cached playground (`/blog/**` swr) that a purge shows a changed CMS answer at once and that the route refuses unauthenticated, wrong-token and proxied requests; `testing/purge-token-check.mjs` that the purge token never reaches a page or the log.
|
||||
|
||||
Reference in New Issue
Block a user