@nandansravesh/react-smart-seo

v0.1.1

Published

6 months ago

Framework-agnostic SEO orchestration for React with automatic metadata, Open Graph, and structured data.

0High
0Medium
0Low

nandansravesh

react seo react-seo metadata open-graph twitter-cards json-ld head ssr

🧠 react-smart-seo

Framework-agnostic SEO orchestration for React
Next.js-level SEO thinking — without needing Next.js.

react-smart-seo is an opinionated, zero-config SEO system for React applications.
It goes beyond basic <head> management and helps developers apply SEO best practices by default, without repetitive boilerplate or manual mistakes.

✨ Why react-smart-seo?

Most React SEO libraries only help you set meta tags.
They don’t help you avoid SEO mistakes, scale SEO across large apps, or enforce consistency.

react-smart-seo is different.

It acts as an SEO orchestration layer that sits between your React app and the document head.

🚀 Key Features

✅ Smart Defaults (Zero Config)

Automatic <title>, meta description, and canonical URL
Open Graph & Twitter cards auto-generated
Sensible SEO fallbacks for every page

✅ Centralized SEO Configuration

Global defaults using SeoProvider
Consistent titles, descriptions, and site metadata

✅ Built-in SEO Validation (Dev-Only)

Warns if:
- Title is missing
- Canonical URL is missing
- Meta description is too long
Optional strict mode to throw errors

✅ Structured Data (JSON-LD)

Built-in support for:
- Article
- WebSite
- Breadcrumb
No manual JSON writing

✅ Head Deduplication

Prevents duplicate <meta> and <title> tags
Safe across re-renders and route changes

✅ Framework-Agnostic

Works with:
- Vite
- CRA
- Custom SSR
- Any React setup
No Next.js dependency

🆚 How It’s Different from Other Libraries

| Feature | react-helmet | next-seo | react-smart-seo | | -------------------- | ------------ | -------- | --------------- | | Framework agnostic | ✅ | ❌ | ✅ | | SEO validation | ❌ | ❌ | ✅ | | Auto OG & Twitter | ❌ | ✅ | ✅ | | Structured data | ❌ | ✅ | ✅ | | Centralized config | ❌ | ✅ | ✅ | | Strict SEO mode | ❌ | ❌ | ✅ | | Opinionated defaults | ❌ | ❌ | ✅ |

react-smart-seo doesn’t just manage tags — it enforces SEO discipline.

📦 Installation

npm install @nandansravesh/react-smart-seo

🧩 Basic Usage

import { Seo } from "@nandansravesh/react-smart-seo";

function Home() {
  return <Seo title="Home" />;
}

This automatically generates:

<title>
<meta name="description"> (fallback)
Canonical URL
Open Graph metadata
Twitter cards

🌍 Global Configuration with SeoProvider

import { SeoProvider } from "@nandansravesh/react-smart-seo";

<SeoProvider
  config={{
    siteName: "XecureCode",
    siteUrl: "https://xecurecode.com",
    titleTemplate: "%s | XecureCode",
    defaultDescription: "We build scalable software",
    twitterHandle: "@xecurecode",
  }}
>
  <App />
</SeoProvider>;

All pages automatically inherit:

Title template
Default description
Site-wide metadata

🧠 Page-Level SEO

<Seo title="Pricing" description="Simple and transparent pricing" />

Generates:

Full title using template
Canonical URL
OG & Twitter metadata
Robots meta tag

🔗 Canonical URLs (Auto)

You don’t need to pass canonical manually.

<Seo title="Blog" />

Automatically resolves to:

https://yoursite.com/current-path

🧱 Structured Data (JSON-LD)

Article Schema Example

<Seo
  title="My Blog Post"
  schema={{
    type: "Article",
    headline: "My Blog Post",
    datePublished: "2024-01-01",
    author: "Sravesh Nandan",
  }}
/>

Automatically injects valid JSON-LD into the document head.

⚠️ SEO Warnings (Development Mode)

In development, you may see warnings like:

⚠️ [react-smart-seo] Missing <title> tag
⚠️ [react-smart-seo] Meta description too long (182 chars)

These warnings:

Help catch SEO issues early
Do not affect production builds

🔐 Strict Mode (Fail Fast)

Enable strict mode to enforce SEO rules:

<Seo strict />

In development:

Throws errors instead of warnings
Ideal for teams, CI, and large projects

🔄 SPA & Route Change Friendly

Works seamlessly with React Router
Metadata updates correctly on route navigation
No duplicated tags on re-render

⚠️ Notes & Limitations

Best SEO results with SSR or SSG
Client-side apps still benefit from:
- Social sharing previews
- Browser metadata
Requires React 17 or higher

🛣️ Roadmap

Sitemap generation
More structured data schemas
SEO linting rules
Framework adapters
Performance hints

📄 License

⭐ Final Tip

If you find this useful:

⭐ Star the repository
🧪 Use it in a real project
🐛 Report issues or suggest features