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).

# 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

npm install -g vibe-seo

2. Initialize Your Project

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:

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

4. Generate SEO Files (One Command)

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

# Automatically detected and fixed
npx vibe-seo-gen all

Next.js

# 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.

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:

# 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)

npx vibe-seo-gen all [options]

Generate Specific Files

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:

# 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

# 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

// 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

// 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

// 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

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:

<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:

<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 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

# 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)

<!-- 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)

npx vibe-seo-gen all
# Files automatically copied to public/ directory
# All compatibility fixes applied automatically

Next.js Projects

npx vibe-seo-gen all
# Files automatically copied to public/ directory

Deployment Checklist

1. Generate files: npx vibe-seo-gen all
2. Verify accessibility:

   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"

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:

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:

   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:

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:

# 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:

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:

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

Environment-Specific Configs

# 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

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 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):

# 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.