Visual Editing for Your Next.js App and Other Front Ends

The new External SPA feature in Magnolia 6.2.14 allows you to edit your apps in Magnolia’s Visual SPA Editor, while hosting your SPA on any server of your choice, taking full advantage of any of the popular meta-frameworks such as Next, Gatsby, Nuxt, or Scully.

Previously, in order to edit an SPA or other front-end projects in the Visual SPA Editor, aka Magnolia Page Editor, you had to host a copy of your front end on Magnolia. Now, you can host your front end on any server. This makes development much more comfortable, and unlocks working with these meta-frameworks.

Similar functionality was already available using the SPA Renderer Extended extension on our Marketplace. If you are using the extension, I recommend upgrading to the product feature at your earliest convenience.

While it was possible to host your production app anywhere, you previously had to build and deploy your SPA into a Magnolia Light Module after every update to be able to edit its pages using Magnolia’s visual editor. Now, you can develop your SPA as usual–typically on the dev server for the React, Vue, or Angular project–and simply point Magnolia to the URL that is hosting your front end. This eliminates the additional build and deploy steps during development.

The changes you make to your SPA will instantly show in the Magnolia Page Editor, without having to reload the page. Yes, even Hot Module Repleacement (HMR) is working.

Lets take a quick look at how this is configured.

Previously you had to specify a templateScript in your page template definition, telling the Page Editor where to load the JS bundle from.

file: templates/pages/basic.yaml

Now, you can specify a baseUrl3 and a routeTemplate instead. Together they specify the URL that the Page Editor loads, based on the page that is currently being edited in the Pages App.

The baseUrl specifies, you guessed it, the base URL of your front end. The routeTemplate specifies the rest of the URL. You can also add properties to be interpolated into the URL, for example {{path}} and {language}.

file: templates/pages/basic.yaml

Example: for a page with the path '/great-scott', the page editor would load the URL: http://localhost:3000/great-scott?lang=en

For more information, please consult our documentation.

And if you want to try it right now, check out our SPA demo projects for React, Vue, and Angular.

The previous setup meant that some projects would have two versions of the same app, one for editing and one for production. Now that you can host the front-end app that is used by the Magnolia Page Editor anywhere, you only need one version of your app.

Of course, you may have reasons to have two separate apps for editing and production but even then your life will be easier because both versions can be deployed using the same process–or any process you choose. For example, they could be built and deployed by Netlify or another CI/CD system every time you push code to your Git repository.

While many front-end projects consist of a single JavaScript bundle that is deployed on a simple file server and loading content via REST, more complex projects are increasingly taking advantage of hosting their front ends on a specialized server. This is sometimes referred to as "Backend for Frontend" (BFF).

The specialized development servers for front-end meta-frameworks like Next, Gatsby, Nuxt, and Scully can:

SSG and SSR has benefits for SEO, search indexing and the generation previews by social networks and tools like Slack.

Now that the Page Editor can load your app from any URL, you can use it with any of these specialized servers.

Want to see it in action? Our first meta-framework demonstration project is now available using Next.js. Have a look at the README in our demo projects repository.

You'll notice that we include two apps for Next.js: one for SSR, and one for SSG. Of course these are just simple examples. Depending on your needs, you will likely mix both techniques together.

For SSR and SSG it is important to note that some JS is running on the server instead of the browser. To accomodate this in Magnolia's react-editor library, you'll need to set the global.mgnlInPageEditor variable in your code.

Also, since you won't have access to browser objects, you can use the Next.js context object in your code, for example context.resolvedUrl instead of window.location.pathname.

Have a look at the /pages/[[...pathname]].js file for the key parts of the SSR implementation.

getServerSideProps runs on the server and gets the page content. useEffect() runs code in the browser. In the exported Pathname component useEffect retrieves the templateAnnotations once the page is loaded. This is important to display Magnolia’s green editing bars in the Page Editor.

Wait, SSG? How can you edit a page of a static site? The Next.js framework has a baked-in answer for this using their preview mode. The key concept is: "If you request a page which has getStaticProps with the preview mode cookies set, then getStaticProps will be called at request time (instead of at build time)."

So when generating the static site, getStaticProps runs for every page. But when editing the page in the Magnolia Page Editor, getStaticProps runs dynamically on the current page. This allows users to edit a page and instantly see the result of their change. To deploy this change into production a new build and push to the server or CDN is required, for example using a webhook.

In our SSG demo project, /pages/[[...pathname]].js is also the key file. It works in the same way as SSR, with getStaticProps performing the same duties as getServerSideProps in SSR mode. The so-called "preview API" is setup in /pages/api/preview.js.

The preview mode expects the app to be called using a certain slug query string. This is easily achieved in the page template definition using this routeTemplate parameter:

If you’re interested in Next.js, check out the SSR and SSG demo projects. You can probably get a Next.js project running in 15 minutes.

If you are already using the Visual SPA Editor in Magnolia, I recommend you try the new approach. You are going to love developing against your framework’s dev server. You just need to add the baseUrl and routeTemplate properties to your page template definitions and you’ll be ready to go in no time.