npm package: @magnolia/cra-template-mgnl-react
Description: The base template for Create React App, integrated directly into Magnolia CMS.
Author: Magnolia Professional Services
Latest version: 1.0.8

# Create Magnolia SPA React App

![Magnolia International Ltd.](https://git.magnolia-cms.com/projects/DEMOS/repos/cra-template-mgnl-react/raw/magnolia.svg?at=refs%2Fheads%2Fmaster)

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:

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

3. Run the project:

```sh
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](https://hd.magnolia-cms.com/), or jump directly to the [SPA Documentation](https://hd.magnolia-cms.com/docs/getting-started/hello-spa).

### 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

```js
// 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:

```sh
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:

```js
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.

```properties
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.

```propoerties
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:

```sh
npm i --save-dev copyfiles
```

In the scripts, add the following new scripts:

```json
    "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:

```log
error postcss@8.1.9: 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.

```sh
npm install -g node
```