npm package: @nandansravesh/react-smart-seo
Description: Framework-agnostic SEO orchestration for React with automatic metadata, Open Graph, and structured data.
Author: Sravesh Nandan
Latest version: 0.1.1

# 🧠 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

```bash
npm install @nandansravesh/react-smart-seo
```

---

## 🧩 Basic Usage

```tsx
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

```tsx
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

```tsx
<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.

```tsx
<Seo title="Blog" />
```

Automatically resolves to:

```tsx
https://yoursite.com/current-path
```

---

## 🧱 Structured Data (JSON-LD)

### Article Schema Example

```tsx
<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:

```tsx
⚠️ [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:

```tsx
<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

MIT © Nandan Sravesh

---

## ⭐ Final Tip

If you find this useful:

- ⭐ Star the repository
- 🧪 Use it in a real project
- 🐛 Report issues or suggest features