Statamic Peak Seo Laravel Package

Getting Started

This package is not a self-contained SEO addon in the way statamic/seo-pro is. It is a fieldset + partial bundle extracted from the Peak starter kit: YAML field definitions you attach to your blueprints, and Antlers partials that render the resulting meta tags. Treat it as a reference implementation you adopt, not a black box you configure.

Minimal path in:

1. composer require studio1902/statamic-peak-seo
2. Open the repo and read resources/fieldsets/ first — that is the actual contract. You will find fields for title, meta description, canonical/redirect behaviour, Open Graph image, and JSON-LD/schema toggles.
3. Attach the fieldset to a collection blueprint (Pages, usually) via the blueprint editor under Fields → Import fieldset, or by referencing it in YAML.
4. Render the matching partial inside <head> in your layout. If the views are not auto-registered, publish or copy them into resources/views/ in your site — see Gotchas.

First use case to validate end-to-end: a single Page entry. Fill the SEO tab, view source, confirm <title>, <meta name="description">, canonical, and OG tags appear. If they do not, the fieldset handle and the partial's variable expectations are misaligned — that mismatch is the single most common failure with this package.

Implementation Patterns

Compose, don't duplicate. The intended workflow is to include the SEO fieldset in every blueprint that renders a public page, then let a single shared partial in your layout handle output. One partial, many collections. Duplicating render logic per template is the anti-pattern this package exists to prevent.

Site-wide fallbacks. Peak-style setups typically resolve SEO values in a cascade: entry field → parent page → global/site defaults (set in a Globals set or config/statamic/ site config). Wire your Antlers with fallback chains (seo_title ?? title ?? site:name). The package supplies fields, not cascade logic — you own that resolution order, so write it down before you have five collections behaving differently.

Override-by-copy is the extension point. Because these are plain partials, the sustainable pattern is to copy the shipped partial into your own resources/views/partials/ and edit there. Never edit inside vendor/ — composer update will silently revert you. If the package supports view publishing (php artisan vendor:publish), prefer that; otherwise document the copy in your README so the next developer knows.

Pair with sitemap and robots. This package handles per-page meta, not the XML sitemap or robots.txt. Expect to enable Statamic's sitemap separately. The redirect/canonical fields here only take effect if your routing layer actually honours them — a canonical field that nothing reads is a trap.

Blueprint-first change management. Since SEO fields live in YAML, changes are diffable and reviewable. Commit blueprint changes alongside template changes so a field rename and the partial consuming it land in the same PR. This is the main day-to-day discipline the package rewards.

Structured data. JSON-LD in these bundles is usually a per-entry toggle plus a type selector. Model it as a small enum of supported types rather than a free-text field, or you will get invalid schema in production with no validation anywhere in the pipeline.

Gotchas and Tips

• It is fieldsets and partials, not an engine. No automatic meta generation, no validation, no sitemap, no automatic OG image resizing. If you expect statamic/seo-pro behaviour, you will be disappointed. Score the adoption decision accordingly.
• Peak coupling. The package is designed to sit inside the Peak starter kit's conventions (file layout, global sets, Tailwind-driven templates). Outside Peak you will likely spend the first hour deleting or rewiring assumptions about where globals live.
• View registration is the usual install failure. If partials "don't exist" after install, the service provider may not be loading views from the package path. Check vendor/studio1902/statamic-peak-seo/src/ServiceProvider.php, register the namespace manually if needed, or copy views into your app.
• Low maintenance signal. 14 stars and a single-maintainer, kit-adjacent package means version compatibility with Statamic majors is not guaranteed on your schedule. Pin the version and add a smoke test that asserts your <head> contains a title and description on a fixture entry — that catches silent breakage on every upgrade.
• GPL-3.0. Fine for a GPL-compatible site; a genuine consideration if you distribute a closed-source product that bundles it. Check this with whoever owns licensing before it becomes load-bearing.
• Debugging order: (1) is the fieldset attached to this collection's blueprint? (2) does the entry actually have values, or are you seeing empty fallbacks? (3) is the partial rendered before </head> and not swallowed by a caching layer? Antlers {{ if }} around meta output is the classic cause of "tags randomly missing" — dump the raw field values with {{ dump }} in dev before blaming the package.
• Empty fields still render. A blank OG image field commonly emits <meta property="og:image" content="">. Guard every tag with a conditional and treat empty-string as absent.
• Multisite. SEO values are usually per-site, so verify site:has:… vs bare variable resolution. Cross-site leakage in canonical URLs is easy to introduce and hard to spot until Search Console complains.
• Escape and truncate deliberately. These partials often output raw titles. Description length limits are editorial policy, not enforced here — if you need hard truncation, add it in the partial rather than trusting content editors.