Jumpstarting a headless Magnolia project

After creating a new project directory and running the Magnolia CLI jumpstart plugin, you’re prompted to choose from available templates:

? Choose a template
  1) standard-webapps (Magnolia without any content)
  2) demo-webapps (Magnolia with travel demo)
  3) headless (Magnolia with headless starter projects)

Select 3) headless and press Enter.

Selecting a starter project

Next, choose a starter project for your desired front-end framework. These Magnolia starter projects provide a consistent and structured setup for headless development.

? Choose a template
  1) angular-starter
  2) react-starter
  ...

For this guide, select 2) react-starter.

Choosing a Magnolia edition

You’re also prompted to select a Magnolia Edition:

? Choose a template
  1) dx-core
  2) ce

For this guide, select 2) ce (Community Edition).

Understanding the project structure

The react-starter template provides an example project that demonstrates how to work with Magnolia in a headless setup. After downloading, your new project directory includes:

  • .magnolia/apache-tomcat/ - Tomcat with Magnolia webapp

  • light-modules/spa-lm/ - Light module with components, pages, and configuration

  • spa/ - React application folder

  • mgnl.config.js - Configuration for Magnolia CLI and its plugins

Key concepts of headless development

When using Magnolia in a headless setup, your front-end application is responsible for rendering content retrieved from Magnolia via REST APIs.

Component mapping

To display Magnolia content in your front-end app, you must map Magnolia templates to front-end components.

This is done using a component mapping file, located here in the React starter project: spa/src/magnolia.config.js

It contains code that connects Magnolia template identifiers (like spa-lm:components/Banner) to the corresponding component source files (like Banner.jsx).

Learn more in the Mapping between Magnolia and SPA components page.

For more information about the React starter project structure, see the README.md in the spa/ folder.

Magnolia CLI configuration

Some important values inside mgnl.config.js:

...
plugins: [
  new CreateComponentPlugin({
    ...
  }),
  new CreatePagePlugin({
    ...
  }),
  ...
],
type: "jsx",
lightModulesPath: "./light-modules",
lightModule: "spa-lm",
componentMappingFilePath: "./spa/src/magnolia.config.js"

Configuration breakdown

These settings allow Magnolia CLI to set up and map pages and components inside your React app.

Setting Description

type: "jsx"

Enables React JSX template generation

lightModulesPath

Directory where Magnolia light modules are stored

lightModule

Default module used for new Magnolia config items

componentMappingFilePath

Path to mapping file for connecting React components and pages to Magnolia templates

CreateComponentPlugin

Magnolia CLI plugin for creating Magnolia component templates and front-end components based on the plugin configuration

CreatePagePlugin

Magnolia CLI plugin for creating Magnolia page templates and front-end pages based on the plugin configuration

Creating pages and components with CLI

Magnolia CLI provides plugins that work with React projects using @magnolia/cli-react-prototypes.

Create a new page template

To create a new page template, run:

npm run mgnl -- create-page HomePage

This command:

  • Creates a new file for the React page: ./spa/src/app/templates/pages/HomePage.jsx

  • Creates a YAML page template definition in the light modules folder

  • Updates spa/src/magnolia.config.js with the new page mapping

Create a new component

To create a new component inside the HomePage, run:

npm run mgnl -- create-component Banner -a HomePage

This command:

  • Generates ./spa/src/app/templates/components/Banner.jsx

  • Creates a YAML component template definition in the light modules folder

  • Adds component mapping in spa/src/magnolia.config.js

  • Registers the component inside the main area of the HomePage template

View the component mapping

Open spa/src/magnolia.config.js and you see mappings like:

import BannerComponent from './app/templates/components/Banner.jsx'
import HomePagePage from './app/templates/pages/HomePage.jsx'
...

const config = {
  componentMappings: {
    ...
    "spa-lm:pages/HomePage": HomePagePage,
    "spa-lm:components/Banner": BannerComponent
  },
};

export default config;

Starting Magnolia CMS

In the project root, run:

npm run mgnl -- start

After the Magnolia instance is successfully started, visit http://localhost:8080.

Login

Go to http://localhost:8080/magnoliaAuthor and sign in as a superuser :

  • Username: superuser

  • Password: superuser

Magnolia is ready to use and gives you a list of suggestions to get started.

superuser is a system administrator account that has permissions to do everything. It’s useful for testing.

Starting the React app

In the new terminal window, run:

cd spa
npm install
npm run dev

Visit http://localhost:8181 to view your front-end app fetching content from Magnolia.

Creating pages and content in Magnolia

  1. Open the Pages app in AdminCentral.

  2. Create a new page using the HomePage template.

  3. Add the Banner component to the main area of the page.

  4. Refresh http://localhost:8181 to see your new content coming from Magnolia and rendered in your React app.

Next Steps

You successfully jumpstarted a headless Magnolia project with React.

Here are some ideas for what to explore next:

  • Customize your prototype - configure your CLI plugins

  • Create your own CLI plugin - create a plugin to match your exact needs

  • Create your first content app and content type and render the content in your React app

  • Use REST APIs - Review restEndpoints/delivery config in spa-lm and visit the Delivery API documentation

  • Learn about the Magnolia React Editor @magnolia/react-editor

Want to try FreeMarker next?

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules