Umbraco Headless with a Next.js Frontend: The Best of Both Worlds
Combining Umbraco's content management with Next.js rendering gives you editorial flexibility and developer performance. Here's how we wire it together.
The traditional Umbraco setup renders pages server-side with Razor views. While this works well, modern frontend expectations — instant navigation, rich interactions, optimistic updates — push us toward a decoupled architecture.
Architecture Overview
Our preferred setup uses Umbraco's Content Delivery API to serve content to a Next.js frontend. Umbraco handles content modeling and editorial workflows; Next.js handles rendering, routing, and interactivity.
Content Delivery API Setup
Umbraco's built-in Content Delivery API provides a JSON representation of your content tree. We configure it with:
- API key authentication for secure access
- Preview endpoints for draft content
- Custom content expansion for nested content types
Next.js Integration Patterns
On the Next.js side, we build a typed content client:
- Generated TypeScript types from Umbraco's content models
- SWR-based hooks for client-side content updates
- ISR (Incremental Static Regeneration) for optimal performance
Dynamic Routing
We map Umbraco's content tree to Next.js dynamic routes. A catch-all route resolves the URL path against Umbraco's content structure and renders the appropriate page template.
Preview Mode
Editors need to preview unpublished changes. We wire Umbraco's preview button to Next.js draft mode, fetching from the preview endpoint and disabling caching for real-time editing feedback.
Media Handling
Umbraco's media library serves images through the Image Cropper. We integrate this with Next.js Image component by building a custom loader that generates Umbraco crop URLs with responsive sizing.
Deployment Strategy
We deploy Umbraco to Azure App Service and Next.js to Vercel. Content changes trigger webhooks from Umbraco that revalidate affected pages on the Next.js side via on-demand ISR.
Conclusion
This architecture gives content teams the editing experience they love while developers build with modern tools. It's the pattern we recommend for any content-heavy application that needs to feel fast and interactive.
Want to discuss this topic?
We love talking shop. Reach out to discuss how we can apply these practices to your project.