Next.js Integration

Spyglasses integrates seamlessly with Next.js applications through our official package. Follow these steps to set up Spyglasses in your Next.js project.

Installation

Install the package:
npm install @spyglasses/next
with yarn:
yarn add @spyglasses/next
with pnpm:
pnpm add @spyglasses/next
Add your API key: Create or update your .env.local file with your Spyglasses API key:
SPYGLASSES_API_KEY=your_api_key_here

Configuration

Create or update your middleware.ts file in the root of your project:

import { createSpyglassesMiddleware } from '@spyglasses/next';
 
export default createSpyglassesMiddleware({
  apiKey: process.env.SPYGLASSES_API_KEY,
  // Optional: override collector endpoint
  collectorEndpoint: process.env.SPYGLASSES_COLLECTOR_ENDPOINT,
  // Optional: enable debug logging
  debug: process.env.NODE_ENV === 'development'
});
 
// Configure matchers for the middleware
export const config = {
  matcher: [
    // Spyglasses matchers
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
}

Docker

If you deploy with Docker, set your API key in your Dockerfile or docker-compose:

Dockerfile:

ENV SPYGLASSES_API_KEY=your_api_key_here

docker-compose:

services:
  web:
    environment:
      - SPYGLASSES_API_KEY=your_api_key_here

Environment Variables at Runtime

For platforms that inject environment variables at runtime, you can reference them directly in your middleware:

export default createSpyglassesMiddleware({
  apiKey: process.env.SPYGLASSES_API_KEY,
  collectorEndpoint: process.env.SPYGLASSES_COLLECTOR_ENDPOINT,
  debug: process.env.NODE_ENV === 'development'
});

Wrapping Existing Middleware

If you have existing middleware, you can compose it with Spyglasses in two ways:

1. Middleware Chaining (Recommended)

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { createSpyglassesMiddleware } from '@spyglasses/next'
 
const spyglassesMiddleware = createSpyglassesMiddleware({
  apiKey: process.env.SPYGLASSES_API_KEY,
})
 
async function existingMiddleware(request: NextRequest) {
  // Your custom logic here
  return NextResponse.next()
}
 
export async function middleware(request: NextRequest) {
  // Run Spyglasses middleware first
  await spyglassesMiddleware(request);
  // Then run your middleware
  return existingMiddleware(request)
}
 
export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
    '/protected/:path*',
  ],
}

2. Middleware Composition (Advanced)

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { createSpyglassesMiddleware } from '@spyglasses/next'
 
const spyglassesMiddleware = createSpyglassesMiddleware({
  apiKey: process.env.SPYGLASSES_API_KEY,
})
 
async function existingMiddleware(request: NextRequest) {
  // Your custom logic here
  return NextResponse.next()
}
 
export async function middleware(request: NextRequest) {
  // Run both middlewares in sequence
  const [spyglassesResponse, existingResponse] = await Promise.all([
    spyglassesMiddleware(request),
    existingMiddleware(request),
  ])
 
  if (spyglassesResponse?.status === 403) {
    return spyglassesResponse // Block bot traffic
  }
  if (existingResponse?.status === 401) {
    return existingResponse // Handle unauthorized access
  }
  return NextResponse.next()
}
 
export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
    '/protected/:path*',
  ],
}

Tip: Use chaining unless you know you need composition.

Deployment

When deploying your Next.js application, make sure to add your Spyglasses API key to your environment variables:

Vercel

Go to Project Settings > Environment Variables
Add SPYGLASSES_API_KEY
Deploy to apply changes

Netlify

Go to Site Settings > Build & Deploy > Environment
Add SPYGLASSES_API_KEY
Trigger a new deploy

AWS Amplify

Go to App Settings > Environment Variables
Add SPYGLASSES_API_KEY
Redeploy your application

After deploying your application with Spyglasses, you can verify the installation by checking your Spyglasses dashboard. If everything is set up correctly, you should start seeing data from your Next.js application.