Analytics
docs

Configuration

Configure plugin options — use the combined sanityAnalyticsPlugin or each sub-plugin independently.

Combined Plugin

sanityAnalyticsPlugin registers all three tools as a single “Analytics” entry in the Sanity toolbar:

sanity.config.ts
import { defineConfig } from 'sanity'
import { sanityAnalyticsPlugin } from 'sanity-plugin-analytics'

export default defineConfig({
  plugins: [
    sanityAnalyticsPlugin({
      title: 'Analytics',            // toolbar label (default)
      name: 'analytics',             // toolbar name (default)
      disabled: false,

      analytics: {
        apiUrl: '/api/analytics',    // default
        siteTitle: 'My Site',        // optional label in dashboard
        disabled: false,
      },

      searchConsole: {
        apiUrl: '/api/search-console', // default
        siteTitle: 'My Site',
        disabled: false,
      },

      lighthouse: {
        apiUrl: '/api/pagespeed',    // default
        siteUrl: 'https://mysite.com',
        documentTypes: [
          { type: 'post', slugField: 'slug', pathPrefix: '/blog' },
        ],
        disabled: false,
      },
    }),
  ],
})

Individual Plugins

Use individual plugins if you want separate toolbar entries or only need one tool:

sanity.config.ts
import {
  googleAnalyticsPlugin,
  searchConsolePlugin,
  lighthousePlugin,
} from 'sanity-plugin-analytics'

// Each plugin adds its own icon to the Sanity toolbar
plugins: [
  googleAnalyticsPlugin({ apiUrl: '/api/analytics' }),
  searchConsolePlugin({ apiUrl: '/api/search-console' }),
  lighthousePlugin({
    siteUrl: 'https://mysite.com',
    documentTypes: [{ type: 'post', slugField: 'slug', pathPrefix: '/blog' }],
  }),
]

Layout: Combined or Separate

By default (layout: 'combined') the plugin adds a single Analytics tool with in-page tabs for each section. Set layout: 'separate' to register a distinct Studio tool for each section instead — each gets its own top-nav entry, icon, and URL. Use the per-section name (URL segment) and title (label) to customise them:

sanity.config.ts
sanityAnalyticsPlugin({
  layout: 'separate',
  analytics: {
    name: 'traffic',      // → tool URL segment
    title: 'Traffic',     // → top-nav label
    apiUrl: '/api/analytics',
  },
  searchConsole: {
    name: 'search',
    title: 'Search',
    apiUrl: '/api/search-console',
  },
  // lighthouse omitted → Lighthouse tool is not registered
})

Show / hide rule: a section appears only when its key (analytics, searchConsole, lighthouse) is present and not disabled — in both layouts. As a convenience, if you pass no section keys at all, all three are shown.

Caching & Refresh

Analytics and Search Console responses are cached in-memory for 15 minutes, keyed by API URL, date range, and property. Switching date ranges or sections re-uses cached data instead of re-fetching, and concurrent requests for the same data are de-duplicated. The Refresh button (and adding a sitemap) bypasses the cache and forces a fresh fetch. The cache is per browser session and clears on studio reload.

SanityAnalyticsPluginConfig Reference

OptionTypeDefaultDescription
layout'combined' | 'separate''combined''combined' = one tabbed tool. 'separate' = a distinct Studio tool (own top-nav entry + URL) per section.
titlestring'Analytics'Toolbar label for the combined tool (layout: 'combined').
namestring'analytics'Tool name / URL segment for the combined tool (layout: 'combined').
disabledbooleanfalseDisable the entire plugin.
analyticsGoogleAnalyticsConfig—GA4 section. Provide the key to show it; omit to hide it.
searchConsoleSearchConsoleConfig—Search Console section. Provide the key to show it; omit to hide it.
lighthouseLighthouseConfig—Lighthouse section. Provide the key to show it; omit to hide it.

Environment-based Toggling

Show the dashboard only in production:

typescript
sanityAnalyticsPlugin({
  disabled: process.env.NODE_ENV !== 'production',
  analytics: {},
  searchConsole: {},
  lighthouse: { siteUrl: 'https://mysite.com' },
})

Zero Config

All API URL defaults work out of the box — just set environment variables:

typescript
// Minimal config — use all defaults
plugins: [
  sanityAnalyticsPlugin({
    analytics: {},
    searchConsole: {},
    lighthouse: { siteUrl: 'https://mysite.com' },
  }),
]

TypeScript

typescript
import type {
  SanityAnalyticsPluginConfig,
  GoogleAnalyticsConfig,
  SearchConsoleConfig,
  LighthouseConfig,
} from 'sanity-plugin-analytics'

For Lighthouse-specific options (documentTypes, resolveUrl, siteUrl) see the Lighthouse Configuration →