Documentation

Vibe SEO v0.6.18 - Complete Documentation

AI-friendly SEO generator for modern web frameworks - Now with enhanced Google site verification and automatic compatibility fixes for Vite React applications!

Overview

Vibe SEO is an AI-friendly SEO generator designed for modern web frameworks. It automatically detects your project structure, scans your pages, and generates comprehensive SEO files including sitemaps, robots.txt, meta tags, and JSON-LD structured data.

✨ What's New in v0.6.18

🔧 Enhanced Google Site Verification: Improved HTML template injection during build process
🚀 Fixed Template Literal Issues: Resolved JavaScript compilation errors
🎯 Better Error Handling: More robust validation and fallback mechanisms
🤖 AI-Friendly by Design: Optimized for modern AI crawlers and traditional search engines
📊 Comprehensive Debugging: See exactly what's being generated and fixed
🌐 Multilingual Support: Full hreflang implementation for international SEO
✅ Google Search Console Integration: Streamlined verification process with automatic tag injection

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

Quick Setup

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.

Key Features

🔧 Automatic Compatibility Fixes

Automatically handles all compatibility issues:

• Vite Configuration updates
• React Router fixes
• Server configuration (vercel.json, netlify.toml)
• File management to public/ directory
• MIME type headers for static files

🎯 Perfect for Lovable Stack

Optimized for modern development:

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

• GPTBot (OpenAI)
• ClaudeBot (Anthropic)
• PerplexityBot (Perplexity)
• Meta-ExternalAgent (Meta AI)
• Applebot (Apple Intelligence)
• Plus traditional search engines

📄 Complete SEO Suite

Generates all essential SEO files:

• sitemap.xml with hreflang annotations
• robots.txt with AI-friendly configurations
• Meta tag files for each page
• JSON-LD structured data
• Search engine verification tags

🔧 Enhanced Google Site Verification

Automatic Injection Process

• Configuration Reading: Reads verification tokens from seo.config.yaml
• Token Validation: Validates token format (letters, numbers, hyphens, underscores)
• HTML Injection: Injects meta tags into HTML <head> section
• Build Integration: Ensures tags persist through production builds
• Error Handling: Provides clear error messages for invalid tokens

Verification Tag Examples

Google Search Console

google-verification.html

<meta name="google-site-verification" content="your-verification-token" />

Bing Webmaster Tools

bing-verification.html

<meta name="msvalidate.01" content="your-bing-verification-token" />

Yandex Webmaster

yandex-verification.html

<meta name="yandex-verification" content="your-yandex-verification-token" />

pinterest-verification.html

<meta name="p:domain_verify" content="your-pinterest-verification-token" />

Manual Verification

If automatic injection fails, you can manually add verification tags:

manual-verification.html

<head>
  <meta name="google-site-verification" content="your-verification-token" />
  <meta name="msvalidate.01" content="your-bing-verification-token" />
</head>

Installation

Global Installation (Recommended)

npm install -g vibe-seo

npx vibe-seo

Local Installation

npm install vibe-seo --save-dev

npx vibe-seo

Quick Start

1. Initialize Your 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

2. Configure Your Site

Edit ./seo/config/seo.config.yaml:

seo.config.yaml

site:
  url: "https://yoursite.com"
  name: "Your Company"
  description: "Your site description"
  language: "en"

seo:
  titleTemplate: "{title} | {siteName}"
  descriptionTemplate: "{description}"

verification:
  google: "your-google-verification-token"

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

🔧 Automatic Fixes Applied

For Vite React Applications

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

1. Updates Vite Configuration

vite.config.ts

// 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. Fixes React Router

App.tsx

// Automatically added to your App.tsx
React.useEffect(() => {
  const path = window.location.pathname;
  if (path === '/robots.txt' || path === '/sitemap.xml') {
    window.location.replace(`${window.location.origin}${path}`);
  }
}, []);

3. Creates Server Configuration

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

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:

npx vibe-seo-init --framework nextjs-app --force

vibe-seo-gen

Generate SEO files from your configuration.

Generate All Files

npx vibe-seo-gen all

Generate Specific Files

npx vibe-seo-gen sitemap robots meta pages

Options:

• -c, --config <path> - Custom config file path
• -o, --output <path> - Custom output directory
• --debug - Enable detailed logging

Examples:

npx vibe-seo-gen all --debug --config ./custom-config.yaml

Configuration Guide

Complete Configuration Example

seo.config.yaml

site:
  url: "https://yoursite.com"
  name: "Your Company"
  description: "Complete web solutions provider"
  language: "en"
  locale: "en_US"

seo:
  titleTemplate: "{title} | {siteName}"
  descriptionTemplate: "{description} - {siteName}"
  imageTemplate: "{siteUrl}/og-images/{slug}.jpg"

verification:
  google: "your-google-verification-token"
  bing: "your-bing-verification-token"
  yandex: "your-yandex-verification-token"

languages:
  - code: "en"
    name: "English"
    url: "https://yoursite.com"
  - code: "es"
    name: "Spanish"
    url: "https://yoursite.com/es"
  - code: "fr"
    name: "French"
    url: "https://yoursite.com/fr"

sitemap:
  changefreq: "weekly"
  priority: 0.8
  excludePaths:
    - "/admin"
    - "/private"

Site Information

Essential site details used throughout all generated files:

• site.url (required) - Your website's base URL
• site.name (required) - Your site/company name
• site.description - Description used in meta tags and fallbacks
• site.language - Primary language code (default: "en")
• site.locale - Locale for Open Graph (default: "en_US")

SEO Templates

Customize how titles and descriptions are generated:

• seo.titleTemplate - Template with placeholders like {title} | {siteName}
• seo.descriptionTemplate - Template for meta descriptions
• seo.imageTemplate - Template for Open Graph images

Available Placeholders:

• {title} - Generated page title
• {siteName} - Your site name
• {siteUrl} - Your site URL
• {description} - Generated description
• {url} - Current page URL
• {slug} - URL-friendly page identifier

Search Engine Verification

Add verification tokens from webmaster tools:

verification.yaml

verification:
  google: "your-google-verification-token"
  bing: "your-bing-verification-token"
  yandex: "your-yandex-verification-token"

How to get Google verification token:

1. Go to Google Search Console
2. Add your property
3. Choose "HTML tag" verification method
4. Copy the content value from the provided meta tag
5. Add it to your config as verification.google

Multilingual SEO

Setting Up Multiple Languages

Configure international SEO with automatic hreflang generation:

languages.yaml

languages:
  - code: "en"
    name: "English"
    url: "https://yoursite.com"
  - code: "es"
    name: "Spanish"
    url: "https://yoursite.com/es"
  - code: "fr"
    name: "French"
    url: "https://yoursite.com/fr"

URL Structure Options

Subdirectories (Recommended):

subdirectories.yaml

languages:
  - code: "en"
    url: "https://yoursite.com"
  - code: "es"
    url: "https://yoursite.com/es"

Subdomains:

subdomains.yaml

languages:
  - code: "en"
    url: "https://en.yoursite.com"
  - code: "es"
    url: "https://es.yoursite.com"

Country Code Top-Level Domains (ccTLD):

cctld.yaml

languages:
  - code: "en-US"
    url: "https://yoursite.com"
  - code: "en-GB"
    url: "https://yoursite.co.uk"

Generated Hreflang Output

In Meta Tags:

meta-tags-hreflang.html

<link rel="alternate" hreflang="en" href="https://yoursite.com/about" />
<link rel="alternate" hreflang="es" href="https://yoursite.com/es/about" />
<link rel="alternate" hreflang="x-default" href="https://yoursite.com/about" />

In Sitemap:

sitemap-hreflang.xml

<url>
  <loc>https://yoursite.com/about</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://yoursite.com/about"/>
  <xhtml:link rel="alternate" hreflang="es" href="https://yoursite.com/es/about"/>
  <xhtml:link rel="alternate" hreflang="x-default" href="https://yoursite.com/about"/>
</url>

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}

Template Customization:

template-customization.yaml

seo:
  titleTemplate: "{title} | {siteName}"
  descriptionTemplate: "{title} - {description} | {siteName}"

Deployment & Integration

Next.js Projects

Vibe SEO automatically copies files to your public/ directory:

npx vibe-seo-gen all

Files are copied to public/robots.txt, public/sitemap.xml, etc.

Deployment Checklist

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

verification-commands.sh

curl https://yoursite.com/robots.txt
curl https://yoursite.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 all --debug

Solutions:

• Run npx vibe-seo-init --force to re-detect framework
• Check that your pages are in expected directories
• Manually specify framework: --framework nextjs-app

"Missing required config field"

Error: Missing required config field: site.name

Solution:

Ensure your config file has all required fields:

required-fields.yaml

site:
  url: "https://yoursite.com"  # Required
  name: "Your Company"         # Required

Generated Files Not Loading

• Check file permissions: Ensure files are readable
• Verify hosting config: Confirm static files are served
• Clear cache: CDN and browser caches
• Test URLs directly:

test-urls.sh

curl https://yoursite.com/robots.txt
curl https://yoursite.com/sitemap.xml

Google Search Console Verification Fails

• Check meta tag placement: Must be in <head> section
• Verify token accuracy: Copy exact content value
• Test accessibility: Ensure homepage is publicly accessible
• 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

Getting Help

Common Debug Commands:

debug-commands.sh

npx vibe-seo-init --force --debug
npx vibe-seo-gen all --debug
npx vibe-seo-gen sitemap --debug

Advanced Usage

Custom Page Configuration

Override defaults for specific pages:

custom-pages.yaml

pages:
  "/about":
    title: "About Our Company"
    description: "Learn more about our mission and values"
    priority: 0.9
  "/contact":
    title: "Contact Us"
    changefreq: "monthly"

Multiple Sitemaps

For large sites:

multiple-sitemaps.yaml

sitemap:
  split: true
  maxUrls: 50000
  sitemaps:
    - name: "main"
      includes: ["/", "/about", "/contact"]
    - name: "blog"
      includes: ["/blog/*"]
    - name: "products"
      includes: ["/products/*"]

Environment-Specific Configs

environment-configs.sh

npx vibe-seo-gen all --config ./seo.production.yaml
npx vibe-seo-gen all --config ./seo.staging.yaml

Programmatic Usage

programmatic-usage.js

const { generateSEO } = require('vibe-seo');

generateSEO({
  configPath: './seo.config.yaml',
  outputPath: './output',
  debug: true
}).then(() => {
  console.log('SEO files generated successfully!');
});

Version History

v0.6.18 (Latest) ⭐

✅ Fixed template literal syntax errors
✅ Enhanced Google site verification tag injection
✅ Improved HTML template modification during build
✅ Better verification token validation and error handling

v0.6.17

✅ Enhanced Google site verification tag injection
✅ Improved HTML template modification during build
✅ Better verification token validation and error handling
✅ Comprehensive fix for Lovable project verification issues

v0.6.16

✅ Enhanced error handling and plugin conflict detection
✅ Improved import validation and syntax error recovery
✅ Better documentation and troubleshooting guidance
✅ Automatic backup creation and manual setup instructions

v0.6.15

✅ Updated to use @vitejs/plugin-react-swc
✅ Enhanced SEOMetaTags component for dynamic meta tag injection
✅ Improved Vite plugin with better error handling
✅ Fixed import conflicts and TypeScript declarations

v0.6.14

✅ Enhanced Google Search Console verification integration
✅ Automatic meta tag injection during build process
✅ Created SEOMetaTags React component for dynamic injection
✅ Improved Vite plugin with transformIndexHtml hook

v0.6.13

✅ Fixed 404 errors for robots.txt and sitemap.xml in production
✅ Enhanced file copying logic with multiple source directories
✅ Improved placeholder file creation to prevent 404s
✅ Removed problematic generateBundle function causing production issues

v0.6.12

✅ Enhanced Vite plugin with @ts-ignore for type declarations
✅ Added configResolved hook for better logging
✅ Improved error handling with try-catch blocks
✅ Added comprehensive troubleshooting documentation

v0.6.11

✅ Fixed seo.config.yaml generation with comprehensive comments
✅ Enhanced configuration file with detailed documentation
✅ Improved user experience with self-documenting config files
✅ Added troubleshooting section for common issues

v0.6.10

✅ Multi-layer solution for robots.txt download issue
✅ Enhanced Vite plugin with proper MIME types and charset
✅ Updated server configurations with Cache-Control headers
✅ Added client-side fallback component for static file serving

v0.6.9

✅ Implemented comprehensive robots.txt download fix
✅ Enhanced Vite plugin with generateBundle for production builds
✅ Updated vercel.json and netlify.toml with proper MIME types
✅ Added StaticFileHandler component as client-side fallback

v0.6.8

✅ Enhanced Vite React compatibility with robust error handling
✅ Improved Vite config modification with syntax validation
✅ Created vite-seo-plugin.d.ts for TypeScript support
✅ Better import placement and array syntax error recovery

v0.6.7

✅ Fixed "no pages detected" issue in Lovable projects
✅ Improved React page scanning to prioritize /src/pages/
✅ Enhanced framework detection for Vite React projects
✅ Better URL conversion from file paths

v0.6.6

✅ Implemented loadConfigWithFrameworkDetection for auto-correction
✅ Fixed framework detection (static → react)
✅ Enhanced console logging for better debugging
✅ Improved configuration file updates

v0.6.5

✅ Replaced flawed React.useEffect redirect with vite-seo-plugin.js
✅ Created custom Vite plugin for proper static file handling
✅ Enhanced MIME type handling to prevent download issues
✅ Improved development server middleware

v0.6.4

✅ Implemented fixViteReactCompatibility for automatic fixes
✅ Automatic Vite config, App.tsx, and server config modifications
✅ Created deployment guides and configuration templates
✅ Enhanced file copying to public directory

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

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

Performance

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

Maintenance

• Update after changes: Run generation after config updates
• Monitor Search Console: Check for crawl errors
• Validate periodically: Ensure files remain accessible
• Version control configs: Track SEO configuration changes

Google Site Verification

• Add verification tokens: Configure in seo.config.yaml
• Test injection: Check page source for meta tags
• Verify in Search Console: Confirm successful verification
• Monitor regularly: Ensure tags persist through updates

Contributing

Vibe SEO is open source and welcomes contributions. Visit our GitHub repository for:

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

Ready to optimize your SEO? Start with npm install -g vibe-seo@0.6.18 and experience the future of automated, AI-friendly SEO generation with enhanced Google site verification! 🚀

License

MIT License - Free for commercial and personal use.

Documentation

Vibe SEO v0.6.18 - Complete Documentation

Overview

✨ What's New in v0.6.18

🚀 One-Command Solution

Quick Setup

Install

Initialize

Generate all SEO files with automatic fixes

Key Features

🔧 Automatic Compatibility Fixes

🎯 Perfect for Lovable Stack

🤖 AI-Friendly by Design

📄 Complete SEO Suite

🔧 Enhanced Google Site Verification

Automatic Injection Process

Verification Tag Examples

Google Search Console

Bing Webmaster Tools

Yandex Webmaster

Pinterest

Manual Verification

Installation

Global Installation (Recommended)

Local Installation

Quick Start

1. Initialize Your Project

2. Configure Your Site

3. Generate SEO Files (One Command)

🔧 Automatic Fixes Applied

For Vite React Applications

1. Updates Vite Configuration

2. Fixes React Router

3. Creates Server Configuration

4. Copies Files to Public Directory

Commands Reference

vibe-seo-init

Options:

Examples:

vibe-seo-gen

Generate All Files

Generate Specific Files

Options:

Examples:

Configuration Guide

Complete Configuration Example

Site Information

SEO Templates

Search Engine Verification

Multilingual SEO

Setting Up Multiple Languages

URL Structure Options

Subdirectories (Recommended):

Subdomains:

Country Code Top-Level Domains (ccTLD):

Generated Hreflang Output

In Meta Tags:

In Sitemap:

Smart Content Generation

Intelligent Title Generation

Dynamic Description Generation

With site description configured:

Without site description:

Template Customization:

Deployment & Integration

Next.js Projects

Deployment Checklist

Popular Hosting Platforms

Troubleshooting

Common Issues

"No Pages Detected"

"Missing required config field"

Generated Files Not Loading

Google Search Console Verification Fails

Debug Mode

Getting Help

Advanced Usage

Custom Page Configuration

Multiple Sitemaps

Environment-Specific Configs