566 lines
18 KiB
Markdown
566 lines
18 KiB
Markdown
---
|
||
title: Angular & Sanity Integration Rules
|
||
description: Integration guide for Angular, including @sanity/client setup, data fetching with signals and resource API, Portable Text rendering, and image optimization.
|
||
---
|
||
|
||
# Angular & Sanity Integration Rules
|
||
|
||
Jump to the section that matches your Angular version or integration task instead of reading this guide straight through.
|
||
|
||
## Table of Contents
|
||
|
||
- Setup and configuration
|
||
- Client setup (service pattern)
|
||
- Data fetching patterns
|
||
- Routing
|
||
- Portable Text rendering
|
||
- Image optimization
|
||
- Modern Angular features
|
||
- SSR and prerendering
|
||
- Visual Editing
|
||
- Error handling
|
||
|
||
## 1. Setup & Configuration
|
||
|
||
Use the official template `sanity-template-angular-clean` as a starting point. It provides a monorepo structure:
|
||
|
||
```
|
||
project/
|
||
├── angular-app/ # Angular 19+ frontend
|
||
└── studio/ # Sanity Studio
|
||
```
|
||
|
||
Install dependencies in the Angular app:
|
||
|
||
```bash
|
||
npm install @sanity/client @sanity/image-url @portabletext/to-html
|
||
```
|
||
|
||
Configure environment files for Sanity credentials:
|
||
|
||
```typescript
|
||
// environments/environment.ts
|
||
export const environment = {
|
||
production: false,
|
||
sanity: {
|
||
projectId: 'your-project-id',
|
||
dataset: 'production',
|
||
apiVersion: '2025-05-01',
|
||
},
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// environments/environment.production.ts
|
||
export const environment = {
|
||
production: true,
|
||
sanity: {
|
||
projectId: 'your-project-id',
|
||
dataset: 'production',
|
||
apiVersion: '2025-05-01',
|
||
},
|
||
}
|
||
```
|
||
|
||
> There is no Angular-specific Sanity SDK. Use `@sanity/client` directly, wrapped in an Angular service.
|
||
|
||
### TypeGen in a Monorepo
|
||
|
||
Sanity TypeGen generates TypeScript types from your schema and GROQ queries. In the Angular monorepo template, TypeGen runs from the Studio side but scans your Angular app's source files. Ensure `studio/sanity.cli.ts` points at the Angular app:
|
||
|
||
```typescript
|
||
// studio/sanity.cli.ts
|
||
import { defineCliConfig } from 'sanity/cli'
|
||
|
||
export default defineCliConfig({
|
||
typegen: {
|
||
enabled: true,
|
||
path: '../angular-app/src/**/*.ts',
|
||
generates: '../angular-app/sanity.types.ts',
|
||
},
|
||
})
|
||
```
|
||
|
||
The remaining defaults (`overloadClientMethods: true`, `schema: "schema.json"`) work as-is. Include the generated types file in `angular-app/tsconfig.json` (usually covered by `"include": ["src/**/*.ts", "sanity.types.ts"]`). See `typegen.md` for the full TypeGen workflow, git strategy, and configuration options.
|
||
|
||
## 2. Client Setup (Service Pattern)
|
||
|
||
Create an injectable service wrapping `@sanity/client` and `@sanity/image-url`:
|
||
|
||
```typescript
|
||
import { Injectable } from '@angular/core'
|
||
import { createClient, type ClientReturn, type QueryParams, type SanityClient } from '@sanity/client'
|
||
import imageUrlBuilder, { type ImageUrlBuilder } from '@sanity/image-url'
|
||
import type { SanityImageSource } from '@sanity/image-url/lib/types/types'
|
||
import { environment } from '../environments/environment'
|
||
|
||
@Injectable({ providedIn: 'root' })
|
||
export class SanityService {
|
||
private client: SanityClient
|
||
private builder: ImageUrlBuilder
|
||
|
||
constructor() {
|
||
this.client = createClient({
|
||
projectId: environment.sanity.projectId,
|
||
dataset: environment.sanity.dataset,
|
||
apiVersion: environment.sanity.apiVersion,
|
||
useCdn: true,
|
||
})
|
||
this.builder = imageUrlBuilder(this.client)
|
||
}
|
||
|
||
// ClientReturn resolves TypeGen's declaration-merged overloads for defineQuery strings
|
||
fetch<Query extends string>(query: Query, params?: QueryParams): Promise<ClientReturn<Query>> {
|
||
return this.client.fetch(query, params)
|
||
}
|
||
|
||
getImageUrlBuilder(source: SanityImageSource) {
|
||
return this.builder.image(source)
|
||
}
|
||
}
|
||
```
|
||
|
||
For preview/draft content, create a second client instance with a token and `useCdn: false`. Never expose tokens in client-side bundles — use server-side rendering or a proxy endpoint for authenticated requests.
|
||
|
||
## 3. Data Fetching Patterns
|
||
|
||
### A. `resource` API (Angular 19+, Recommended)
|
||
|
||
The `resource` API works natively with promises and integrates with Angular signals:
|
||
|
||
```typescript
|
||
import { Component, input, resource, inject } from '@angular/core'
|
||
import { defineQuery } from 'groq'
|
||
import { SanityService } from '../sanity.service'
|
||
|
||
const POST_QUERY = defineQuery(`*[_type == "post" && slug.current == $slug][0]{
|
||
title, body, mainImage, publishedAt
|
||
}`)
|
||
|
||
@Component({
|
||
selector: 'app-post',
|
||
standalone: true,
|
||
template: `
|
||
@if (post.value(); as p) {
|
||
<h1>{{ p.title }}</h1>
|
||
<time>{{ p.publishedAt | date }}</time>
|
||
} @else if (post.isLoading()) {
|
||
<p>Loading…</p>
|
||
} @else if (post.error()) {
|
||
<p>Error loading post</p>
|
||
}
|
||
`,
|
||
})
|
||
export default class PostComponent {
|
||
slug = input.required<string>()
|
||
private sanity = inject(SanityService)
|
||
|
||
post = resource({
|
||
params: () => ({ slug: this.slug() }),
|
||
loader: ({ params }) => this.sanity.fetch(POST_QUERY, params),
|
||
})
|
||
}
|
||
```
|
||
|
||
The `resource` automatically re-fetches when `slug` changes and exposes `value()`, `isLoading()`, and `error()` signals.
|
||
|
||
> **TypeGen:** Wrapping queries in `defineQuery` enables Sanity TypeGen to infer return types automatically — no manual type imports needed. See `typegen.md` for the full workflow.
|
||
|
||
### B. `rxResource` (Observable-based)
|
||
|
||
For teams using RxJS patterns or needing operators like `retry` and `debounceTime`:
|
||
|
||
```typescript
|
||
import { Component, input, inject } from '@angular/core'
|
||
import { rxResource } from '@angular/core/rxjs-interop'
|
||
import { defineQuery } from 'groq'
|
||
import { from } from 'rxjs'
|
||
import { SanityService } from '../sanity.service'
|
||
|
||
const POST_QUERY = defineQuery(`*[_type == "post" && slug.current == $slug][0]`)
|
||
|
||
@Component({ /* ... */ })
|
||
export default class PostComponent {
|
||
slug = input.required<string>()
|
||
private sanity = inject(SanityService)
|
||
|
||
post = rxResource({
|
||
params: () => ({ slug: this.slug() }),
|
||
loader: ({ params }) => from(this.sanity.fetch(POST_QUERY, params)),
|
||
})
|
||
}
|
||
```
|
||
|
||
### C. `toSignal` (Angular 17–18)
|
||
|
||
For apps not yet on Angular 19, convert observables to signals:
|
||
|
||
```typescript
|
||
import { Component, inject } from '@angular/core'
|
||
import { toSignal } from '@angular/core/rxjs-interop'
|
||
import { defineQuery } from 'groq'
|
||
import { from } from 'rxjs'
|
||
import { SanityService } from '../sanity.service'
|
||
|
||
const POSTS_QUERY = defineQuery(`*[_type == "post"] | order(publishedAt desc)`)
|
||
|
||
@Component({ /* ... */ })
|
||
export class HomeComponent {
|
||
private sanity = inject(SanityService)
|
||
posts = toSignal(from(this.sanity.fetch(POSTS_QUERY)), { initialValue: [] })
|
||
}
|
||
```
|
||
|
||
> **Note:** `toSignal` does not re-fetch on parameter changes. For dynamic queries, use `resource` or `rxResource`.
|
||
|
||
### Choosing a pattern
|
||
|
||
| Pattern | Angular Version | Reactivity | Best For |
|
||
|---|---|---|---|
|
||
| `resource` | 19+ | Signal-based, auto re-fetch | New projects, dynamic queries |
|
||
| `rxResource` | 19+ | RxJS + signals | Teams using RxJS operators |
|
||
| `toSignal` | 17+ | One-shot conversion | Static queries, legacy apps |
|
||
|
||
## 4. Routing
|
||
|
||
Use lazy-loaded routes with `withComponentInputBinding()` so route params bind directly to component inputs:
|
||
|
||
```typescript
|
||
// app.config.ts
|
||
import { provideRouter, withComponentInputBinding } from '@angular/router'
|
||
import { routes } from './app.routes'
|
||
|
||
export const appConfig = {
|
||
providers: [
|
||
provideRouter(routes, withComponentInputBinding()),
|
||
],
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// app.routes.ts
|
||
import { Routes } from '@angular/router'
|
||
|
||
export const routes: Routes = [
|
||
{
|
||
path: '',
|
||
loadComponent: () => import('./home/home.component'),
|
||
pathMatch: 'full',
|
||
},
|
||
{
|
||
path: 'post/:slug',
|
||
loadComponent: () => import('./post/post.component'),
|
||
},
|
||
]
|
||
```
|
||
|
||
With `withComponentInputBinding()`, the `:slug` route param is automatically bound to `slug = input.required<string>()` on the component — no need to inject `ActivatedRoute`.
|
||
|
||
## 5. Portable Text Rendering
|
||
|
||
### A. `@portabletext/to-html` with Angular Pipe (Recommended)
|
||
|
||
```typescript
|
||
import { Pipe, PipeTransform, inject } from '@angular/core'
|
||
import { toHTML, type PortableTextComponents } from '@portabletext/to-html'
|
||
import type { PortableTextBlock } from '@portabletext/types'
|
||
import { SanityService } from '../sanity.service'
|
||
|
||
@Pipe({ name: 'portableTextToHTML', standalone: true })
|
||
export class PortableTextToHTMLPipe implements PipeTransform {
|
||
private sanity = inject(SanityService)
|
||
|
||
private components: PortableTextComponents = {
|
||
types: {
|
||
image: ({ value }) => {
|
||
const url = this.sanity.getImageUrlBuilder(value).width(800).auto('format').url()
|
||
return `<img src="${url}" alt="${value.alt || ''}" loading="lazy" />`
|
||
},
|
||
},
|
||
marks: {
|
||
link: ({ children, value }) =>
|
||
`<a href="${value.href}" rel="noopener noreferrer">${children}</a>`,
|
||
},
|
||
}
|
||
|
||
transform(value: PortableTextBlock[] | undefined): string {
|
||
if (!value) return ''
|
||
return toHTML(value, { components: this.components })
|
||
}
|
||
}
|
||
```
|
||
|
||
Usage in templates:
|
||
|
||
```html
|
||
<div [innerHTML]="post.body | portableTextToHTML"></div>
|
||
```
|
||
|
||
### B. `@limitless-angular/sanity` (Community, Component-based)
|
||
|
||
For full Angular component control over each block type, the community library `@limitless-angular/sanity` provides a component-based Portable Text renderer. This is useful when you need Angular-specific interactivity within rich text blocks.
|
||
|
||
See `portable-text.md` for Portable Text schema design and serialization rules.
|
||
|
||
## 6. Image Optimization
|
||
|
||
Create a pipe wrapping `@sanity/image-url`:
|
||
|
||
```typescript
|
||
import { Pipe, PipeTransform, inject } from '@angular/core'
|
||
import type { SanityImageSource } from '@sanity/image-url/lib/types/types'
|
||
import { SanityService } from '../sanity.service'
|
||
|
||
@Pipe({ name: 'sanityImage', standalone: true })
|
||
export class SanityImagePipe implements PipeTransform {
|
||
private sanity = inject(SanityService)
|
||
|
||
transform(value: SanityImageSource | undefined, width?: number): string | null {
|
||
if (!value) return null
|
||
const builder = this.sanity.getImageUrlBuilder(value)
|
||
if (width) return builder.width(width).auto('format').url()
|
||
return builder.auto('format').url()
|
||
}
|
||
}
|
||
```
|
||
|
||
Combine with Angular's `NgOptimizedImage` for LCP images:
|
||
|
||
```html
|
||
<!-- Priority image with NgOptimizedImage -->
|
||
<img [ngSrc]="post.mainImage | sanityImage: 1200" width="1200" height="630" priority />
|
||
|
||
<!-- Lazy-loaded image -->
|
||
<img [src]="post.mainImage | sanityImage: 600" [alt]="post.mainImage.alt" loading="lazy" />
|
||
```
|
||
|
||
❌ **Bad:** Fetching full-size images without width constraints.
|
||
|
||
```html
|
||
<img [src]="post.mainImage | sanityImage" />
|
||
```
|
||
|
||
✅ **Good:** Specifying width and using `auto('format')` for WebP/AVIF delivery.
|
||
|
||
```html
|
||
<img [src]="post.mainImage | sanityImage: 800" loading="lazy" />
|
||
```
|
||
|
||
### LQIP with `NgOptimizedImage`
|
||
|
||
Sanity provides a base64 LQIP (Low Quality Image Placeholder) per image asset — but you must query it explicitly:
|
||
|
||
```groq
|
||
mainImage {
|
||
// @sanity/image-url needs these to build URLs with hotspot/crop support
|
||
asset,
|
||
hotspot,
|
||
crop,
|
||
alt,
|
||
// NgOptimizedImage needs these for placeholder and layout
|
||
"lqip": asset->metadata.lqip,
|
||
"width": asset->metadata.dimensions.width,
|
||
"height": asset->metadata.dimensions.height
|
||
}
|
||
```
|
||
|
||
Feed the LQIP directly into `NgOptimizedImage`'s `placeholder` attribute:
|
||
|
||
```html
|
||
<img
|
||
[ngSrc]="post.mainImage | sanityImage: 1200"
|
||
[width]="post.mainImage.width"
|
||
[height]="post.mainImage.height"
|
||
[placeholder]="post.mainImage.lqip"
|
||
[alt]="post.mainImage.alt"
|
||
priority
|
||
/>
|
||
```
|
||
|
||
Angular applies a CSS blur to the LQIP and crossfades to the full image on load. No extra libraries needed.
|
||
|
||
> **Note:** LQIP strings are small (~200 bytes) so they're safe to inline in SSR HTML and `TransferState`. See `image.md` for the full image query patterns.
|
||
|
||
See `image.md` for image field schema patterns and hotspot/crop configuration.
|
||
|
||
## 7. Modern Angular Features
|
||
|
||
When building with Sanity, leverage these Angular 19+ features:
|
||
|
||
- **Standalone components** — Default in Angular 19. No `NgModule` boilerplate needed.
|
||
- **Signals and `resource`** — Preferred over RxJS for data fetching. Simpler, less boilerplate.
|
||
- **New control flow** — Use `@if`, `@for`, `@switch` with `@empty` for cleaner templates:
|
||
|
||
```html
|
||
@for (post of posts.value(); track post._id) {
|
||
<app-post-card [post]="post" />
|
||
} @empty {
|
||
<p>No posts found.</p>
|
||
}
|
||
```
|
||
|
||
- **`@defer` blocks** — Lazy-load below-fold content:
|
||
|
||
```html
|
||
@defer (on viewport) {
|
||
<app-comments [postId]="post._id" />
|
||
} @placeholder {
|
||
<p>Scroll to see comments…</p>
|
||
}
|
||
```
|
||
|
||
- **`inject()` function** — Preferred over constructor injection for cleaner code.
|
||
- **Zoneless change detection** — Experimental in Angular 19. Works well with signals-based data fetching since signals automatically notify the framework of changes.
|
||
|
||
## 8. SSR & Prerendering
|
||
|
||
Angular 17+ includes built-in SSR support (replacing Angular Universal):
|
||
|
||
```typescript
|
||
// app.config.server.ts
|
||
import { provideServerRendering } from '@angular/platform-server'
|
||
import { provideClientHydration } from '@angular/platform-browser'
|
||
|
||
export const serverConfig = {
|
||
providers: [
|
||
provideServerRendering(),
|
||
provideClientHydration(),
|
||
],
|
||
}
|
||
```
|
||
|
||
Key considerations for Sanity + Angular SSR:
|
||
|
||
| Feature | Details |
|
||
|---|---|
|
||
| **Hydration** | `provideClientHydration()` preserves server-rendered DOM. The client reuses it instead of re-rendering. |
|
||
| **HTTP Transfer Cache** | Only works with Angular's `HttpClient`. Since `@sanity/client` uses its own HTTP transport, use `TransferState` manually (see below). |
|
||
| **Prerendering** | Use `getPrerenderParams` in route config to generate static pages at build time. |
|
||
|
||
### Transfer State for `@sanity/client`
|
||
|
||
Angular's built-in HTTP Transfer Cache does not cover `@sanity/client` requests. Without manual transfer, the client re-fetches every query during hydration. Add `TransferState` to the service from Section 2:
|
||
|
||
```typescript
|
||
+ async function hashQuery(query: string, params?: QueryParams): Promise<string> {
|
||
+ const input = query + JSON.stringify(params ?? {})
|
||
+ const buffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input))
|
||
+ return Array.from(new Uint8Array(buffer), b => b.toString(16).padStart(2, '0')).join('')
|
||
+ }
|
||
|
||
import { Injectable, inject } from '@angular/core'
|
||
+ import { isPlatformBrowser, isPlatformServer } from '@angular/common'
|
||
+ import { PLATFORM_ID, makeStateKey, TransferState } from '@angular/core'
|
||
import { createClient, type ClientReturn, type QueryParams, type SanityClient } from '@sanity/client'
|
||
|
||
export class SanityService {
|
||
private client: SanityClient
|
||
+ private transferState = inject(TransferState)
|
||
+ private platformId = inject(PLATFORM_ID)
|
||
|
||
async fetch<Query extends string>(query: Query, params?: QueryParams): Promise<ClientReturn<Query>> {
|
||
+ const key = makeStateKey<ClientReturn<Query>>(await hashQuery(query, params))
|
||
+
|
||
+ if (isPlatformBrowser(this.platformId)) {
|
||
+ const cached = this.transferState.get(key, null)
|
||
+ if (cached !== null) {
|
||
+ this.transferState.remove(key)
|
||
+ return cached
|
||
+ }
|
||
+ }
|
||
+
|
||
const result = await this.client.fetch(query, params)
|
||
+
|
||
+ if (isPlatformServer(this.platformId)) {
|
||
+ this.transferState.set(key, result)
|
||
+ }
|
||
+
|
||
return result
|
||
}
|
||
}
|
||
```
|
||
|
||
The `hashQuery` helper keeps `TransferState` keys short (SHA-256 hex) instead of embedding raw GROQ strings in the serialized HTML.
|
||
|
||
Prerendering dynamic routes:
|
||
|
||
```typescript
|
||
// app.routes.server.ts
|
||
import { RenderMode, ServerRoute } from '@angular/ssr'
|
||
|
||
export const serverRoutes: ServerRoute[] = [
|
||
{
|
||
path: 'post/:slug',
|
||
renderMode: RenderMode.Prerender,
|
||
async getPrerenderParams() {
|
||
// Fetch all slugs from Sanity at build time
|
||
const client = createClient({ projectId: '...', dataset: '...', apiVersion: '...', useCdn: true })
|
||
const slugs = await client.fetch<string[]>(`*[_type == "post"].slug.current`)
|
||
return slugs.map((slug) => ({ slug }))
|
||
},
|
||
},
|
||
{ path: '**', renderMode: RenderMode.Server },
|
||
]
|
||
```
|
||
|
||
❌ **Bad:** Using `isPlatformBrowser()` in templates to conditionally render content — causes hydration mismatch.
|
||
|
||
✅ **Good:** Using `@defer` or `afterNextRender()` for browser-only code.
|
||
|
||
## 9. Visual Editing
|
||
|
||
> **Important:** Angular does not have official Sanity Visual Editing support. There is no `@sanity/visual-editing` integration, no Stega encoding, and no click-to-edit overlay for Angular applications. This is unlike Next.js, Nuxt, and SvelteKit which have first-party support.
|
||
|
||
### Preview Mode (Basic)
|
||
|
||
For draft content preview, create a separate preview client with an API token:
|
||
|
||
```typescript
|
||
@Injectable({ providedIn: 'root' })
|
||
export class SanityService {
|
||
private client: SanityClient
|
||
private previewClient: SanityClient
|
||
|
||
constructor() {
|
||
this.client = createClient({
|
||
projectId: environment.sanity.projectId,
|
||
dataset: environment.sanity.dataset,
|
||
apiVersion: environment.sanity.apiVersion,
|
||
useCdn: true,
|
||
})
|
||
|
||
this.previewClient = this.client.withConfig({
|
||
useCdn: false,
|
||
token: environment.sanity.previewToken, // Server-side only!
|
||
perspective: 'drafts',
|
||
})
|
||
}
|
||
|
||
fetch<Query extends string>(query: Query, params?: QueryParams, preview = false): Promise<ClientReturn<Query>> {
|
||
const client = preview ? this.previewClient : this.client
|
||
return client.fetch(query, params)
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Security:** Never expose the preview token in client-side bundles. Use this pattern only with SSR where the token stays on the server, or proxy preview requests through a backend API.
|
||
|
||
### Community Visual Editing
|
||
|
||
The community library `@limitless-angular/sanity` provides experimental Visual Editing support for Angular, including overlay click-to-edit functionality. Check its documentation for current status and limitations.
|
||
|
||
## 10. Error Handling
|
||
|
||
Common errors when integrating Angular with Sanity:
|
||
|
||
| Error | Cause | Solution |
|
||
|---|---|---|
|
||
| `401 Unauthorized` | Invalid or missing API token | Verify token in [Sanity Manage](https://www.sanity.io/manage). Ensure it has correct permissions. |
|
||
| `403 Forbidden` | CORS origin not allowed | Add your Angular dev/production URL to CORS origins in [Sanity Manage](https://www.sanity.io/manage). |
|
||
| `422 Invalid query` | GROQ syntax error | Test queries in Vision plugin or Sanity's GROQ playground. See `groq.md`. |
|
||
| Hydration mismatch | Conditional rendering based on platform | Use `@defer` or `afterNextRender()` instead of `isPlatformBrowser()` checks. |
|
||
| Empty response | Missing dataset or wrong `apiVersion` | Verify environment config. Use a date-based `apiVersion` (e.g., `'2025-05-01'`). |
|
||
| Images not loading | Missing `@sanity/image-url` setup | Ensure `getImageUrlBuilder` is called with a valid image reference. See `image.md`. |
|
||
|
||
For GROQ query patterns and best practices, see `groq.md`. For schema design, see `schema.md`.
|