@arraypress/sanity-loader

Astro Content Layer loader for Sanity. Plug a GROQ query into defineCollection({ loader: sanityLoader({ type: 'product' }) }) and treat your Sanity dataset like any other Astro content source.

getCollection(), getEntry(), dynamic routes, RSS, sitemap, OG images — everything that already works against glob() keeps working unchanged.

Install

npm install --save-dev @arraypress/sanity-loader @sanity/client

@sanity/client is a peer dep — install it alongside.

Configure

Either set env vars (most common):

# .env
SANITY_PROJECT_ID=abcd1234
SANITY_DATASET=production

Or pass overrides at the call site (multi-project monorepos):

sanityLoader({
  type: 'product',
  projectId: 'abcd1234',
  dataset: 'production',
  apiVersion: '2024-10-01',
  useCdn: true,
  token: process.env.SANITY_READ_TOKEN, // for private datasets
});

Use

// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { sanityLoader } from '@arraypress/sanity-loader';

const products = defineCollection({
  loader: sanityLoader({ type: 'product' }),
  schema: z.object({
    title: z.string(),
    price: z.number(),
    summary: z.string().optional(),
  }),
});

export const collections = { products };

Then anywhere in your Astro pages:

---
import { getCollection } from 'astro:content';
const products = await getCollection('products');
---
{products.map((p) => <ProductCard data={p.data} />)}

Options

Option	Default	Description
`type`	required	Sanity document `_type`.
`projectId`	`process.env.SANITY_PROJECT_ID`	Sanity project id.
`dataset`	`process.env.SANITY_DATASET` ↦ `'production'`	Dataset name.
`apiVersion`	`'2024-10-01'`	API date pin.
`useCdn`	`true`	Read through Sanity's CDN.
`token`	—	Auth token for private datasets / drafts.
`client`	—	Pre-built `SanityClient` (bypasses the internal factory).
`query`	`[_type == $type && !(_id in path('drafts.*'))]`	GROQ override — reference expansion, partial projection.
`map`	identity	Per-doc transform applied before the Zod schema runs.
`idField`	`'slug.current'`	Dotted path to the entry id. Falls back to `_id`.

Tips

Flatten Sanity references with `map`

Sanity stores references as { _ref, _type: 'reference' }. Astro schemas usually want flat values — use map to resolve them:

sanityLoader({
  type: 'product',
  query: `*[_type == $type && !(_id in path('drafts.**'))]{
    ...,
    "artist": artist->name,
    "category": category->slug.current
  }`,
});

Multi-project monorepos

The internal client cache is keyed on projectId+dataset, so multiple sanityLoader() calls pointing at different projects each get their own connection:

const storefront = defineCollection({
  loader: sanityLoader({ type: 'product', projectId: 'aaaa1111' }),
});
const blog = defineCollection({
  loader: sanityLoader({ type: 'post', projectId: 'bbbb2222' }),
});

Test stubs via `client`

Pass a pre-built client (or stub) when you want to drive the loader from a test without env vars or a network:

import { sanityLoader } from '@arraypress/sanity-loader';

const stub = { fetch: async () => [{ _id: 'a', slug: { current: 'a' }, title: 'A' }] };
const loader = sanityLoader({ type: 'product', client: stub });

Portable Text bodies

Long-form fields in Sanity are stored as Portable Text — an array of blocks, not Markdown. The loader writes an empty body field on each entry; render the Portable Text from the schema-typed field using @portabletext/to-html:

import { toHTML } from '@portabletext/to-html';

const html = toHTML(entry.data.bodyBlocks);

License

MIT