Coding guidelines that bake modern SEO best practices directly into the HTML/CSS/JavaScript production workflow, ensuring sites ship fast, crawlable, and search-optimized.
You're tired of retrofitting SEO into finished websites. These comprehensive Cursor Rules transform your development workflow by baking modern SEO best practices directly into your HTML, CSS, and JavaScript—ensuring every commit ships faster, more crawlable, and search-optimized code.
Most developers treat SEO as a post-launch checklist item. You build the feature, ship it, then scramble to add meta tags, fix Core Web Vitals violations, and restructure semantic markup when organic traffic tanks. This reactive approach creates massive technical debt:
The result? You're constantly firefighting SEO issues instead of building features, while competitors with SEO-first workflows consistently outrank you.
These Cursor Rules embed technical SEO expertise directly into your coding workflow. Instead of remembering 100+ optimization techniques, you get intelligent code suggestions that automatically:
No more post-launch SEO audits. Every component ships with proper semantic markup, optimized performance, and structured data. Your QA cycle shrinks because SEO requirements are satisfied during development.
Target <2.5s LCP, <100ms FID, <0.1 CLS automatically. The rules prevent render-blocking patterns and enforce critical CSS inlining, lazy loading, and proper resource prioritization.
Every breakpoint, image, and layout decision starts mobile-first, aligning with Google's indexing preferences without extra planning or refactoring.
Generate XML sitemaps, robots.txt, canonical tags, and hreflang attributes at build time. Handle 404s, redirects, and duplicate content prevention with automated middleware.
Built-in Lighthouse CI integration fails builds when SEO scores drop. Web Vitals logging surfaces performance regressions before they impact rankings.
Before: Developer creates blog post component → Designer reviews layout → Content team adds copy → SEO specialist audits for schema markup, meta tags, heading hierarchy → Developer implements fixes → Second review cycle
After: Blog post template automatically includes Article schema, proper heading hierarchy validation, meta tag templates, and Core Web Vitals monitoring. Content team publishes directly with SEO compliance guaranteed.
// Auto-generated with proper schema and SEO
export function BlogPost({ title, content, author, publishedDate }) {
return (
<SeoHead
title={title}
description={extractDescription(content)}
schema={generateArticleSchema({ title, author, publishedDate })}
>
<article>
<header>
<h1>{title}</h1> {/* Exactly one H1, hierarchy validated */}
<BreadcrumbSchema path={getBreadcrumbPath()} />
</header>
<main dangerouslySetInnerHTML={{ __html: content }} />
</article>
</SeoHead>
);
}
Before: Feature development → Performance testing → Identify Core Web Vitals issues → Refactor images, CSS, JavaScript → Re-test → Deploy
After: Performance constraints enforced during development. Images automatically optimized with next/image, CSS critical path extracted, JavaScript deferred by default.
// Automatic optimization with built-in monitoring
import { WebVitals } from './lib/web-vitals';
export default function App({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<WebVitals onMetric={reportWebVitals} threshold="strict" />
</>
);
}
Add the SEO-First rules to your .cursorrules file in your project root. The rules integrate with your existing Next.js, React, or vanilla JavaScript workflow.
# Add SEO validation to package.json
"scripts": {
"build": "next build && npm run validate-seo",
"validate-seo": "lighthouse-ci --collect.numberOfRuns=3 --assert.preset=lighthouse:recommended"
}
// middleware.js - Automatic URL optimization
export function middleware(request) {
// Force HTTPS, normalize URLs, handle redirects
return enforceSeoUrlPolicy(request);
}
The rules generate reusable SEO components that handle schema markup, meta tags, and structured data automatically:
// Auto-generated SEO utilities
export function SeoHead({ title, description, schema, children }) {
return (
<Head>
<title>{title}</title>
<meta name="description" content={description} />
<script type="application/ld+json">
{JSON.stringify(schema)}
</script>
{children}
</Head>
);
}
Your build pipeline automatically runs Lighthouse audits, checks for broken links, validates HTML, and fails deployments that regress SEO scores.
Your development team ships SEO-optimized code by default while competitors struggle with technical debt. Every feature launch improves rather than hinders search performance.
Stop treating SEO as an afterthought. These Cursor Rules turn technical SEO into an automated part of your development process, letting you focus on building features while ensuring every line of code improves search performance.
Your future self—and your organic traffic—will thank you.
You are an expert in HTML5, CSS3, modern JavaScript (ES2023+), Node.js, React/Next.js, Lighthouse, and technical SEO automation tooling (Gumloop, AirOps, Surfer AI, Alli AI, Page Optimizer Pro).
Key Principles
- Ship SEO as a first-class feature: every commit must improve or preserve crawlability, speed, and semantics.
- Mobile-first, responsive design is mandatory (aligns with Google’s Mobile-First Indexing).
- Favor semantic, accessible markup; ARIA only when native semantics fail.
- Performance is part of SEO: target <2.5 s LCP, <100 ms FID, <0.1 CLS (Core Web Vitals).
- HTTPS is non-negotiable; refuse to deploy to HTTP endpoints.
- Content quality beats keyword stuffing; write for humans, structure for bots.
- Automate audits (Lighthouse CI, PageSpeed Insights API) in the CI pipeline.
HTML
- Use semantic elements (<header>, <main>, <nav>, <article>, <section>, <footer>)—never div soup.
- Exactly one <h1> per page, reflecting the primary intent; nest other headings hierarchically (h2-h6).
- Add rel="canonical" for every indexable page to mitigate duplicate content.
- Always include <meta charset="utf-8">, viewport, description (≤160 chars), and OG/Twitter cards.
- Lazy-load non-critical images with loading="lazy" and decoding="async".
- Use descriptive, keyword-rich, kebab-case filenames/paths (e.g., /blog/core-web-vitals-guide).
CSS
- Inline critical CSS (<style data-critical>) for above-the-fold, defer remainder via <link rel="preload" as="style">.
- Use logical, mobile-first breakpoints; avoid fixed widths.
- Minify and purge unused CSS (e.g., PurgeCSS) before production.
JavaScript
- Defer all non-critical scripts; never block rendering (use defer or type="module").
- Avoid client-side rendering for primary content; prefer SSR/SSG (Next.js getServerSideProps/getStaticProps).
- Implement structured data via JSON-LD objects injected server-side, e.g., Article, FAQ, HowTo.
- Use descriptive variable/function names that convey purpose (e.g., generateBreadcrumbSchema()).
- Handle edge cases early; validate external API failures and fall back gracefully to cached/static data.
Error Handling & Validation
- Abort build on HTML validation errors (use html-validate). Broken links fail CI (linkinator).
- Automatically create custom 404 and 410 pages; direct removed content to appropriate status codes.
- Force HTTPS; redirect HTTP → HTTPS with 301.
- Log Core Web Vitals in real time (Web-Vitals JS) and surface alerts when thresholds breached.
Framework: Next.js (React)
- Use next/head for meta tags; centralize templates in <SeoHead /> component.
- Implement dynamic <link rel="alternate" hreflang> for multilingual sites.
- Images must use next/image with correct width, height, and priority flags.
- Generate sitemap.xml and robots.txt at build time via next-sitemap.
- Connect middleware to enforce trailing-slash and lowercase URL policy.
- Wrap getServerSideProps with withSeoCache() utility to set caching headers (s-maxage, stale-while-revalidate).
Testing
- Integrate Lighthouse CI, Axe, and Jest-axe in pull-requests; PR fails if score <90 or WCAG violations.
- Nightly run Screaming Frog or Alli AI API to crawl staging and report new 404/redirect chains.
- Use Playwright to snapshot and diff LCP element load times across versions.
Performance
- Adopt Module/Chunk preloading (Next.js experimental HTTP 2 push disabled; rely on preload hints).
- Serve images in AVIF/WebP with width-responsive <picture> fallbacks.
- Remove third-party scripts that add >50 ms main-thread blocking time.
Security
- Enforce HSTS (max-age ≥ 31536000; preload).
- Set CSP to block inline scripts except hashed critical CSS/JS.
- Regularly rotate API keys used by SEO tooling.
Automation & Tooling
- Keyword research: integrate Google Keyword Planner API with a cron job populating Airtable.
- Content briefs: trigger Surfer AI via AirOps workflow on new topic tickets.
- On merge to main, run Gumloop pipeline: build → Lighthouse → Page Optimizer Pro diff → deploy.
Common Pitfalls & Guards
- NEVER use "click here" anchor text; CI lints anchors (markdown-lint-anchor-text rule).
- Avoid parameterized URLs for canonical pages (?utm=, ?ref=). Middleware strips or canonicalizes.
- If page speed regression >5 %, block release until fixed.
Directory Naming
- pages/blog/core-web-vitals-guide.tsx (kebab-case, keyword-rich).
- components/seo/breadcrumb-schema.tsx
Commit Message Template
feat(seo): add FAQ schema to /pricing page
Always include measurable SEO impact in commit body ("expected +0.5 pts Lighthouse SEO score").