GROQ Queries Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The GROQ (Graph-Relational Object Queries) strategy in this project facilitates efficient data retrieval from the Sanity Content Lake to the Next.js frontend. It utilizes a centralized definition of queries paired with TypeScript type generation to ensure type safety and optimal performance.
This strategy revolves around the defineQuery utility for query declaration, sanityFetch for execution with live-reloading capabilities, and Sanity's TypeGen to map GROQ results to TypeScript interfaces.
Centralized Query Architecture
Queries are defined in a dedicated library file to promote reusability across the application's Server Components. These queries target specific document types like home, page, project, and settings, often employing projections to shape the data exactly as required by the UI components.
Core Query Definitions
| Query Variable | Purpose | Target Document |
|---|---|---|
homePageQuery | Fetches homepage content including dereferenced showcase projects. | home |
pagesBySlugQuery | Retrieves specific page content filtered by slug. | page |
projectBySlugQuery | Retrieves project details filtered by slug. | project |
settingsQuery | Fetches global site settings, including menu and footer data. | settings |
slugsByTypeQuery | Lists all slugs for a specific document type (used for static generation). | Mixed |
Sources: sanity/lib/queries.ts:3-64
Data Flow for Content Retrieval
The following diagram illustrates how GROQ queries are triggered by Next.js components and resolved through the Sanity Client.
The data flow ensures that components receive structured content while benefiting from features like Draft Mode and real-time updates through the SanityLive provider.
Sources: app/(personal)/projects/[slug]/page.tsx:43-43, sanity/lib/live.ts
Advanced Query Patterns
Dereferencing and Projections
The project frequently uses the @-> operator to dereference linked documents. For instance, in the homePageQuery, showcase projects (which are stored as references) are expanded to include their specific fields such as coverImage and slug.
showcaseProjects[]{
_key,
...@->{
_id,
_type,
coverImage,
"slug": slug.current,
title,
}
}
Sources: sanity/lib/queries.ts:8-17
Dynamic Parameter Filtering
Queries like pagesBySlugQuery and projectBySlugQuery use named parameters (e.g., $slug) to filter the Content Lake. This is safer and more efficient than string interpolation.
*[_type == "page" && slug.current == $slug][0]
Sources: sanity/lib/queries.ts:27, app/(personal)/[slug]/page.tsx:40
Type Integration and TypeGen
The project uses sanity typegen to automatically create TypeScript interfaces based on the GROQ queries. This ensures that when a query is modified, the frontend code immediately reflects the changes in the expected data structure.
Query Result Mapping
| Query | Generated TypeScript Type |
|---|---|
homePageQuery | HomePageQueryResult |
pagesBySlugQuery | PagesBySlugQueryResult |
projectBySlugQuery | ProjectBySlugQueryResult |
settingsQuery | SettingsQueryResult |
Sources: sanity.types.ts:401-654
The SanityQueries interface in the generated types file maps the raw GROQ string to its respective result type, allowing the client to automatically infer return types during development.
Sources: sanity.types.ts:662-670
Execution Environment
The Sanity client is configured to handle different perspectives and features based on the environment and user state (e.g., Draft Mode).
Client Configuration
The client uses the published perspective by default and enables stega to embed Content Source Maps, which powers visual editing in the Sanity Studio.
Sources: sanity/lib/client.ts:4-21
Conclusion
The GROQ Queries Strategy implemented in this repository provides a robust bridge between Sanity's flexible content modeling and Next.js's typed component architecture. By centralizing queries, utilizing parameterization, and enforcing type safety through automated generation, the project maintains high performance and developer productivity.