Nuxt3 Refactoring Project

BOEL's corporate website underwent a complete redesign in 2020.
The previous site used WordPress as the base for dynamic content such as TIPS and NEWS, while static sections were built in plain HTML. With the full redesign, we transitioned to a JAM stack architecture built with Nuxt.js.
We gave a brief introduction to Nuxt.js in TIPS Vol.107: "Building a Todo List with Nuxt.js" — feel free to check it out if you're interested.

Since the redesign, we had been working on performance improvements in parallel with UI enhancements and content expansion.
In the meantime, with the release of Nuxt3's beta in December 2021 and its release candidate (RC) in April 2022 — as the Vue3-compatible version of the framework — we launched a refactoring project centered around Nuxt3.

Before diving into the refactoring work, we first reviewed the site's overall structure and identified known pain points in order to define the direction for this project. In addition to performance improvements, the requirements incorporated long-standing internal requests — such as extending CMS functionality beyond Insights — as well as user-facing requests including the launch of RSS feeds, AMP support, and the addition of previously unimplemented content such as an English-language version of the site.

For the CMS migration, we decided to move from Flamelink — which had been used for TIPS — to microCMS, based on considerations of development ease and long-term maintainability.

The requirements also included systematically building out an ecosystem — encompassing the development of a design system as well as the organization of documentation such as basic design documents, site specification sheets, and coding guidelines — so that team members could use these as a solid foundation for future projects.

The following were the key priorities we focused on for this refactoring project:

When migrating our site from Nuxt2 to Nuxt3, we had the option of using Nuxt Bridge as an intermediate migration build, but we deliberately chose not to use it.<br>The reason was that during the previous site redesign in 2020, the work had been carried out in a rushed manner — including team members who were not yet familiar with Nuxt.js — leaving the source code messy and poorly maintainable. For this reason, we agreed as a team to take the opportunity of this refactoring to move directly to Nuxt3, also adopting the new Composition API and script setup syntax in place of the Options API we had been using.

We began by migrating all pages from the Options API to the Composition API and the script setup syntax.

Key changes

That said, rushing the migration all at once would have led to frequent issues, so we proceeded incrementally, starting with static pages that had less content.<br>When rewriting the code, we extracted logic that had been duplicated across multiple pages into functions, consolidating it along with what had previously been written in mixins into Composables. We also broke down larger, coarser-grained components into smaller, more granular ones.

In addition, the following tasks were addressed in line with current trends:

As the page-by-page migration progressed, we began encountering issues that proved difficult to resolve.

The first issue was the breadcrumb list displayed in the footer.<br>In Nuxt2, we had used EventBus to detect page transitions, but since EventBus had been deprecated, an alternative approach was needed. We struggled with issues such as the breadcrumb displaying correctly but failing to respond properly to page transitions — showing the previous page's information instead. Ultimately, we resolved this by using useState() — a new feature in Nuxt3 — to update the state at the onMounted timing.

Around the time we updated to RC10, changes occurred in how partial SCSS files — which had been used to consolidate reset CSS and variables — were loaded, causing style priorities to shift across all pages and resulting in layout breakages.<br>To address this, we specified the globally loaded SCSS files through the Vite configuration in nuxt.config, and also separated SCSS files by page and component to narrow their scope, so that any future breakages would have a limited impact.

At the start of the refactoring development, Nuxt3 was still in the release candidate stage and had not yet reached its official release. This made it prone to bugs, and the relatively small user base meant that gathering information was a challenge.<br>We referred to the official documentation as it was progressively developed, and there were times when we researched similar cases in the Nuxt3 GitHub repository's Issues and Discussions sections to find solutions.

While some issues were resolved over time, there were also plugins and modules that were not yet compatible with Nuxt3. In some cases, we built custom solutions to address these gaps.

Beyond the issues mentioned above, various other problems continued to arise and had to be addressed as they came up. As a result, development did not proceed as planned, and the project suffered delay after delay — at times seemingly returning to square one.<br>The uncertain state of development, juggling schedules with other projects, the passage of time — a combination of factors weighed on team morale, and there were even moments of friction between members.<br>We reorganized our development structure, took stock of the situation, and made a fresh start. Finally, in January 2023, we successfully completed the switch to the refactored version of our own website.

Regarding performance improvements — one of our key objectives — the number of flagged issues has decreased and overall scores have improved compared to before the redesign. There is still room for further improvement, and we will continue working on it going forward.

Around the same time as the site switchover, Nuxt3 continued its minor version updates, and a major update — version 3.3.1 — has since been released. (As of March 2023)

Release Notes

An image format for the Web

To minimize the impact on the website, we create a separate update branch, verify the changes, and then apply them to the production environment.
We plan to continue updating to the latest releases as they become available.

With the site version upgrade complete, we now plan to move forward with planning new content, updating existing content, and expanding what we offer.<br>From subtle refinements to more visually significant overhauls, we will continue to evolve and improve — always.

Having begun development before the stable release, we worked in an environment where adoption examples were still scarce. Nevertheless, being among the early adopters of the latest technology for our refactoring work deepened our understanding and expertise with Nuxt3.<br>We hope this account proves helpful for anyone undertaking a similar refactoring project or working with Nuxt3.