Choosing the right front-end approach

Before starting your Magnolia project, one of the first decisions you make is how to build the front-end.

Magnolia supports two main approaches:

Headless development

Magnolia exposes content via APIs, and your front-end application (such as a React, Angular, Vue app or SSR framework like Next.js, Nuxt, or Angular SSR) takes full control of rendering.
FreeMarker-based development

Magnolia renders pages and components server side using templating and configuration.

Each approach offers unique advantages, and your choice shapes how content is delivered, how your front-end is structured, and how editors interact with the system.

This page compares the two approaches to help you understand:

How each rendering flow works
What your YAML and component setup looks like
How your editors and site visitors are affected
Infrastructure and SEO implications
Which Magnolia modules and features are available

Rendering flow comparison

Let’s start with how each approach handles rendering. This affects performance, SEO, and the server setup.

FreeMarker puts Magnolia fully in charge of rendering the final HTML response. In headless projects, Magnolia provides content via APIs, but the HTML is rendered by your application, either on the client or the server (for example, using SSR frameworks like Next.js or Nuxt).

FreeMarker	Headless
The user visits a URL in their browser. Magnolia receives the request. Magnolia renders the full HTML server side. Magnolia returns the rendered page to the browser. Magnolia has full control over the HTML structure and delivery.	The user visits a URL in their browser. The request is handled by the front-end server (not Magnolia). The front-end fetches content from Magnolia using REST APIs. The application renders the page client side or server side (for example, SSR with Next.js). Magnolia provides structured content, but rendering is fully external.

FreeMarker

Headless

The user visits a URL in their browser.
Magnolia receives the request.
Magnolia renders the full HTML server side.
Magnolia returns the rendered page to the browser.

Magnolia has full control over the HTML structure and delivery.

The user visits a URL in their browser.
The request is handled by the front-end server (not Magnolia).
The front-end fetches content from Magnolia using REST APIs.
The application renders the page client side or server side (for example, SSR with Next.js).

Magnolia provides structured content, but rendering is fully external.

Configuration and YAML Differences

The structure of YAML files in Magnolia is similar in both approaches, but how components and pages are rendered differs significantly.

In FreeMarker projects, templates are tied to .ftl files rendered server side. In headless setups, Magnolia sends content to your app, and the actual rendering is handled by your JavaScript app.

FreeMarker Headless

	FreeMarker	Headless
Component autogeneration	Supported. See Component autogeneration.	Supported since 6.2.35. See Visual SPA Editor.
Component inheritance	Supported. See Component inheritance.	Supported since 6.2.35. See Visual SPA Editor.
Component YAML definition	Magnolia renders the component templates. You specify which FreeMarker template is used to render the page: `templateScript: /hello/templates/components/hello.ftl renderType: freemarker`	The front-end server or browser renders the component templates. Component YAML definitions can be as simple as just the title property. The mapping between template names and JS components is in JS code. For more information, see the React, Angular, and Vue properties.
Dialog definition	Dialog definitions are fully decoupled from template rendering. There are no differences between the FreeMarker and headless templating approaches.
Page YAML definition	Page templates are rendered by Magnolia. You specify which FreeMarker template is used to render the page: `templateScript: /hello/templates/pages/hello.ftl renderType: freemarker`	Page templates are rendered by the front-end server or browser. You only specify the URL to load in the Pages app. `$type: spa baseUrl: http://localhost:3000 routeTemplate: '/\{language}\{\{@path}}'` The mapping between template names and JavaScript components is in the JS code. For more information, see React, Angular, and Vue.
Site Template Prototypes	Supported. See Template prototype.	Supported. See Template prototype. A headless template page must have: `$type: siteSpa` See Common template properties.

Component autogeneration

Supported.

See Component autogeneration.

Supported since 6.2.35.

See Visual SPA Editor.

Component inheritance

Supported.

See Component inheritance.

Supported since 6.2.35.

See Visual SPA Editor.

Component YAML definition

Magnolia renders the component templates. You specify which FreeMarker template is used to render the page:

templateScript: /hello/templates/components/hello.ftl
renderType: freemarker

The front-end server or browser renders the component templates.

Component YAML definitions can be as simple as just the title property.

The mapping between template names and JS components is in JS code. For more information, see the React, Angular, and Vue properties.

Dialog definition

Dialog definitions are fully decoupled from template rendering. There are no differences between the FreeMarker and headless templating approaches.

Page YAML definition

Page templates are rendered by Magnolia. You specify which FreeMarker template is used to render the page:

templateScript: /hello/templates/pages/hello.ftl
renderType: freemarker

Page templates are rendered by the front-end server or browser.

You only specify the URL to load in the Pages app.

$type: spa
baseUrl: http://localhost:3000
routeTemplate: '/\{language}\{\{@path}}'

The mapping between template names and JavaScript components is in the JS code. For more information, see React, Angular, and Vue.

Site Template Prototypes

Supported.

See Template prototype.

Supported.

See Template prototype.

A headless template page must have:

$type: siteSpa

See Common template properties.

Editorial and visitor experience

From the editor’s perspective, both models offer familiar tools. However, depending on how pages are rendered, some features, like personalization, SEO, and versioning, behave differently.

	FreeMarker	Headless
i18n (internationalization of template labels)	Done via i18n message bundles.	See the Magnolia blog post Internationalizing Template Labels in SPAs.
p13n (personalization)	Supported. See Personalization.	Supported. See Personalization. For headless templates, an extra step is required. See Personalization of headless SPA projects.
SEO/Social media sharing	FreeMarker templates are all server-side generated. All SEO/Social media sharing tags work correctly.	For all scenarios that render the site on the server (such as Next.js), all SEO/Social media sharing tags work correctly. For scenarios where JS fetches the page data on the client side in the user browsers, the SEO/Social media sharing tags might not work as expected.
Sitemap	The recommended approach is a sitemap generated using SOLR.	In the headless approach, Magnolia doesn’t render sites and lacks a comprehensive knowledge of the entire scope of the project structure. The SPA has this knowledge and should be tasked with rendering the sitemap by means of the Delivery API to retrieve Magnolia-managed pages or content app items for URL builds.
Versioning	Supported. See Versioning.	Restore works as expected. Show version works but, when fetching data from Magnolia, you must include a version number in the query parameters read from the iframe URL. Compare is not supported.

FreeMarker

Headless

i18n (internationalization of template labels)

Done via i18n message bundles.

See the Magnolia blog post Internationalizing Template Labels in SPAs.

p13n (personalization)

Supported.

See Personalization.

Supported.

See Personalization.

For headless templates, an extra step is required. See Personalization of headless SPA projects.

SEO/Social media sharing

FreeMarker templates are all server-side generated. All SEO/Social media sharing tags work correctly.

For all scenarios that render the site on the server (such as Next.js), all SEO/Social media sharing tags work correctly.

For scenarios where JS fetches the page data on the client side in the user browsers, the SEO/Social media sharing tags might not work as expected.

Sitemap

The recommended approach is a sitemap generated using SOLR.

In the headless approach, Magnolia doesn’t render sites and lacks a comprehensive knowledge of the entire scope of the project structure. The SPA has this knowledge and should be tasked with rendering the sitemap by means of the Delivery API to retrieve Magnolia-managed pages or content app items for URL builds.

Versioning

Supported.

See Versioning.

Restore works as expected.

Show version works but, when fetching data from Magnolia, you must include a version number in the query parameters read from the iframe URL.

Compare is not supported.

Infrastructure considerations

How you host, cache, and serve your Magnolia project depends on the front-end model you choose. With FreeMarker, Magnolia owns the rendering cycle. With headless, you’ll typically have a separate front-end server or CDN layer that must be configured accordingly.

FreeMarker Headless

Caching

Because Magnolia is responsible for serving the HTML to end users, Magnolia controls caching policies and browser caching policies (we can set response headers to make browser cache content).

Magnolia is responsible for Magnolia caching policies. Regarding browser caching, Magnolia can ONLY influence the requests coming to the Delivery API and assets stored in Magnolia. So only those requests reaching Magnolia via:

/.rest/*
/dam/*
/.imaging/*

You must set browser caching policies on the front-end server.

CDN

In a typical case where the CDN inherits the caching headers from the original source, Magnolia can influence all cache headers.

See the Caching row above.

In a typical case where the CDN inherits the caching headers from the original source, Magnolia can only influence the following cache headers:

/.rest/*
/dam/*
/.imaging/*

HTML document headers are set on the front-end servers.

See the Caching row above.

Redirects

Because all requests come to Magnolia, Magnolia controls various redirects using Virtual URI Mappings.

Magnolia can only serve redirects for:

/.rest/*
/dam/*
/.imaging/*

This is because only those requests go directly to Magnolia.

Other redirects must be handled by front-end servers as the initial requests arrive there.

One way of adding the ability to set redirects in Magnolia would involve creating a new Content App to create redirect mappings. The front-end server would then fetch the mappings from Magnolia and apply them.

Magnolia modules and features

Many Magnolia modules work the same regardless of rendering model. However, some modules rely on Magnolia’s control over HTML output, and may require adjustments or aren’t supported in headless projects. The table below summarizes which modules are supported and what to consider.

FreeMarker

Headless

A/B/n Testing

A/B/n Testing module.

Not supported on headless.

Campaign manager

Supported.

See Campaign manager module.

Supported.

See Campaign manager module.

For headless templates, an extra step is required. For information, see the comments in ticket SUPPORT-12091.

Commerce Connector

E-commerce module.

Supported.

Diff

Diff module.

Not supported on headless.

Form

Magnolia controls the HTML rendering. It allows the creation of forms and also renders them inside FreeMarker templates.

FreeMarker-based module allows adding the form processors and custom Java logic to consume and process the data after form submission.

You can use the Dynamic Form module (incubator version) to create forms. This module exposes the REST APIs to:

Fetch the JSON structure of the form, meaning the JS code needs to fetch the form and render it on its own.
Submit the form to store data entered by the user.

JavaScript Models

JavaScript Models module.

Not supported on headless.

Live Copy

Supported.

See Live Copy.

Supported.

See Live Copy.

Marketing Automation (Web-to-lead)

Marketing Automation integration framework.

Supported.

Marketing Tags

Magnolia has complete control over rendering the HTML Editors can use the Marketing Tags app to define various tags and Magnolia can add them when rendering the page HTML.

You must add the Delivery API endpoint to the existing Marketing Tags app.

The front-end server fetches the tags from Magnolia and applies them to the generated HTML.

MTK (Magnolia Templating Kit)

MTK module.

Not supported on headless.

Multisite

Multisite module.

Supported.

Pages

Pages module.

Supported.

Personalization

Personalization module.

Supported.

Public User Registration

Public-User-Registration module.

Not supported on headless.

User-based search result ranking

User Result Ranker module.

Not supported on headless.

Summary

Choosing between FreeMarker and headless depends on your project’s goals, team expertise, and technical architecture:

Headless is a strong choice if you’re using a modern front-end framework, want full rendering control, or are building a decoupled setup.
FreeMarker suits projects where Magnolia handles rendering and a classic CMS architecture is preferred.

You can always revisit this choice later, but it’s best to start with the model that aligns with your long-term strategy.

Next, learn how to jumpstart a headless project or [set up a FreeMarker-based project.