seo-metadata-checker/Readme.md

Browser-focused SEO metadata checker for SPAs. Automatically monitors and displays SEO tags with real-time route change detection for React, Vue, Angular apps.

# 🔍 SEO Metadata Checker

A **browser-focused npm package** that automatically monitors and displays SEO metadata for Single Page Applications (SPAs). Perfect for **React, Vue, Angular**, and vanilla JavaScript applications.

## ✨ Features

- 🚀 **Auto-initializing** - Works immediately after import
- 🔄 **Real-time route monitoring** - Detects SPA route changes automatically
- 📱 **Floating panel display** - Clean, toggleable UI overlay
- 📊 **Console logging** - Detailed SEO analysis in DevTools
- 🌐 **Global access** - `window.getSeoMetadata()` function
- ⚡ **Zero dependencies** - Lightweight and fast
- 🎯 **Framework agnostic** - Works with any SPA framework
- 🔧 **Configurable** - Customize behavior and appearance

## 🚀 Installation

```bash
npm install seo-metadata-checker
```

## 📖 Quick Start

### ES6 Modules
```javascript
import 'seo-metadata-checker';
// That's it! The checker auto-initializes and starts monitoring
```

### CommonJS
```javascript
require('seo-metadata-checker');
```

### HTML Script Tag
```html
<script type="module" src="node_modules/seo-metadata-checker/index.js"></script>
```

### CDN (via unpkg)
```html
<script type="module" src="https://unpkg.com/seo-metadata-checker@latest/index.js"></script>
```

## 📋 What It Monitors

The package automatically checks and displays:

### 📄 Basic SEO
- Page title (`<title>`)
- Meta description
- Canonical URL
- Language attribute
- Charset
- Viewport settings
- Robots meta tag

### 📱 Open Graph Tags
- `og:title`
- `og:description`
- `og:image`
- `og:url`
- `og:type`
- `og:site_name`

### 🐦 Twitter Cards
- `twitter:card`
- `twitter:title`
- `twitter:description`
- `twitter:image`
- `twitter:site`
- `twitter:creator`

### 📊 Structured Data
- JSON-LD schema.org markup
- Automatic parsing and validation

## 🎮 Usage Examples

### Programmatic Access
```javascript
// Get current page SEO metadata
const metadata = window.getSeoMetadata();
console.log(metadata);

// Example output:
{
  title: "My Awesome Page",
  description: "This is a great page about...",
  canonical: "https://example.com/page",
  openGraph: {
    title: "My Awesome Page",
    description: "This is a great page about...",
    image: "https://example.com/image.jpg",
    // ... more OG tags
  },
  twitter: {
    card: "summary_large_image",
    title: "My Awesome Page",
    // ... more Twitter tags
  },
  // ... additional metadata
}
```

### Custom Configuration
```javascript
import seoChecker from 'seo-metadata-checker';

// Customize behavior
seoChecker.init({
  autoShow: true,           // Show floating panel automatically
  position: 'top-left',     // Panel position: 'top-left', 'top-right', 'bottom-left', 'bottom-right'
  logToConsole: true,       // Enable console logging
  panelStyle: 'compact'     // Panel style: 'compact' or 'detailed'
});
```

### Manual Control
```javascript
import seoChecker from 'seo-metadata-checker';

// Manual initialization with custom config
seoChecker.init({
  autoShow: false,  // Don't show panel automatically
  logToConsole: true
});

// Manually trigger check and display
const metadata = seoChecker.getSeoMetadata();
seoChecker.showPanel(metadata);

// Clean up when needed
seoChecker.destroy();
```

## 🔧 Framework Integration

### React
```jsx
// App.js or main component
import 'seo-metadata-checker';

function App() {
  return (
    <div className="App">
      {/* Your app content */}
    </div>
  );
}
```

### Vue
```javascript
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import 'seo-metadata-checker';

createApp(App).mount('#app');
```

### Angular
```typescript
// main.ts
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import 'seo-metadata-checker';

platformBrowserDynamic().bootstrapModule(AppModule);
```

### Next.js
```javascript
// pages/_app.js
import { useEffect } from 'react';

export default function MyApp({ Component, pageProps }) {
  useEffect(() => {
    import('seo-metadata-checker');
  }, []);

  return <Component {...pageProps} />;
}
```

## 🎨 UI Features

### Floating Panel
- **Compact design** - Minimal screen space usage
- **Toggle visibility** - Expand/collapse content
- **Issue highlighting** - Visual indicators for SEO problems
- **Positioned corners** - Choose your preferred location
- **Dark theme** - Easy on the eyes during development

### Console Output
```
🔍 SEO Metadata Analysis
  📄 Title: My Awesome Page
  📝 Description: This page is about amazing things...
  🔗 Canonical: https://example.com/page
  🌐 Language: en
  🤖 Robots: index,follow
  
  📱 Open Graph
    title: My Awesome Page
    description: This page is about amazing things...
    image: https://example.com/og-image.jpg
    url: https://example.com/page
    type: website
    
  🐦 Twitter Cards
    card: summary_large_image
    title: My Awesome Page
    description: This page is about amazing things...
    image: https://example.com/twitter-image.jpg
```

## ⚠️ Issue Detection

The package automatically detects common SEO issues:

- ❌ Missing page title
- ❌ Missing meta description
- ❌ Missing language attribute
- ❌ Missing Open Graph image
- ⚠️ Title too long (>60 characters)
- ⚠️ Description too long (>160 characters)
- ⚠️ Invalid canonical URL

## 🔄 Route Change Detection

Works seamlessly with all major SPA routing solutions:

- **React Router** - History API monitoring
- **Vue Router** - Automatic route detection
- **Angular Router** - Navigation change tracking
- **Hash routing** - Polling fallback for hash changes
- **Custom routing** - MutationObserver for dynamic content

## 🌐 Browser Support

- ✅ Chrome 60+
- ✅ Firefox 55+
- ✅ Safari 12+
- ✅ Edge 79+

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup
```bash
git clone https://github.com/yourusername/seo-metadata-checker.git
cd seo-metadata-checker
npm install
```

### Running Tests
```bash
npm test
```

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🎯 Use Cases

- **Development debugging** - Quickly verify SEO tags during development
- **QA testing** - Ensure proper metadata across all pages
- **Social media optimization** - Validate Open Graph and Twitter Cards
- **SEO auditing** - Quick checks during content updates
- **Team collaboration** - Share SEO status visually

## 📚 API Reference

### `window.getSeoMetadata()`
Returns complete SEO metadata object for the current page.

### `window.seoMetadataChecker.init(config)`
Initialize with custom configuration.

### `window.seoMetadataChecker.showPanel(metadata)`
Manually display the floating panel.

### `window.seoMetadataChecker.destroy()`
Clean up and remove all event listeners.

---

**Made with ❤️ for better SEO**

Found this useful? Give it a ⭐ on GitHub!