PageBridge
5 min setup

Quick Start

Get PageBridge running and syncing Google Search Console data into your Sanity Studio in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

  • A Sanity project with Studio v3 deployed
  • A Google Cloud project with Search Console API enabled and a service account
  • A PostgreSQL database (local via Docker or hosted)
  • Node.js 18+ and pnpm 9+ installed

1. Install packages

Add the Sanity plugin and CLI to your project:

pnpm add @pagebridge/sanity

# Install the CLI globally or as a dev dependency
pnpm add -D @pagebridge/cli
bash

2. Configure environment variables

The fastest way is to run the interactive setup wizard:

pnpm pagebridge init
bash

This walks you through each credential, tests connections as you go, and writes a .env file with properly prefixed variables.

Or create a .env.local (or .env) file manually. PageBridge uses a PAGEBRIDGE_ prefix to avoid conflicts with your project's existing env vars:

.env.local
PAGEBRIDGE_GOOGLE_SERVICE_ACCOUNT='{"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}'
PAGEBRIDGE_DATABASE_URL='postgresql://postgres:postgres@localhost:5432/pagebridge'
PAGEBRIDGE_SANITY_PROJECT_ID='your-project-id'
PAGEBRIDGE_SANITY_DATASET='production'
PAGEBRIDGE_SANITY_TOKEN='sk...'
PAGEBRIDGE_SITE_URL='https://your-site.com'
bash

Unprefixed names (DATABASE_URL, SANITY_TOKEN, etc.) are also supported as a fallback. See Google Service Account for detailed instructions on creating the credentials.

3. Set up the database

Start a local PostgreSQL instance with Docker:

docker run -d --name pagebridge-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pagebridge \
  -p 5432:5432 \
  postgres:16
bash

Then push the schema:

pnpm pagebridge db:push
bash

4. Add the Sanity plugin

In your sanity.config.ts:

sanity.config.ts
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import {
  pageBridgePlugin,
  createPageBridgeStructure,
  createPageBridgeStructureResolver,
  PAGEBRIDGE_TYPES
} from '@pagebridge/sanity'

export default defineConfig({
  // ... your existing config
  plugins: [
    pageBridgePlugin({
      contentTypes: ['post', 'page'] // your document types
    }),
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items([
            createPageBridgeStructure(S),
            S.divider(),
            ...S.documentTypeListItems().filter(
              (item) => !PAGEBRIDGE_TYPES.includes(item.getId() as string)
            )
          ]),
      defaultDocumentNode: createPageBridgeStructureResolver(['post', 'page'])
    })
  ]
})
typescript

5. Verify your setup

Run the doctor command to check that everything is configured correctly:

pnpm pagebridge doctor
bash

This validates your env file, credentials, database connection, schema, Sanity access, and GSC API access. Fix any issues it reports before proceeding.

6. Run your first sync

Sync search analytics data from Google Search Console:

pnpm pagebridge sync --site sc-domain:your-site.com --migrate
bash

The --migrate flag ensures database migrations are run before syncing. This fetches the last 90 days of search data, matches URLs to Sanity documents, detects content decay, and writes performance snapshots to Sanity.

7. View results in Studio

Open Sanity Studio and you will see:

  • A PageBridge section in the sidebar with Sites, Snapshots, and Refresh Tasks
  • A Performance tab on each matched document showing metrics, weekly trends, and top queries
  • A Refresh Queue tool listing pages that need content updates

Next steps