Create Magnolia SPA React App

This project will enable anybody to easily create a new project for Front-end Development with Magnolia and React. Rather than re-using an existing Git project, they can start with a clean project (aside from the simple example page and components).

Once they've created their new project, they simply need to point the .env files to the proper server location, and add their REST endpoints. To get it to work with a Magnolia Light Module, they just need to run yarn build or npm run build, and copy the build directory to the Light Module's webresources directory.

A more in-depth set of instructions will replace the following sections to help aid new developers.

Usage

NOTE: This is for usage before the project is published to NPM. Once it is published, it will be as simple as running:

• For Standard React Projects:

npx create-react-app [PROJECT_NAME] --template @magnolia/mgnl-react

3. Run the project:

cd [PROJECT_NAME]
yarn start

4. Verify the project by opening http://localhost:3000. You do not need a running Magnolia instance as this loads some mock data (see file:./mgnl-create-react-app/packages/cra-template-mgnl-react/template/public/exampleData/pages.json )

Follow this link if you'd like to learn how to build Magnolia Headless Development, or jump directly to the SPA Documentation.

Register the Service Worker

1. Open template/src/index.js
2. Change serviceWorkerRegistration.unregister(); to serviceWorkerRegistration.register();

Remove PWA Capabilities (Work Offline)

By default, this project provides you with a Progressive Web App (PWA). If you would like to run this as a standard React Application, simply do the following:

1. Open template/src/index.js
2. Remove import * as serviceWorkerRegistration from './serviceWorkerRegistration';
3. Remove

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://cra.link/PWA
serviceWorkerRegistration.unregister();

4. Save the file.
5. Remove template/src/service-worker.js
6. Remove template/src/serviceWorkerRegistration.js

Make it Yours

When you're ready to wire up your Magnolia environment with the new project, you can take the following steps to remove the demo code and run against your Magnolia environment.

Remove the demo code

Run the following from your React App directory:

rm -rf ./public/exampleData
rm ./src/logo.svg
rm -rf ./src/pages/*
rm -rf ./src/components/*

Remove the componentMappings from ./src/magnolia.config.js by replace the contents with:

const config = {
    'componentMappings':{
        // Page Components
        // Components
    }
};

export default config;

Replace the .env file with these contents. Keep in mind, this is assuming that you are deploying your Author instance to the webapp called magnoliaAuthor. If it is not that, just replace it with the name of your webapp. If you are not using a public instance, you can leave it along as it won't matter, but if you are, make sure the name is correct.

PUBLIC_URL=
REACT_APP_MGNL_HOST=http://localhost:8080
REACT_APP_MGNL_IS_PREVIEW=true
REACT_APP_MGNL_DAM_RAW=http://localhost:8080
REACT_APP_MGNL_LANGUAGES="en de"
REACT_APP_MGNL_BASE_AUTHOR=/magnoliaAuthor
REACT_APP_MGNL_BASE_PUBLIC=/magnoliaPublic
REACT_APP_MGNL_APP_BASE=
REACT_APP_MGNL_API_TEMPLATES=/.rest/templateDefinition/v1
REACT_APP_MGNL_API_PAGES=/.rest/delivery/pages/v1
REACT_APP_MGNL_API_NAV=/.rest/delivery/pagenav/v1

The same goes for the .env.mgnl file, replace the contents and the webapp names appropropriately.

PUBLIC_URL=/magnoliaAuthor/.resources/bookshelf/webresources/build
REACT_APP_MGNL_HOST=http://localhost:8080/
REACT_APP_MGNL_BASE_AUTHOR=magnoliaAuthor
REACT_APP_MGNL_BASE_PUBLIC=magnoliaPublic
REACT_APP_MGNL_APP_BASE=/
REACT_APP_MGNL_IS_PREVIEW=true
REACT_APP_MGNL_API_PAGES=/.rest/delivery/pages/v1
REACT_APP_MGNL_DAM_RAW=http://localhost:8080
REACT_APP_MGNL_LANGUAGES="en de"

Update Scripts

This is just a suggestion, but will make your life easier. You should add a couple scripts to your package.json file to make deployment easier. These scripts will depend on copyfiles, so first run:

npm i --save-dev copyfiles

In the scripts, add the following new scripts:

    "clean": "rimraf dist && rimraf ../../light-modules/MY-LIGHT-MODULE/webresources/build",
    "deploy:mgnl": "yarn build:mgnl && copyfiles -u 1 \"build/**/*\" ../../light-modules/MY-LIGHT-MODULE/webresources/build"

Pay attention to the relative path used here. Make sure to update it to the proper path to your Magnolia Resources directory (i.e. light-modules).

Also, change the MY-LIGHT-MODULE to the name of your light module that you plan to deploy to.

Potential Issues

You may see an error like this:

error [email protected]: The engine "node" is incompatible with this module. Expected version "^10 || ^12 || >=14". Got "13.12.0"
error Found incompatible module.

For this issue, you'll need to upgrade your version of node.

npm install -g node