GEO AI Shopify

Shopify embedded app for AI Search Optimization. Native metafields, App Proxy, multilingual support, zero-config setup.

Installation

For development and self-hosting:

git clone https://github.com/madeburo/geo-ai-shopify.git
cd geo-ai-shopify
npm install
npx prisma generate
npx prisma migrate dev
shopify app dev

Create a .env file with your Shopify credentials:

SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret
ENCRYPTION_KEY=64_character_hex_string
DATABASE_URL=file:dev.db
SCOPES=read_products,write_products,read_content,write_content,read_themes,read_metafields,write_metafields,read_translations
SHOPIFY_APP_URL=https://your-app-url

Generate an encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Features

• llms.txt and llms-full.txt served via Shopify App Proxy at /apps/llms/
• AI metadata stored as Shopify Metafields (namespace: geo_ai) on products, pages, and collections
• One-click AI description generation via Claude or OpenAI
• Bulk generation for up to 50 resources (batched by 5)
• Theme Extension injecting meta tags and JSON-LD into storefront head
• Per-locale llms.txt via Shopify Translations API
• GDPR-compliant crawl tracking with SHA-256 IP anonymization
• Setup wizard and onboarding checklist

App Proxy endpoints

The app serves llms.txt content through Shopify App Proxy — accessible from your storefront domain:

GET /apps/llms/              → llms.txt
GET /apps/llms/{locale}      → llms.txt (per locale)
GET /apps/llms/full          → llms-full.txt
GET /apps/llms/full/{locale} → llms-full.txt (per locale)

Admin API endpoints

GET  /api/status
POST /api/regenerate
GET  /api/settings
POST /api/settings
POST /api/ai-generate
POST /api/ai-bulk

Configuration

Navigate to the Settings tab in the embedded app to configure:

• Content Types — toggle products, pages, collections, blog posts
• Bot Rules — allow or disallow specific AI crawlers
• Cache — set regeneration frequency (1, 6, 12, 24, or 48 hours)
• AI Generation — provider, API key, model, and prompt template
• Advanced — multilingual, crawl tracking

Security

• HMAC-SHA256 signature verification on App Proxy routes using constant-time comparison
• Mandatory SHOPIFY_API_SECRET — app refuses to verify signatures with an empty secret
• Shop parameter validation on public API endpoints (must match *.myshopify.com)
• Rate limiting on public API endpoints (60 req/min per shop) with Retry-After header
• AES-256-GCM encrypted API key storage

Requirements

• Node.js 20 or higher
• Shopify Partner account
• Shopify CLI