@pagebridge/sanity

Sanity Studio v3 plugin for PageBridge. Provides document schemas, UI components, and tools for viewing search performance data and managing content refresh tasks.

Installation

pnpm add @pagebridge/sanity

Setup

1. Add the Plugin

In your sanity.config.ts:

import { defineConfig } from "sanity";
import { pageBridgePlugin } from "@pagebridge/sanity";

export default defineConfig({
  // ... other config
  plugins: [
    pageBridgePlugin({
      contentTypes: ["post", "page"], // Document types to track
    }),
  ],
});

2. Add the Structure Resolver

To display the Performance pane on your content documents:

import { defineConfig } from "sanity";
import { structureTool } from "sanity/structure";
import {
  pageBridgePlugin,
  createPageBridgeStructureResolver,
} from "@pagebridge/sanity";

export default defineConfig({
  // ... other config
  plugins: [
    structureTool({
      structure: createPageBridgeStructureResolver({
        contentTypes: ["post", "page"],
      }),
    }),
    pageBridgePlugin({
      contentTypes: ["post", "page"],
    }),
  ],
});

Document Schemas

The plugin registers three document types:

gscSite

Represents a Google Search Console property.

| Field | Type | Description | | ------------- | -------- | -------------------------------------------- | | siteUrl | string | GSC site URL (e.g., sc-domain:example.com) | | slug | slug | URL-friendly identifier | | defaultLocale | string | Default locale (default: "en") | | pathPrefix | string | Path prefix for URL matching (e.g., /blog) | | lastSyncedAt | datetime | Last sync timestamp (read-only) |

gscSnapshot

Performance metrics snapshot linked to content documents.

| Field | Type | Description | | -------------- | --------- | ------------------------------- | | site | reference | Reference to gscSite | | page | string | Page URL | | linkedDocument | reference | Matched content document | | period | string | last7, last28, or last90 | | clicks | number | Total clicks | | impressions | number | Total impressions | | ctr | number | Click-through rate | | position | number | Average position | | topQueries | array | Top search queries with metrics | | fetchedAt | datetime | When data was fetched | | indexStatus | object | Google index status details |

gscRefreshTask

Content refresh task with decay signal information.

| Field | Type | Description | | -------------- | --------- | --------------------------------------------------------- | | site | reference | Reference to gscSite | | linkedDocument | reference | Content document needing refresh | | reason | string | position_decay, low_ctr, impressions_drop, manual | | severity | string | low, medium, high | | status | string | open, snoozed, in_progress, done, dismissed | | snoozedUntil | datetime | When to resurface (if snoozed) | | metrics | object | Position, CTR, impressions data | | queryContext | array | Top 5 queries with stats | | notes | text | Resolution notes | | createdAt | datetime | Task creation time | | resolvedAt | datetime | Task resolution time |

Components

SearchPerformancePane

Document view pane showing performance metrics for a content document.

import { SearchPerformancePane } from "@pagebridge/sanity";

// Used automatically when you configure the structure resolver
// Can also be used directly in custom document views

The pane displays:

• Clicks, impressions, CTR, and position metrics
• Top search queries driving traffic
• Google index status
• Link to associated refresh tasks

RefreshQueueTool

Sanity tool for managing content refresh tasks. Accessible from the Studio sidebar.

Features:

• Filter tasks by status (open, in progress, snoozed, done, dismissed)
• Sort by severity or creation date
• View decay signal details
• Update task status
• Add resolution notes

Configuration Options

pageBridgePlugin

interface PageBridgePluginConfig {
  // Document types that can be linked to snapshots and tasks
  contentTypes: string[];
}

createPageBridgeStructureResolver

interface StructureResolverConfig {
  // Document types to show the Performance pane on
  contentTypes: string[];
}

Using Schemas Directly

If you need to customize the schemas or use them without the plugin:

import {
  gscSite,
  createGscSnapshot,
  createGscRefreshTask,
} from "@pagebridge/sanity/schemas";

// Create snapshot schema with custom content types
const customSnapshot = createGscSnapshot({
  contentTypes: ["article", "guide"],
});

// Create task schema with custom content types
const customTask = createGscRefreshTask({
  contentTypes: ["article", "guide"],
});

Styling

The components use Sanity UI and follow the Studio's theme. No additional CSS is required.

Peer Dependencies

• sanity >= 3.0.0
• react >= 18.0.0
• react-dom >= 18.0.0
• @sanity/ui >= 2.0.0
• @sanity/icons >= 3.0.0

Exports

// Plugin
export {
  pageBridgePlugin,
  createPageBridgeStructureResolver,
} from "@pagebridge/sanity";
export type { PageBridgePluginConfig } from "@pagebridge/sanity";

// Components
export {
  SearchPerformancePane,
  RefreshQueueTool,
} from "@pagebridge/sanity";

// Schemas
export {
  gscSite,
  gscSnapshot,
  gscRefreshTask,
  createGscSnapshot,
  createGscRefreshTask,
} from "@pagebridge/sanity/schemas";
export type {
  GscSnapshotOptions,
  GscRefreshTaskOptions,
} from "@pagebridge/sanity/schemas";

License

MIT