Back to the blog
  • Jan 25, 2022
  • --
Category Tech
External SPA 1200x628
Visual Editing for Your Next.js App and Other Front Ends

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.

Smoother Development

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

  title: 'React: Basic'
templateScript: /react-minimal-lm/webresources/build/index.html
dialog: spa-lm:pages/basic

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

  title: 'React: Basic'
baseUrl: http://localhost:3000
routeTemplate: '{{path}}?lang={language}'
dialog: spa-lm:pages/basic

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.

Magnolia Headless CMS

Manage content in one hub and reuse it across the web and all your channels. See why Magnolia is great for headless—no need to sacrifice authoring experience and enterprise features.

Smoother Deployment

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.

Meta-Frameworks, SSR, SSG, BFF, and Jamstack

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:

  • Act as a proxy to securely access data from other servers

  • Render pages using Server Side Rendering (SSR)

  • Render pages using Static Site Generation (SSG) to improve performance

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.

Next.js Demo

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.

Next.js SSR

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.

Next SSG

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:

  title: 'Next.js SSG: Basic'
baseUrl: http://localhost:3000
routeTemplate: '/api/preview?slug=/{language}{{@path}}'

Check It Out

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.

About the Author

Christopher Zimmermann Product Manager at Magnolia

Christopher is a product manager at Magnolia with an emphasis on developer experience & productivity. He helped introduce the ‘light development’ paradigm and is now focused on headless, hybrid headless and making integrations easier to implement. While trained in Physics in university, the buzz and wild west openness of software development drew him to a career as a programmer in product companies, creative web agencies, freelancing and startups. Christopher is an outdoors enthusiast who got started with backcountry camping in the USA, but is slowly getting the hang of finding a coffee and cake in a rustic hut at 3000+ meters altitude in the Swiss Alps.

Read more