sanity-plugin-external-source

npm install sanity-plugin-external-source

// sanity.config.ts
import {defineConfig} from 'sanity'
import {externalSource} from 'sanity-plugin-external-source'

export default defineConfig({
  // ...
  plugins: [externalSource()]
})

import {defineField} from 'sanity'
import {createRestAdapter} from 'sanity-plugin-external-source'

const productsAdapter = createRestAdapter({
  name: 'products',
  title: 'Products',
  buildUrl: ctx => `https://api.example.com/products?q=${encodeURIComponent(ctx.query)}`,
  nextUrl: json => json.nextPageUrl ?? null, // omit for APIs without pagination
  selectItems: json => json.items,
  mapItem: raw => ({
    id: String(raw.id),
    title: raw.name,
    subtitle: raw.sku,
    imageUrl: raw.thumbnail,
    raw
  })
})

defineField({
  name: 'featuredProduct',
  title: 'Featured product',
  type: 'external.item',
  options: {
    adapters: [productsAdapter] // one field, one source
  }
})

defineField({
  name: 'anyExternal',
  type: 'external.item',
  options: {adapters: [productsAdapter, mediaAdapter, pimAdapter]}
})

{
  _type: 'external.item',   // configurable via `typeName`
  source: 'products',       // adapter name
  externalId: '8231',
  title: 'Aurora Desk 100',
  subtitle: 'SKU-1000',
  imageUrl: 'https://…/thumb.png',
  payload: '{"id":8231,…}', // JSON.stringify of the raw record (disable with storePayload: false)
  syncedAt: '2026-07-03T12:00:00.000Z'
}

*[_type == "page" && featuredProduct.source == "products"]{
  title,
  "productId": featuredProduct.externalId,
  "productImage": featuredProduct.imageUrl,
  "syncedAt": featuredProduct.syncedAt
}

import {defineAdapter} from 'sanity-plugin-external-source'

const API = 'https://pokeapi.co/api/v2'

export const pokemonAdapter = defineAdapter({
  name: 'pokemon', // stored in documents as `source` — keep it stable!
  title: 'Pokémon', // tab label

  async *fetch({query, signal}) {
    let url = `${API}/pokemon?limit=24&q=${encodeURIComponent(query)}`
    while (url) {
      const res = await fetch(url, {signal}) // signal: stale runs get aborted
      if (!res.ok) throw new Error(`PokeAPI: HTTP ${res.status}`) // shown inline in the dialog

      const json = await res.json()
      const items = json.results.map(r => {
        const id = r.url.replace(/\/+$/, '').split('/').pop()
        return {
          id,
          title: r.name,
          imageUrl: `https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/${id}.png`,
          raw: r
        }
      })

      if (!json.next) return items // `return` the last page → "Load more" hides immediately
      yield items // one page per "Load more" click
      url = json.next
    }
  },

  // Optional: enables the "Refresh" button on the input
  async resolve(id) {
    const res = await fetch(`${API}/pokemon/${id}`)
    if (res.status === 404) return null // item gone upstream
    if (!res.ok) throw new Error(`PokeAPI: HTTP ${res.status}`)
    const p = await res.json()
    return {
      id: String(p.id),
      title: p.name,
      imageUrl: p.sprites.other['official-artwork'].front_default,
      raw: p
    }
  }
})

            ┌───────────────────────────────────────────────────┐
 plugin ──▶ │ fetch({query, filters, signal})                   │ ──▶ your API
            │   async fn   → resolve with all items             │
            │   async gen  → yield one page per "Load more"     │
            └───────────────────────────────────────────────────┘

interface ExternalItem {
  id: string        // stable unique id — stored as externalId
  title?: string
  subtitle?: string
  imageUrl?: string
  raw?: unknown     // stored as the JSON payload (falls back to the item itself)
}

// 1) No pagination — return everything (or the top N)
async fetch({query, signal}) {
  const res = await fetch(searchUrl(query), {signal})
  return mapItems(await res.json())
}

// 2) Offsets / page numbers — a loop counter
async *fetch({query, signal}) {
  for (let offset = 0; ; offset += LIMIT) {
    const json = await getJson(searchUrl(query, offset), signal)
    const items = json.results.map(mapItem)
    if (offset + LIMIT >= json.count) return items
    yield items
  }
}

// 3) Cursor tokens / next-page URLs — a mutable variable
async *fetch({query, signal}) {
  let url = firstUrl(query)
  while (true) {
    const json = await getJson(url, signal)
    if (!json.next) return mapItems(json)
    yield mapItems(json)
    url = json.next
  }
}

filters: [
  {kind: 'select', name: 'category', title: 'Category', multiple: true,
   options: [{value: 'kitchen', title: 'Kitchen'}, {value: 'outdoors', title: 'Outdoors'}]},
  {kind: 'toggle', name: 'inStock', title: 'In stock only'},
  {kind: 'text', name: 'sku', title: 'SKU contains', placeholder: 'SKU-10…'},
  {kind: 'daterange', name: 'created', title: 'Created'}
]

{name: 'products', ...,
 // Store only the id — framework fields (_type, source, syncedAt) still added.
 mapValue: item => ({externalId: item.id})}

{name: 'articles', ...,
 // Store a custom subset — headline, canonical url, published date.
 mapValue: item => ({
   externalId: item.id,
   headline: item.title,
   url: item.raw.canonicalUrl,
   publishedAt: item.raw.publishedAt
 })}

externalSource({storePayload: false})

import {Badge, Box, Flex, Stack, Text} from '@sanity/ui'

renderTile({item, selected, query}) {
  return (
    <Flex align="center" gap={3}>
      <Box flex={1}>
        <Stack space={2}>
          <Text size={1} weight={selected ? 'bold' : 'medium'}>{item.title}</Text>
          <Text size={0} muted>{item.raw.sku}</Text>
        </Stack>
      </Box>
      <Badge tone={item.raw.inStock ? 'positive' : 'critical'}>
        {item.raw.inStock ? 'In stock' : 'Out of stock'}
      </Badge>
    </Flex>
  )
}

createRestAdapter({
  name: 'articles',
  title: 'Articles',
  buildUrl: ctx => {
    // First page only — the factory follows `nextUrl` from there.
    const url = new URL('https://api.example.com/articles')
    if (ctx.query) url.searchParams.set('q', ctx.query)
    if (typeof ctx.filters.section === 'string') url.searchParams.set('section', ctx.filters.section)
    return url
  },
  nextUrl: json => json.nextPageUrl ?? null,               // null = no more pages; omit for single-page APIs
  headers: () => ({Authorization: `Bearer ${myToken}`}), // static object or (async) factory
  selectItems: json => json.data.hits,
  mapItem: raw => ({id: String(raw.id), title: raw.headline, imageUrl: raw.thumb, raw}),
  resolveUrl: id => `https://api.example.com/articles/${id}`, // enables Refresh; 404 → "item gone"
  mapResolved: json => json.data
})

externalSource({
  typeName: 'external.item', // optional: rename the schema type
  storePayload: true         // optional: set false to skip storing the raw JSON
})

externalSource({typeName: 'product.ref'})
// …
defineField({
  name: 'product',
  type: 'product.ref',
  options: {adapters: [productsAdapter]}
})

defineField({
  name: 'featuredProduct',
  type: 'external.item',
  options: {dialog: {mode: 'centered'}} // or 'fullscreen'
})

options: {dialog: {mode: 'centered', width: 3}}

npm install
npm run dev   # starts the dev studio in ./dev
npm run build # plugin-kit verify + pkg-utils build