> ## Content Index
> Fetch the complete content index at: https://www.artisancraft.dev/llms.txt
> Use this file to discover other available public pages before exploring further.

# Headless Sitefinity with Next.js: a practical guide for modern frontends
- URL: https://www.artisancraft.dev/headless-sitefinity-with-next-js-a-practical-guide-for-modern-frontends/
- Published: 2025-12-02T12:00:18.000Z
- Updated: 2025-12-02T12:00:18.000Z
- Description: Sitefinity’s headless APIs and native Next.js support let you keep a powerful CMS backend while building a modern React frontend. With an official SDK, starter templates and hybrid rendering, you can ship headless or migrate gradually without a full rewrite.
- Author: Daniel Plomp
- Tags: CMS, dxp, headless cms, Sitefinity, .NET, nextjs

## Introduction

Modern web projects often want the best of both worlds: a strong CMS for content teams and a modern React/Next.js stack for the frontend. Sitefinity has moved firmly into that space: it ships robust headless APIs (REST and GraphQL) and native Next.js support, including an official SDK and starter templates. \[[source](https://www.progress.com/documentation/sitefinity-cms/headless-api-reference?ref=artisancraft.dev)\]

In this guide, we’ll look at how Sitefinity and Next.js fit together in practice: the architecture, how to get started, and how to wire up real content and widgets without guesswork.

---

## Why Sitefinity + Next.js works well

Sitefinity DX provides:

- **Headless APIs** via REST/OData and GraphQL, exposed through configurable “web services” in the backend. \[[source](https://www.progress.com/documentation/sitefinity-cms/for-developers-client-side-programming-and-web-services?ref=artisancraft.dev)\]
- **Native Next.js support**, including a Next.js renderer and tooling for hybrid setups (some pages rendered by Next.js, others still by Sitefinity). \[[source](https://www.progress.com/documentation/sitefinity-cms/develop-with-nextjs?ref=artisancraft.dev)\]
- An official **Next.js SDK** (`@progress/sitefinity-nextjs-sdk`) that wraps the REST API and provides widgets, typings, and helper APIs for building integrations. \[[source](https://github.com/Sitefinity/nextjs-sdk?ref=artisancraft.dev)\]
- A **Next.js samples repo** with a starter template you can clone or use via `create-next-app`. \[[source](https://github.com/Sitefinity/nextjs-samples?ref=artisancraft.dev)\]

On the other side, Next.js gives you React, server components, SSG/ISR/SSR, and a flexible routing model that works well with Sitefinity’s page layout service and APIs. \[[source](https://nextjs.org/docs/app/getting-started/layouts-and-pages?ref=artisancraft.dev)\]

The result is a clean separation: Sitefinity manages and personalizes content; Next.js takes care of rendering, UX and performance.

---

## Architecture in one picture

Conceptually, a typical setup looks like this:

- **Sitefinity DX**
  - content types, pages, taxonomies, media
  - personalization, workflows
  - headless APIs (REST/GraphQL, layout service)
- **Next.js renderer**
  - uses the Sitefinity Next.js SDK
  - renders pages based on layout service responses
  - exposes custom API routes and widgets
- **Browser / other channels**
  - consume the rendered pages (or JSON APIs)

Sitefinity’s docs describe this as a three-tier architecture where Sitefinity and a standalone Next.js app work together, and you can even mix “classic” pages and Next.js pages in one solution. \[[source](https://www.progress.com/documentation/sitefinity-cms/setup-next.js-renderer?ref=artisancraft.dev)\]

---

## Step 1 – Set up headless APIs in Sitefinity

Before you touch Next.js, you need your content accessible via APIs.

1. In Sitefinity, go to **Web services** and create a new service (or use an existing one).
2. Choose which content types (news, blog posts, dynamic modules, etc.) will be exposed.
3. Pick the protocol: REST/OData or GraphQL. GraphQL is configured through the same UI but uses a different protocol option. \[[source](https://www.progress.com/documentation/sitefinity-cms/for-developers-client-side-programming-and-web-services?ref=artisancraft.dev)\]

This gives you API endpoints for both content delivery and management, documented per service in the backend. \[[source](https://www.progress.com/documentation/sitefinity-cms/headless-api-reference?ref=artisancraft.dev)\]

---

## Step 2 – Bootstrap a Next.js project with the Sitefinity starter

Progress provides a Next.js starter template and an SDK that handle most of the plumbing:

1. Create a project from the official samples repo: \[[source](https://github.com/Sitefinity/nextjs-samples?ref=artisancraft.dev)\]

```bash
npx create-next-app nextjs-sitefinity \
  --example "https://github.com/Sitefinity/nextjs-samples/tree/main/src/starter-template"

```

1. Install dependencies:

```bash
cd nextjs-sitefinity
npm install

```

1. Configure environment variables in `.env.development` (from the README):
  1. `SF_CMS_URL` – URL of your Sitefinity instance
  2. `SF_ACCESS_KEY` – access key for your user (created in Sitefinity’s backend)

The starter already includes:

- `@progress/sitefinity-nextjs-sdk` as a dependency
- Next.js middleware that handles proxying and header rewriting for Sitefinity
- A catch-all route `src/app/[...slug]/page.tsx` that renders CMS pages via the layout service
- A widget registry where you can register your own React components

At this point, you can usually run `npm run dev` and see Sitefinity-powered pages rendered by Next.js.

---

## Step 3 – Rendering Sitefinity pages in Next.js

The Sitefinity Next.js SDK integrates with the **page layout service**: it requests layout and widget data for a given URL, then renders it via your React components. The starter template already wires this up in the app router. 

A simplified version of the root page component looks like this (shrunk to avoid copying the full sample):

```ts
// app/[...slug]/page.tsx
import { initRendering, RenderPage } from '@progress/sitefinity-nextjs-sdk/widgets';
import { widgetRegistry } from '../widget-registry';

export default async function Page({ params, searchParams }: any) {
  // Initialize rendering with your registry
  initRendering(widgetRegistry);

  // Ask Sitefinity for the layout & widgets for this URL
  return RenderPage({ params, searchParams });
}

```

The actual starter template adds more options (like requesting related fields and error handling), but the core idea is the same: **Sitefinity decides the layout and widget composition; your Next.js app decides how those widgets look**.

---

## Step 4 – Creating a custom widget (hero example)

A big advantage of the official SDK is that you can create custom widgets with:

- a React component for rendering
- an entity definition that drives the widget designer in Sitefinity
- registration in the widget registry

The “hero widget” example from EnsoDX shows exactly this pattern: a hero React component, a `hero.entity.ts` describing fields (title, subtitle, image, CTA button, etc.), and a registration step so editors can add this hero block from the Sitefinity page editor. \[[source](https://www.ensodx.com/posts/building-a-sitefinity-nextjs-hero-widget?ref=artisancraft.dev)\]

Conceptually:

```ts
// app/widgets/hero/hero.tsx
import React from 'react';
import type { WidgetContext } from '@progress/sitefinity-nextjs-sdk/widgets';
import type { HeroEntity } from './hero.entity';

export async function HeroWidget(props: WidgetContext<HeroEntity>) {
  const { Title, Subtitle, BackgroundImage, CtaText, CtaUrl } = props.model.Properties;

  return (
    <section className="hero">
      <h1>{Title}</h1>
      {Subtitle && <p>{Subtitle}</p>}
      {CtaUrl && (
        <a href={CtaUrl} className="btn">
          {CtaText}
        </a>
      )}
    </section>
  );
}

```

The entity file and registration follow the patterns in the docs and the samples repo; once registered, the widget appears in the Sitefinity toolbox and is editable by non-developers.

---

## Step 5 – Using the REST SDK from custom API routes

Besides layout rendering, you can call Sitefinity’s REST API directly using the **REST SDK** exposed by the same package:

```ts
import { RestClient } from '@progress/sitefinity-nextjs-sdk/rest-sdk';

```

The `RestClient` is a static class with methods like `getItems`, `getItem`, `getNavigation`, `performSearch`, etc., taking typed argument objects (`GetAllArgs`, `ItemArgs`, and so on).

The samples repo shows how to use this in a Next.js **route handler** to fetch navigation:

```ts
// app/api/navigation/route.ts
export const dynamic = 'force-dynamic';

import { NextResponse, NextRequest } from 'next/server';
import { RestClient } from '@progress/sitefinity-nextjs-sdk/rest-sdk';
import { headers } from 'next/headers';
import { initServerSideRestSdk } from '@progress/sitefinity-nextjs-sdk/rest-sdk'; // imported in the starter

export async function GET(request: NextRequest) {
  const isEdit = request.nextUrl.searchParams.get('sfaction') === 'edit';
  const siteId = request.nextUrl.searchParams.get('sf_site');
  const culture = request.nextUrl.searchParams.get('sf_culture');

  const host = (await headers()).get('host') || '';

  await initServerSideRestSdk({
    host,
    additionalFetchData: { next: { revalidate: 60 } },
    queryParams: {
      sf_culture: culture ?? '',
      sf_site: isEdit ? siteId ?? '' : '',
    },
  });

  const args: any = {
    selectionModeString: '',
    levelsToInclude: 3,
    showParentPage: false,
    selectedPages: undefined,
  };

  const items = await RestClient.getNavigation(args);

  return NextResponse.json(items);
}

```

This example is based on the official sample in the Next.js starter template and uses the same pattern: initialize the SDK with host, culture and site, then call `RestClient.getNavigation` with `GetNavigationArgs`.

You can use the same approach with other `RestClient` methods (for content lists, search, taxonomies, etc.), always following the argument shapes defined in the SDK’s TypeScript declarations.

---

## Step 6 – Headless, hybrid, or both?

One practical question is: do you go fully headless, or do you run hybrid?

Sitefinity explicitly supports a **Next.js renderer** alongside “classic” pages: you can host a Next.js app that renders some pages and let Sitefinity render others, while sharing the same content repository.

That gives you three realistic options:

1. **Pure headless**
  - All public pages go through Next.js.
  - Sitefinity is “just” a CMS and API layer.
2. **Hybrid**
  - New experiences (landing pages, apps, portals) use Next.js.
  - Legacy sections keep their existing MVC / WebForms rendering and are whitelisted in the renderer.
3. **Progressive migration**
  - Start by moving only high-value pages to Next.js.
  - Gradually migrate the rest without a big-bang rewrite.

Because the official renderer and SDK are maintained by Progress and released alongside Sitefinity, you’re not building on a random community integration.

---

## Best practices and things to watch

A few practical tips, based on the official docs and samples:

- **Model your content carefully** – if you plan to reuse content across multiple frontends (web, mobile, microsites), keep content structures presentation-neutral.
- **Use the SDK’s caching options** – environment variables like `SF_SDK_CACHE` and `SF_SDK_CACHE_REVALIDATE` let you control how Next.js data caching behaves for REST calls.
- **Secure your APIs** – use access keys, HTTPS, and proper scopes; Sitefinity’s docs cover access keys and security best practices.
- **Leverage widget designers** – the `@progress/sitefinity-widget-designers-sdk` lets you define friendly designers for your custom widgets so editors get a good UX when filling in data.
- **Monitor performance** – the diagnostics module in the SDK supports tracing REST calls and widget rendering using OpenTelemetry, which is especially useful on complex pages.

---

## Conclusion

Headless Sitefinity with Next.js is not a theoretical pattern anymore; it’s an officially supported, well-documented setup with a maintained SDK, starter templates, and real-world examples.

- Content teams keep using Sitefinity’s familiar backend, personalization and workflows.
- Developers get a modern React/Next.js front-end stack with strong APIs and typed helpers.
- Architecture stays flexible enough to support headless, hybrid, or gradual migration.

If you’re already on Sitefinity and you’re considering a more modern frontend, the Next.js renderer and SDK are probably the most practical starting point you can pick right now.

[![CTA Image](https://storage.ghost.io/c/8f/6e/8f6ec642-540e-4f85-ac9b-beb628cb9cfd/content/images/2025/10/symbol-2.png)](https://www.artisancraft.dev/consulting-services/) 

I offer hands-on consulting to help you resolve technical challenges and improve your CMS implementations.

Get in touch if you'd like support diagnosing or upgrading your setup with confidence.

[Learn more ](https://www.artisancraft.dev/consulting-services/)