Lighthouse Configuration

Configure which pages get audited, how URLs are resolved, and where the API route lives.

Full Config Example

sanity.config.ts

import { defineConfig } from 'sanity'
import { lighthousePlugin } from 'sanity-plugin-analytics'

export default defineConfig({
  // ...
  plugins: [
    lighthousePlugin({
      // URL of your /api/pagespeed proxy route
      apiUrl: '/api/pagespeed',        // default

      // Public origin of your website — required for URL discovery
      siteUrl: 'https://mysite.com',

      // Map Sanity document types to their public URLs
      documentTypes: [
        {
          type: 'post',
          slugField: 'slug',           // dot-path to slug field (default: 'slug')
          pathPrefix: '/blog',         // prepended before the slug
          titleField: 'title',         // dot-path for display name (default: 'title')
        },
        {
          type: 'page',
          slugField: 'slug',
        },
        {
          type: 'product',
          slugField: 'slug.current',   // nested slug object
          pathPrefix: '/products',
        },
      ],

      // Optional: fully custom URL resolver (overrides documentTypes mapping)
      resolveUrl: (document, { siteUrl }) => {
        if (document._type === 'home') return siteUrl
        return null  // return null to skip this document
      },

      // Disable this tab/tool
      disabled: false,
    }),
  ],
})

Options Reference

Option	Type	Default	Description
`apiUrl`	`string`	`'/api/pagespeed'`	URL of the PageSpeed proxy route in your app.
`siteUrl`	`string`	`—`	Public site origin, e.g. https://example.com. Required for Fetch Remaining to work.
`documentTypes`	`LighthouseDocumentTypeConfig[]`	`—`	Array of document type mappings (see below).
`resolveUrl`	`(doc, ctx) => string \| null`	`—`	Custom URL resolver — takes precedence over documentTypes mapping.
`title`	`string`	`'Lighthouse'`	Tool title / toolbar label (used in 'separate' layout).
`name`	`string`	`'lighthouse'`	Tool name / URL route segment (used in 'separate' layout).
`disabled`	`boolean`	`false`	Hide the Lighthouse tool from the Sanity toolbar.

`LighthouseDocumentTypeConfig`

Each entry in documentTypes maps one Sanity document type to a URL pattern:

Field	Type	Default	Description
`type`	`string`	`—`	Sanity document type, e.g. 'post'.
`slugField`	`string`	`'slug'`	Dot-path to a slug string or slug object (with .current). E.g. 'slug.current' or just 'slug'.
`pathPrefix`	`string`	`''`	URL segment prepended before the slug, e.g. '/blog'.
`titleField`	`string`	`'title'`	Dot-path used as the display name in the dashboard.

URL Resolution Logic

When the dashboard clicks Fetch Remaining, it queries all unpublished documents of the configured types and resolves their URLs:

URL resolution example

// Given config:
siteUrl: 'https://mysite.com',
documentTypes: [{ type: 'post', slugField: 'slug', pathPrefix: '/blog' }]

// A document { _type: 'post', slug: { current: 'my-first-post' } }
// resolves to:
// → https://mysite.com/blog/my-first-post

// A document { _type: 'post', slug: 'about' }
// (string slug)
// → https://mysite.com/blog/about

Custom Resolver

For complex URL structures, use resolveUrl to take full control:

sanity.config.ts

lighthousePlugin({
  siteUrl: 'https://mysite.com',
  resolveUrl: (document, { siteUrl }) => {
    if (document._type === 'home') return siteUrl

    if (document._type === 'category') {
      const slug = (document.slug as any)?.current
      return slug ? `${siteUrl}/category/${slug}` : null
    }

    // Return null to skip this document
    return null
  },
})

Next step: Learn how the Lighthouse dashboard works →