vibe-seo/README.md

AI-friendly SEO generator for modern web frameworks

# Vibe SEO v0.6.20

**AI-friendly SEO generator for modern web frameworks** - Now with automatic compatibility fixes for Vite React applications!

## 🚀 **One-Command Solution**

Vibe SEO is now a **true self-service tool** that automatically handles all compatibility issues. Perfect for the Lovable stack (Vite + React + TypeScript + shadcn-ui + Tailwind CSS).

```bash
# Install
npm install -g vibe-seo

# Initialize
npx vibe-seo-init

# Generate all SEO files with automatic fixes
npx vibe-seo-gen all
```

**That's it!** Your SEO files work perfectly out of the box. No manual configuration needed.

## ✨ **What's New in v0.6.4**

### 🔧 **Automatic Compatibility Fixes**
- **Vite Configuration**: Automatically updates your `vite.config.ts` for static file handling
- **Vite SEO Plugin**: Creates a custom plugin for proper static file serving with correct MIME types
- **Server Configuration**: Creates `vercel.json` and `netlify.toml` with proper MIME types
- **File Management**: Copies generated files to the `public/` directory

### 🎯 **Perfect for Lovable Stack**
- ✅ **Vite** - Automatic config updates
- ✅ **React** - Automatic App.tsx modifications  
- ✅ **TypeScript** - Proper type handling
- ✅ **shadcn-ui** - No conflicts
- ✅ **Tailwind CSS** - No interference

### 🤖 **AI-Friendly by Design**
Optimized for modern AI crawlers:
- **GPTBot** (OpenAI)
- **ClaudeBot** (Anthropic)
- **PerplexityBot** (Perplexity)
- **Meta-ExternalAgent** (Meta AI)
- **Applebot** (Apple Intelligence)
- Plus traditional search engines

## 🛠 **Quick Start**

### 1. Install
```bash
npm install -g vibe-seo
```

### 2. Initialize Your Project
```bash
cd your-lovable-project
npx vibe-seo-init
```

**What this does:**
- Detects your framework automatically
- Creates `./seo/config/seo.config.yaml`
- Sets up template files
- Configures framework-specific paths

### 3. Configure Your Site
Edit `./seo/config/seo.config.yaml`:

```yaml
site:
  url: "https://yourdomain.com"
  name: "Your Company Name"
  description: "Your compelling site description"
```

### 4. Generate SEO Files (One Command)
```bash
npx vibe-seo-gen all
```

**This single command:**
- ✅ Generates all SEO files (sitemap, robots, meta tags, JSON-LD)
- ✅ **Automatically fixes your Vite config** for static file handling
- ✅ **Automatically updates your App.tsx** to handle static file requests
- ✅ **Creates server configs** for proper MIME types
- ✅ **Copies files to public directory** for immediate access
- ✅ **Makes everything work** without manual configuration

### 5. Test Your Files
- `http://localhost:5173/robots.txt` ✅ Works
- `http://localhost:5173/sitemap.xml` ✅ Works
- No 404 errors ✅
- No download issues ✅

## 📋 **Generated Files**

### Core SEO Files
- `public/sitemap.xml` - XML sitemap for search engines
- `public/robots.txt` - Instructions for web crawlers
- `seo/output/meta-tags/` - HTML meta tag files for each page
- `seo/output/jsonld/` - Structured data for rich snippets

### Automatic Fixes Applied
- `vite.config.ts` - Updated with SEO static file handling
- `src/App.tsx` - Modified with static file request handling
- `vercel.json` - Created with proper MIME type headers
- `netlify.toml` - Created with proper MIME type headers

## 🎯 **Framework Support**

### **Vite React (Lovable Stack)** ⭐ **Recommended**
```bash
# Automatically detected and fixed
npx vibe-seo-gen all
```

### **Next.js**
```bash
# App Router & Pages Router
npx vibe-seo-gen all
```

### **Other Frameworks**
- **React** (Create React App)
- **Vue.js**
- **Angular**
- **Static HTML**

## 📖 **Commands Reference**

### `vibe-seo-init`
Initialize vibe-seo in your project.

```bash
npx vibe-seo-init [options]
```

**Options:**
- `-f, --framework <type>` - Force specific framework
- `-d, --dir <directory>` - Custom output directory (default: `./seo`)
- `--force` - Overwrite existing configuration

**Examples:**
```bash
# Auto-detect framework (recommended)
npx vibe-seo-init

# Force Next.js App Router
npx vibe-seo-init --framework nextjs-app

# Custom directory
npx vibe-seo-init --dir ./custom-seo

# Overwrite existing config
npx vibe-seo-init --force
```

### `vibe-seo-gen`
Generate SEO files from your configuration.

#### Generate All Files (Recommended)
```bash
npx vibe-seo-gen all [options]
```

#### Generate Specific Files
```bash
npx vibe-seo-gen sitemap    # Only sitemap.xml
npx vibe-seo-gen robots     # Only robots.txt
npx vibe-seo-gen meta       # Only meta tags
npx vibe-seo-gen scan       # Preview detected pages
```

**Options:**
- `-c, --config <path>` - Custom config file path
- `-o, --output <path>` - Custom output directory
- `--debug` - Enable detailed logging

**Examples:**
```bash
# Generate with debug info
npx vibe-seo-gen all --debug

# Custom config location
npx vibe-seo-gen all -c ./config/seo.yaml

# Preview pages without generating
npx vibe-seo-gen scan
```

## ⚙️ **Configuration Guide**

### Complete Configuration Example

```yaml
# Framework (auto-detected)
framework: react

# Site Information
site:
  url: "https://yourdomain.com"
  name: "Your Company Name"
  description: "Your compelling site description"
  logo: "/assets/logo.png"
  language: "en"
  locale: "en_US"
  author: "Your Name"
  favicon: "/favicon.ico"

# Multilingual Configuration
languages:
  default: "en"
  supported:
    - code: "en"
      locale: "en_US"
      name: "English"
      url: "https://yourdomain.com"
    - code: "es"
      locale: "es_ES"
      name: "Español"
      url: "https://yourdomain.com/es"

# AI-Friendly Bot Configuration
bots:
  allow:
    - "Googlebot"
    - "Bingbot"
    - "GPTBot"
    - "PerplexityBot"
    - "ClaudeBot"
    - "Meta-ExternalAgent"
    - "Applebot"
    - "YouBot"
    - "DuckDuckBot"
  disallow: []
  crawlDelay: 1

# SEO Templates
seo:
  titleTemplate: "{title} | {siteName}"
  descriptionTemplate: "{description}"
  imageTemplate: "{siteUrl}/og-images/{slug}.png"
  twitterCard: "summary_large_image"
  ogType: "website"
  defaultKeywords: "keyword1, keyword2, keyword3"

# Sitemap Configuration
sitemap:
  changefreq: "weekly"
  priority: 0.8
  excludePaths:
    - "/admin/*"
    - "/api/*"
    - "/_next/*"
    - "/private/*"

# Search Engine Verification
verification:
  google: "your-verification-token"
  bing: "your-bing-token"
  yandex: "your-yandex-token"
  pinterest: "your-pinterest-token"

# Framework-Specific Paths
paths:
  srcDir: "./src"
  publicDir: "./public"
  buildDir: "./dist"
  outputDir: "./public"
```

## 🔧 **Automatic Fixes Applied**

### **For Vite React Applications**

When you run `npx vibe-seo-gen all`, the tool automatically:

#### **1. Updates Vite Configuration**
```typescript
// Automatically added to your vite.config.ts
build: {
  rollupOptions: {
    output: {
      assetFileNames: (assetInfo) => {
        if (assetInfo.name === 'robots.txt' || assetInfo.name === 'sitemap.xml') {
          return '[name][extname]';
        }
        return 'assets/[name]-[hash][extname]';
      }
    }
  }
},
assetsInclude: ['**/*.txt', '**/*.xml']
```

#### **2. Creates Vite SEO Plugin**
```javascript
// Automatically created vite-seo-plugin.js
export default function seoPlugin() {
  return {
    name: 'vite-seo-plugin',
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        if (req.url === '/robots.txt' || req.url === '/sitemap.xml') {
          // Set proper MIME types and serve files
          const content = readFileSync(filePath, 'utf8');
          res.setHeader('Content-Type', req.url === '/robots.txt' ? 'text/plain' : 'application/xml');
          res.writeHead(200);
          res.end(content);
          return;
        }
        next();
      });
    }
  };
}
```

#### **3. Creates Server Configuration**
```json
// Automatically created vercel.json
{
  "headers": [
    {
      "source": "/robots.txt",
      "headers": [{"key": "Content-Type", "value": "text/plain"}]
    },
    {
      "source": "/sitemap.xml",
      "headers": [{"key": "Content-Type", "value": "application/xml"}]
    }
  ]
}
```

#### **4. Copies Files to Public Directory**
- `sitemap.xml` → `public/sitemap.xml`
- `robots.txt` → `public/robots.txt`

## 🌐 **Multilingual SEO**

### Setting Up Multiple Languages

```yaml
languages:
  default: "en"
  supported:
    - code: "en"
      locale: "en_US"
      name: "English"
      url: "https://yourdomain.com"
    - code: "es"
      locale: "es_ES"
      name: "Español"
      url: "https://yourdomain.com/es"
    - code: "de"
      locale: "de_DE"
      name: "Deutsch"
      url: "https://yourdomain.de"
```

### Generated Hreflang Output

**In Meta Tags:**
```html
<link rel="alternate" hreflang="en" href="https://yourdomain.com/about">
<link rel="alternate" hreflang="es" href="https://yourdomain.com/es/about">
<link rel="alternate" hreflang="x-default" href="https://yourdomain.com/about">
```

**In Sitemap:**
```xml
<url>
  <loc>https://yourdomain.com/about</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://yourdomain.com/about"/>
  <xhtml:link rel="alternate" hreflang="es" href="https://yourdomain.com/es/about"/>
  <xhtml:link rel="alternate" hreflang="x-default" href="https://yourdomain.com/about"/>
</url>
```

## 📄 **Generated Files Examples**

### Sitemap (sitemap.xml)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" 
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://yourdomain.com/</loc>
    <lastmod>2024-01-01T00:00:00.000Z</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
    <xhtml:link rel="alternate" hreflang="en" href="https://yourdomain.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://yourdomain.com/es/"/>
  </url>
</urlset>
```

### Robots.txt
```txt
# Robots.txt for Your Company Name
# Generated by vibe-seo

User-agent: *
Allow: /

# AI-friendly crawlers
User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

# Sitemap location
Sitemap: https://yourdomain.com/sitemap.xml
```

### Meta Tags (meta-tags/index.html)
```html
<!-- SEO Meta Tags for / -->
<!-- Generated by vibe-seo -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">

<!-- Primary Meta Tags -->
<title>Home | Your Company Name</title>
<meta name="description" content="Your compelling site description">

<!-- Search Engine Verification -->
<meta name="google-site-verification" content="your-verification-token">

<!-- Language and Internationalization -->
<link rel="alternate" hreflang="en" href="https://yourdomain.com/">
<link rel="alternate" hreflang="es" href="https://yourdomain.com/es/">
<link rel="alternate" hreflang="x-default" href="https://yourdomain.com/">

<!-- Open Graph / Facebook -->
<meta property="og:type" content="website">
<meta property="og:url" content="https://yourdomain.com/">
<meta property="og:title" content="Home | Your Company Name">
<meta property="og:site_name" content="Your Company Name">

<!-- Twitter -->
<meta property="twitter:card" content="summary_large_image">
<meta property="twitter:url" content="https://yourdomain.com/">

<!-- Canonical URL -->
<link rel="canonical" href="https://yourdomain.com/">
```

## 🧠 **Smart Content Generation**

### Intelligent Title Generation

Vibe SEO automatically converts URLs to readable titles:

| URL | Generated Title |
|-----|----------------|
| `/` | `Home | Your Company` |
| `/about` | `About | Your Company` |
| `/about-us` | `About Us | Your Company` |
| `/contact-info` | `Contact Info | Your Company` |
| `/services/web-design` | `Services - Web Design | Your Company` |

### Dynamic Description Generation

**With site description configured:**
- Homepage: Uses your site description directly
- Other pages: `{Page Title} - {Your site description}`

**Without site description:**
- Homepage: `Welcome to {Your Company}`
- Other pages: `{Page Title} | {Your Company}`

## 🚀 **Deployment & Integration**

### **Vite React Projects (Lovable Stack)**
```bash
npx vibe-seo-gen all
# Files automatically copied to public/ directory
# All compatibility fixes applied automatically
```

### **Next.js Projects**
```bash
npx vibe-seo-gen all
# Files automatically copied to public/ directory
```

### **Deployment Checklist**

1. **Generate files**: `npx vibe-seo-gen all`
2. **Verify accessibility**:
   ```bash
   curl https://yourdomain.com/robots.txt
   curl https://yourdomain.com/sitemap.xml
   ```
3. **Test verification**: Check Google Search Console
4. **Validate hreflang**: Use Google's URL Inspection tool

### **Popular Hosting Platforms**

**Vercel**: Files served automatically from `public/` ✅  
**Netlify**: Configure publish directory to include generated files ✅  
**AWS/Cloudfront**: Ensure static file serving is configured ✅  
**Docker**: Include `COPY public/ /app/public/` in Dockerfile ✅

## 🔍 **Troubleshooting**

### Common Issues

#### "No Pages Detected"
```bash
npx vibe-seo-gen scan --debug
```

**Solutions:**
1. Run `npx vibe-seo-init --force` to re-detect framework
2. Check that your pages are in expected directories
3. Manually specify framework: `--framework react`

#### "Missing required config field"
```
Error: Missing required config field: site.name
```

**Solution:**
Ensure your config file has all required fields:
```yaml
site:
  url: "https://yourdomain.com"  # Required
  name: "Your Company"           # Required
```

#### Generated Files Not Loading

1. **Check file permissions**: Ensure files are readable
2. **Verify hosting config**: Confirm static files are served
3. **Clear cache**: CDN and browser caches
4. **Test URLs directly**:
   ```bash
   curl -I https://yourdomain.com/robots.txt
   curl -I https://yourdomain.com/sitemap.xml
   ```

#### Google Search Console Verification Fails

1. **Check meta tag placement**: Must be in `<head>` section
2. **Verify token accuracy**: Copy exact content value
3. **Test accessibility**: Ensure homepage is publicly accessible
4. **Wait for propagation**: Changes may take time to take effect

### Debug Mode

Enable comprehensive logging:

```bash
npx vibe-seo-gen all --debug
```

**Debug output shows:**
- Config validation results
- Framework detection details
- Page scanning progress
- Generated content preview
- File creation confirmation
- Automatic fixes applied

### Getting Help

**Common Debug Commands:**
```bash
# Check detected pages
npx vibe-seo-gen scan

# Validate config
npx vibe-seo-gen robots --debug

# Test framework detection
npx vibe-seo-init --force
```

## 📚 **Advanced Usage**

### Custom Page Configuration

Override defaults for specific pages:

```yaml
pages:
  "/":
    title: "Welcome to Our Site"
    description: "Custom homepage description"
    priority: 1.0
  "/about":
    title: "About Our Company"
    changefreq: "monthly"
```

### Multiple Sitemaps

For large sites:

```yaml
additionalSitemaps:
  - "https://yourdomain.com/blog-sitemap.xml"
  - "https://yourdomain.com/products-sitemap.xml"
```

### Environment-Specific Configs

```bash
# Development
npx vibe-seo-gen all -c ./config/dev.seo.yaml

# Staging
npx vibe-seo-gen all -c ./config/staging.seo.yaml

# Production
npx vibe-seo-gen all -c ./config/prod.seo.yaml
```

### Programmatic Usage

```javascript
const { loadConfig, generateAll, scanPages } = require('vibe-seo');

async function generateSEO() {
  const config = await loadConfig('./seo.config.yaml');
  const pages = await scanPages(config);
  const results = await generateAll(pages, config, './output');
  console.log('Fixes applied:', results.fixes);
}
```

## 📈 **Version History**

### v0.6.20 (Latest) ⭐
- ✅ **Enhanced Next.js App Router detection and guidance**
- ✅ **Automatic layout template generation for App Router**
- ✅ **Prevents metadata export issues in client components**
- ✅ **Comprehensive App Router troubleshooting and best practices**

### v0.6.3
- ✅ Enhanced config data usage throughout
- ✅ Intelligent title and description generation
- ✅ Comprehensive validation and error messages
- ✅ Detailed debugging output

### v0.6.2
- ✅ Enhanced Vite React support and improved page detection
- ✅ Better handling of TypeScript files
- ✅ Improved framework detection for Vite projects

### v0.6.1
- ✅ Enhanced config data usage throughout
- ✅ Intelligent title and description generation
- ✅ Comprehensive validation and error messages
- ✅ Detailed debugging output

### v0.6.0
- ✅ Multilingual hreflang support
- ✅ Google Search Console integration
- ✅ Enhanced meta tag templates
- ✅ Sitemap internationalization
- ✅ Open Graph localization

## 🎯 **Best Practices**

### SEO Optimization

1. **Use descriptive URLs**: `/about-us` vs `/page1`
2. **Configure site description**: Used as fallback for all pages
3. **Set up verification**: Enable Search Console monitoring
4. **Implement hreflang**: For international audiences
5. **Regular regeneration**: After adding new pages

### Performance

1. **Generate on build**: Include in CI/CD pipeline
2. **Cache generated files**: Don't regenerate on every request
3. **Optimize images**: Use efficient Open Graph image formats
4. **Monitor file sizes**: Large sitemaps should be split

### Maintenance

1. **Update after changes**: Run generation after config updates
2. **Monitor Search Console**: Check for crawl errors
3. **Validate periodically**: Ensure files remain accessible
4. **Version control configs**: Track SEO configuration changes

## 🤝 **Contributing**

Vibe SEO is open source and welcomes contributions. Visit our [GitHub repository](https://github.com/onecf/vibe-seo) for:

- 🐛 Bug reports
- 💡 Feature requests  
- 🔧 Pull requests
- 📚 Documentation improvements

## 📄 **License**

MIT License - Free for commercial and personal use.

---

## 🚀 **Ready to Optimize Your SEO?**

**For Lovable Stack (Vite + React + TypeScript + shadcn-ui + Tailwind CSS):**

```bash
# Install
npm install -g vibe-seo

# Initialize
npx vibe-seo-init

# Generate all SEO files with automatic fixes
npx vibe-seo-gen all
```

**That's it!** Your SEO files work perfectly out of the box. No manual configuration needed. 🎉

---

**Perfect for:** Lovable, Vite React, Next.js, and all modern web frameworks.

**Built for:** AI-friendly SEO that works with modern crawlers and traditional search engines.