Spyglasses for Astro

The Spyglasses middleware for Astro enables you to detect AI Agents, bots, crawlers, and referrers in your Astro web applications. It provides comprehensive AI SEO, shows you when your site features in ChatGPT, Claude, Perplexity, and other AI assistant platforms, and can block AI model training crawlers.

Key Features

• High Performance: Runtime pattern loading with caching-friendly fetch
• Bot Detection: Identifies and can block AI crawlers and model trainers
• AI Referrer Tracking: Tracks human visitors coming from AI platforms
• Serverless Ready: Works well on serverless deployments

Installation

npm install @spyglasses/astro
# or
yarn add @spyglasses/astro
# or
pnpm add @spyglasses/astro

Quick Start

1. Create an Astro middleware file src/middleware.ts and register it in your astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { createSpyglassesMiddleware } from '@spyglasses/astro';

const spyglasses = createSpyglassesMiddleware({
  apiKey: process.env.SPYGLASSES_API_KEY,
  debug: process.env.SPYGLASSES_DEBUG === 'true'
});

export default defineConfig({
  server: {
    middleware: [spyglasses]
  }
});

If you use Astro's file-based middleware, add src/middleware.ts:

// src/middleware.ts
import { createSpyglassesMiddleware } from '@spyglasses/astro';
export const onRequest = createSpyglassesMiddleware({
  apiKey: process.env.SPYGLASSES_API_KEY,
  debug: process.env.SPYGLASSES_DEBUG === 'true'
});

2. Add environment variables:

SPYGLASSES_API_KEY=your_api_key_here
SPYGLASSES_CACHE_TTL=86400
SPYGLASSES_DEBUG=true

The middleware will now detect and log AI bots and AI referrers. Blocking rules are managed in the Spyglasses dashboard.

SSR setup (required for middleware in production)

Astro middleware runs only when the site is server-rendered (SSR). For middleware to execute on every request in production, enable SSR with a server adapter and set output: 'server':

1. Install a server adapter (Node example):

npx astro add node

2. Update astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' })
});

Astro maintains official adapters for Node.js, Netlify, Vercel, and [Cloudflare]https://docs.astro.build/en/guides/integrations-guide/cloudflare/. You can find both official and community adapters in their integrations directory. Choose the one that corresponds to your deployment environment.

Notes:

• If you prefer static by default, you can opt-in per route with export const prerender = false on specific pages/endpoints. This will cause Spyglasses to only track bot visits on those pages.

How It Works

Patterns and property settings are fetched at runtime and cached by the platform, refreshed on TTL expiry.

Usage Examples

See the examples directory for:

• Basic integration
• Middleware chaining

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SPYGLASSES_API_KEY | Your Spyglasses API key | Required | | SPYGLASSES_CACHE_TTL | Cache duration in seconds | 86400 | | SPYGLASSES_DEBUG | Enable debug logging | false | | SPYGLASSES_COLLECTOR_ENDPOINT | Override collector endpoint | Optional | | SPYGLASSES_PATTERNS_ENDPOINT | Override patterns endpoint | Optional |

Configuration Options

Same as the Next.js package: apiKey, debug, excludePaths, collectEndpoint, patternsEndpoint.

Performance note

Enabling SSR (output: 'server') adds per-request server rendering compared to Astro’s default static output, which can add small latency and potential cold starts depending on your hosting adapter/runtime. For the lowest latency and fully static pages, consider only enabling SSR on the routes that need Spyglasses, or use our Cloudflare Worker integration instead if you want edge execution with minimal overhead.

License

MIT License - see LICENSE for details.