npm package: @spyglasses/astro
Description: AI SEO, bot detection, and blocking middleware for Astro applications
Author: Spyglasses
Latest version: 0.1.2

# Spyglasses for Astro

[![npm version](https://badge.fury.io/js/@spyglasses%2Fastro.svg)](https://www.npmjs.com/package/@spyglasses/astro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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](https://www.spyglasses.io), 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

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

```ts
// 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`:

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

```bash
npx astro add node
```

2) Update `astro.config.mjs`:

```ts
// 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](https://docs.astro.build/en/guides/integrations-guide/node/), [Netlify](https://docs.astro.build/en/guides/integrations-guide/netlify/), [Vercel](https://docs.astro.build/en/guides/integrations-guide/vercel/), and [Cloudflare]https://docs.astro.build/en/guides/integrations-guide/cloudflare/. You can find both [official and community adapters in their integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=adapters). Choose the one that corresponds to your [deployment environment](https://docs.astro.build/en/guides/deploy/).

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](/docs/platforms/cloudflare-worker) instead if you want edge execution with minimal overhead.

## License

MIT License - see `LICENSE` for details.