🧠 AI-SEO (NPM Package)

AI-SEO is a minimal, zero-dependency JavaScript utility for injecting AI-friendly JSON-LD structured data into your pages. Optimized for AI-powered search engines like ChatGPT, Bing Chat, Google Gemini, and traditional SEO.

💡 Looking for a CDN/no-install version? Check out easy-ai-seo for direct script tag usage!

✨ Features

• ✅ Zero dependencies - Minimal footprint
• ✅ SSR/SSG safe - Works with Next.js, Nuxt, and other frameworks
• ✅ TypeScript support - Full type definitions included
• ✅ Flexible API - Custom schemas or simplified FAQ setup
• ✅ Framework agnostic - Works with React, Vue, Svelte, vanilla JS
• ✅ Tree-shakeable - Only bundle what you use
• ✅ Schema.org compliant - Follows structured data standards
• ✅ Multi-runtime support - Works with Node.js, Bun, and Deno
• ✅ Enhanced error handling - Comprehensive browser detection and error messages
• ✅ Debug mode - Development-friendly logging and validation warnings
• ✅ Duplicate prevention - Smart detection and prevention of duplicate schemas
• ✅ Schema validation - Built-in validation for common schema errors
• ✅ Cleanup utilities - Methods to remove and manage injected schemas

📦 Installation

Node.js / npm

npm install ai-seo

Bun

bun add ai-seo

Deno

import { initSEO, addFAQ } from "npm:ai-seo";

Minimum Runtime Versions:

• Node.js: >=14
• Bun: >=0.6.0
• Deno: >=1.30.0

🚀 Quick Start

Simple FAQ Setup

import { addFAQ } from 'ai-seo';

// One-liner for FAQ pages
addFAQ('What is AI SEO?', 'AI SEO optimizes content for AI-powered search engines.');

Enhanced Usage with Debug Mode

import { initSEO, removeSchema, listSchemas } from 'ai-seo';

// Enhanced initialization with debugging and validation
const schemaElement = initSEO({
  pageType: 'FAQPage',
  questionType: "How do I use the ai-seo npm package?",
  answerType: "Install the package with npm, import initSEO, and call it with your structured content.",
  debug: true,           // Enable development logging
  validate: true,        // Validate schema before injection (default)
  allowDuplicates: false, // Prevent duplicate schemas (default)
  id: 'my-faq-schema'    // Optional: specify custom ID for tracking
});

// Later, you can remove the schema
if (schemaElement) {
  removeSchema('my-faq-schema');
}

// Or list all current schemas
const allSchemas = listSchemas();
console.log('Current schemas:', allSchemas);

Custom Schema with Validation

import { initSEO } from 'ai-seo';

// Inject any custom JSON-LD schema with validation
initSEO({
  schema: {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "My Product",
    "description": "Product description..."
  },
  debug: true,      // See validation results in console
  validate: true    // Ensure schema is valid before injection
});

🔧 Framework Examples

React/Next.js

import React, { useEffect } from 'react';
import { addFAQ } from 'ai-seo';

const FAQPage = () => {
  useEffect(() => {
    addFAQ(
      'How fast is this package?',
      'Ultra-fast! Zero dependencies and minimal code footprint.'
    );
  }, []);

  return <h1>FAQ Page</h1>;
};

Vue 3

<script setup>
import { onMounted } from 'vue';
import { addFAQ } from 'ai-seo';

onMounted(() => {
  addFAQ('Is this Vue compatible?', 'Yes! Works with any framework.');
});
</script>

<template>
  <h1>Vue FAQ Page</h1>
</template>

Svelte

<script>
import { onMount } from 'svelte';
import { addFAQ } from 'ai-seo';

onMount(() => {
  addFAQ('Does this work with Svelte?', 'Absolutely! Framework agnostic design.');
});
</script>

<h1>Svelte FAQ Page</h1>

Bun

// Works seamlessly with Bun's fast runtime
import { addFAQ } from 'ai-seo';

addFAQ('Is Bun supported?', 'Yes! Ultra-fast performance with Bun runtime.');

Deno

// Import from npm: registry
import { initSEO } from "npm:ai-seo";

initSEO({
  pageType: 'FAQPage',
  questionType: 'Does this work with Deno?',
  answerType: 'Absolutely! Secure by default with Deno.'
});

📋 API Reference

initSEO(options)

Enhanced schema injection with comprehensive options.

Returns: HTMLScriptElement | null - The injected script element or null if injection fails

addFAQ(question, answer, options?)

Simplified helper for FAQ setup with optional enhanced features.

Returns: HTMLScriptElement | null

Schema Management Functions

removeSchema(schemaId)

Remove a specific schema by its ID.

Parameters: schemaId (string) - The ID of the schema to remove
Returns: boolean - True if successfully removed, false otherwise

removeAllSchemas()

Remove all ai-seo injected schemas from the page.

Returns: number - Count of schemas that were removed

listSchemas()

Get information about all currently injected schemas.

Returns: SchemaInfo[] - Array of schema information objects

interface SchemaInfo {
  id: string;
  type: string;        // Schema @type
  timestamp: number;   // Injection timestamp
  element: HTMLScriptElement;
}

getSchema(schemaId)

Retrieve full schema data by ID.

Parameters: schemaId (string) - The ID of the schema to retrieve
Returns: SchemaRegistryEntry | null - Schema data or null if not found

interface SchemaRegistryEntry {
  element: HTMLScriptElement;
  schema: Record<string, any>;  // The JSON-LD schema object
  timestamp: number;
}

🧪 Output Example

The package injects this JSON-LD into your page head:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "What is AI SEO?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "AI SEO optimizes content for AI-powered search engines."
    }
  }]
}

📈 Release Notes

v1.1.0 (Latest)

• 🚀 Enhanced Error Handling - Comprehensive browser detection and detailed error messages
• 🐛 Debug Mode - Development-friendly console logging with debug: true option
• 🔒 Duplicate Prevention - Smart detection and prevention of duplicate schema injection
• ✅ Schema Validation - Built-in client-side validation for common schema errors
• 🧹 Cleanup Utilities - New functions: removeSchema(), removeAllSchemas(), listSchemas(), getSchema()
• 📊 Schema Registry - Internal tracking system for better schema management
• 🆔 Custom IDs - Optional custom ID assignment for schema tracking
• 🎛️ Enhanced Options - New options: debug, validate, allowDuplicates, id

v1.0.4

• ✨ Multi-runtime support - Now officially supports Node.js, Bun, and Deno
• 📦 Enhanced package metadata - Updated keywords and engine specifications
• 🗺️ Roadmap published - Clear development path for future features

v1.0.3

• 🔄 Version bump - Internal package updates

v1.0.2

• ✨ New addFAQ() helper - One-liner for FAQ setup
• 🛡️ SSR/SSG safety - Automatic browser environment detection
• 🔧 Flexible schema support - Custom JSON-LD schemas
• 📦 Better packaging - Added TypeScript definitions
• 🎯 Default values - pageType defaults to 'FAQPage'
• 🔄 Return values - Script element returned for cleanup
• 📚 Improved docs - Better examples and API reference

v1.0.1

• 🐛 Bug fixes and stability improvements

v1.0.0

• 🎉 Initial release with core FAQ functionality

🔍 Related Projects

• easy-ai-seo - CDN version for direct script tag usage
• Perfect for projects that don't use npm or prefer CDN delivery

🛠️ Development

# Clone the repository
git clone https://github.com/Veeeetzzzz/ai-seo-npm-package.git

# Install dependencies (there are none! 🎉)
cd ai-seo-npm-package

# The package is ready to use

✅ Validation Tools

Verify your structured data with:

• Google Rich Results Test
• Schema.org Validator
• Google Search Console

🧪 AI Testing

Test if AI models can understand your content:

Prompt: "Can you summarize the content from [your-website.com]? What questions does it answer?"

Try this in ChatGPT, Gemini, or Bing Chat to verify AI readability.

🗺️ Roadmap

✅ Short Term (v1.1.x) - Core Improvements - COMPLETED

• [x] Enhanced Error Handling - Better browser detection and error messages
• [x] Debug Mode - Development-friendly logging and validation warnings
• [x] Duplicate Prevention - Check for existing schemas before injection
• [x] Basic Schema Validation - Client-side validation for common schema errors
• [x] Cleanup Utilities - Methods to remove injected schemas

🔧 Medium Term (v1.2.x) - Extended Functionality

• [ ] Extended Schema Helpers - Product, Article, LocalBusiness, Event schemas
• [ ] Multiple Schema Support - Inject multiple schemas in a single call
• [ ] Server-Side Utilities - SSR/SSG schema generation helpers
• [ ] Test Suite - Comprehensive testing with Vitest
• [ ] Bundle Optimization - Tree-shaking improvements and size analysis

🎯 Long Term (v2.x) - Advanced Features

• [ ] Schema Composer API - Fluent interface for complex schema building
• [ ] Framework Integrations - React hooks, Vue composables, Svelte stores
• [ ] CLI Tool - Command-line schema validation and generation
• [ ] Performance Monitoring - Schema effectiveness tracking
• [ ] Visual Schema Builder - Separate package for GUI schema creation

🌟 Future Considerations

• [ ] AI Content Analysis - Automatic schema suggestions based on page content
• [ ] Schema Templates - Pre-built templates for common industries
• [ ] A/B Testing Support - Schema variant testing capabilities
• [ ] Analytics Integration - Built-in tracking for schema performance

💡 Have ideas? Submit feature requests to help shape the roadmap!

📘 License

MIT License. Free for personal and commercial use.

🙋 Support & Contributions

• 🐛 Report bugs
• 💡 Request features
• 🤝 Contribute

Created with ♥ to help the web evolve with AI-driven search.