From reading to action
A practical path through this guide.
Select a step to explore what to do and why it matters.
Define the rendering shape
Separate lightweight card fields from article-only detail fields.
GROQ projections define the content shape your frontend receives. Design separate card and detail projections so a listing does not fetch every article body. Share the fields that must stay consistent, such as slug, title, summary, image, and publication date.
Start from the rendering requirement
List what a blog card actually displays and what its metadata needs. Fetch those fields and the specific referenced author or category data required. Avoid dereferencing large documents simply because they are connected to the article.
Keep the detail projection explicit too. It can extend the card shape with the body and other article-only fields. This makes the relationship visible and reduces the chance that one route uses a different slug or date convention.
Parameterize filters
Use query parameters for user-selected categories, tags, and slugs. Do not concatenate untrusted filter text into a query string. Define empty-filter behavior clearly so the all-articles view and filtered view use compatible semantics.
Check how missing references and optional arrays affect the result. An article with no category should not crash the listing. Related-content queries should exclude the current slug and handle an empty tag list without producing surprising matches.
Preserve one public content policy
- Define what counts as a public article.
- Reuse that filter across listing, detail, and slug queries.
- Apply a stable ordering rule.
- Make pagination or result limits visible.
- Keep draft and published perspectives intentional.
If the application also bundles local articles, specify where they are merged and how a CMS document overrides the same slug. Independent fallback rules across routes can produce pages that exist but never appear in the sitemap or category filter.
Validate the returned shape
Use representative documents: complete metadata, missing image, missing reference, empty tags, and an old document created before the latest schema changes. Inspect the actual result and render those cases in a production-like build.
Keep TypeScript types aligned with what the projection returns, including flattened slugs and nullable values. Types help document the contract, but they do not validate arbitrary remote data by themselves. Preserve defensive handling at the boundary where missing fields are expected.
Further reading
How GROQ queries work explains projection and reference concepts. See sitemap debugging for a common consequence of inconsistent public queries.
A few practical answers
Frequently asked questions
Why should card and article-detail GROQ projections differ?
Cards need a small summary shape, while article pages need body content and detail fields. Explicit projections avoid transferring full bodies unnecessarily and clarify the rendering contract.
How should user-selected filters enter a GROQ query?
Pass category, tag and slug values as parameters. Define empty-filter behavior explicitly and check missing references rather than constructing queries with untrusted string concatenation.
