---
name: server-seo
description: Technical SEO for frontend apps — crawlable HTML on the first response, per-route ``/description, Open Graph and Twitter Card previews, JSON-LD structured data (Product, Article, BreadcrumbList, FAQPage), canonical URLs and hreflang clusters, XML sitemaps and `robots.txt`, semantic headings and alt text, and Core Web Vitals (LCP/INP/CLS). Use when a route needs metadata, share previews render blank, rich results are missing, or crawlers only see an empty `#root`.
when_to_use: Adding or auditing per-route title/description/canonical metadata; fixing blank Open Graph or Twitter share previews; adding JSON-LD for rich results; generating a sitemap or editing `robots.txt`; setting up hreflang for localised routes; diagnosing why a client-rendered SPA route is not indexed; chasing LCP/INP/CLS regressions that affect Page Experience.
paths:
- "**/robots.txt"
- "**/sitemap*.{xml,js,ts}"
- "**/*{Seo,SEO,Meta,Head,StructuredData}*.{jsx,tsx,vue,js,ts}"
---
# SEO
## What is Technical SEO?
Technical SEO is the work of making an application's content *reachable, parseable, and attributable* by crawlers. It splits into two halves: **crawling and indexing** (does the bot get real HTML, with the right metadata, at a canonical URL?) and **page experience** (does the page load and respond fast enough — LCP < 2.5s, INP < 200ms, CLS < 0.1?). A client-rendered SPA fails the first half by default: the crawler receives `<div id="root"></div>` and must run your JS to discover anything.
## Key Principles
1. **Metadata Is Per Route, Not Per Site**: Every indexable URL needs its own title (50–60 chars), description (150–160 chars), canonical, and OG image. Duplicated sitewide tags tell the search engine your pages are interchangeable.
2. **HTML on the First Response Wins**: Crawlers execute JS, but on a deferred budget, and social-preview scrapers (Slack, LinkedIn, Discord) generally do not execute it at all. SSR or SSG is what makes metadata reliable — see the `server-ssr` and `server-ssg` skills.
3. **Declare One Canonical URL**: `/products`, `/products/`, `/products?ref=x` and a localised twin are four URLs for one page. `<link rel="canonical">` plus 301s consolidates their signals; self-referential canonicals are the safe default.
4. **Structured Data Buys Presentation, Not Ranking**: JSON-LD makes a result eligible for stars, prices, breadcrumbs, and FAQ accordions — a CTR lever, distinct from position.
## Best Practices
✅ **DO**:
- Give each route a unique title, description, and canonical URL
- Set `og:title`/`og:description`/`og:image` (absolute URLs) as the baseline, plus `twitter:card` for layout
- Emit JSON-LD matching what is actually visible on the page, and validate with the Rich Results Test
- Ship an XML sitemap with `lastmod` and reference it from `robots.txt`
- Use one `<h1>` and a non-skipping heading hierarchy; write descriptive `alt` text
- Make hreflang clusters bidirectional and include `x-default`
❌ **DON'T**:
- Rely on client-side `document.title` mutation as your only metadata strategy
- Mark up content the user cannot see (Google treats it as spam)
- Block CSS/JS in `robots.txt` — the renderer needs them to see your layout
- Use `robots.txt` to hide a page from the index (use `noindex`; a disallowed URL can still rank)
- Let a hero image lazy-load or ship images without dimensions (LCP and CLS regressions)
- Ship desktop-only content behind mobile "read more" toggles — indexing is mobile-first
## Code Patterns
### Per-Route Metadata
```jsx
// React 19 hoists <title>/<meta> from anywhere in the tree into <head>
function Seo({ title, description, canonical, image, type = 'website' }) {
return (
<>
<title>{`${title} | YourSite`}
);
}
```
Frameworks with a metadata pipeline (`generateMetadata` in Next's App Router, ``, `useHead` in Nuxt) render these server-side, which is what makes them visible to non-JS scrapers.
### Structured Data (JSON-LD)
```jsx
function StructuredData({ data }) {
return (
);
}
const productSchema = {
'@context': 'https://schema.org',
'@type': 'Product',
name: product.name,
image: product.images,
description: product.description,
sku: product.sku,
brand: { '@type': 'Brand', name: product.brand },
offers: {
'@type': 'Offer',
url: `https://example.com/products/${product.id}`,
priceCurrency: 'USD',
price: product.price,
availability: product.inStock
? 'https://schema.org/InStock'
: 'https://schema.org/OutOfStock',
},
aggregateRating: { '@type': 'AggregateRating', ratingValue: product.rating, reviewCount: product.reviewCount },
};
```
`BreadcrumbList` for navigation trails, `Article` (headline/author/datePublished) for posts, `FAQPage` for Q&A — one `