Moving From Vue 1 To Vue 2 To Vue 3: A Case Study Of Migrating A Headless CMS System — Smashing Magazine

Prototype Roots and Two Kinds of Migration

Storyblok’s front end has lived on Vue since late 2015, when the team built a full prototype on a framework that was still pre-1.0. The bet paid off well enough that Vue remains the foundation of the interface today, and the company has since contributed back to the ecosystem through open-source projects and community activity.

That history produced two very different upgrade efforts. The first, from Vue 1 to Vue 2, coincided with the product's shift from Storyblok Version 1 to Version 2 and was handled as a ground-up migration: a brand-new codebase rather than an incremental update. The second, from Vue 2 to Vue 3, was a soft migration, where the existing code was upgraded in the background with no visible change to the interface.

A ground-up migration offers more freedom over architecture and design, but it is resource-intensive. For Storyblok, that flexibility enabled the development of the open-source Blok Ink design system as the core of the new version, something customers could later reuse for their own extensions. The soft migration, by contrast, is quicker and cheaper but constrained by the existing design and architecture. It is also easier on users, who do not have to relearn an interface, and it avoids large marketing and communication efforts.

Why Rebuild From Scratch

Storyblok launched as a product in 2017 on Vue 1 and kept adding features. After the first seed investment in 2019, the team had room to grow. In 2020, about five developers started on Storyblok V2. Rather than port the old Vue 1 code forward, they began with an empty repository. The decision gave the new team two advantages:

1. Developers were fully involved in designing the architecture of the new system.
2. They learned how the system worked by rebuilding it.

In hindsight, that call was the right one. It produced a more stable, more modern version of the prototype while giving the team real understanding of the internals. The costs were time, resources, and persuading customers to move to the new version.

The Vue 2-to-Vue 3 upgrade was a different equation. That migration required updating large portions of code and verifying that everything still behaved correctly. Teams also had to invest in retesting the interface and in developer time to learn the Vue 3 changes. That is harder at scale, where different codebases and competing business needs exist.

The right approach depends on context. Relevant factors include:

• The resources and expertise available;
• The size and complexity of the system;
• How much control is needed over the resulting design and architecture.

Whatever path is chosen, a clear plan matters. The next section covers what that plan looked like in practice.

Five Factors That Shape A Major Framework Migration

Framework migrations rarely fail because of technical complexity alone. The harder problems are organizational: getting buy-in, sequencing work, and keeping users confident while the ground shifts beneath them. Based on a migration path that took our team from Vue 1 through Vue 2 and into Vue 3, five factors consistently determined how smoothly each transition went.

Build A Realistic Timeline

Migrations add no visible features, which makes them a hard sell to product owners and clients. But delaying them only compounds the cost. The longer a codebase sits on an outdated foundation, the more the gap grows between what the team could build and what the framework actually supports.

In the long term, migrations are necessary, and the longer you put them off, the harder they will become.

Our Vue 1 to Vue 2 effort took roughly two years end to end:

• Before mid-2020: New features continued to ship in the old version.
• June 2020: Core components were identified and rebuilt in a new open-source design system.
• November 2020: A fresh Vue 2 project was created.
• November 2020 to August 2021: Every part of the old app was redeveloped against the new design system.
• August 2021: A beta release covered major areas like the Visual Editor.
• August 2021 to August 2022: Missing functionality was restored, new features were added, and UX improvements came from customer feedback.
• August 2022: The new application officially launched.

Along the way, more than 20 developers, designers, QAs, and product owners were onboarded onto the new stack.

The Vue 2 to Vue 3 migration was faster — around eight months — largely because the hard work of rebuilding from scratch was already done:

• July to November 2022: The design system was migrated to Vue 3.
• November 2022 to January 2023: Breaking functionality was removed, and dependencies tied to Vue 2 were updated or replaced.
• December 2022: Developers and stakeholders were briefed on what changed in Vue 3 and how the transition would run.
• January 2023: The Vue 3 codebase was introduced, teams moved over, and thorough testing began.
• February 2023: The Vue 3 version went live in production.

Before any of this scheduling can happen, the migration's parts need to be identified. A simple spreadsheet or a planning tool like Jira works for this. Splitting different functional areas into separate sheets helps assign them to the teams that will own them.

Prioritize Functionality Before Code

Migrating an entire system in one pass is expensive and risky. The better approach is to rank features by importance and move them incrementally. When we rebuilt Storyblok from the ground up, we started with the Visual Editor — the product's core differentiator — and built a fresh version of it on top of the new design system.

Before starting any migration, answer these questions:

• Is the goal a completely new version of the product, or a like-for-like port?
• What distinct parts does the system have, and can any be migrated independently?
• Which features matter most to customers?
• Who knows the system well enough to guide the work?
• Should every developer work on the migration, or should a small set of experts focus on it?
• Can the total effort be estimated? If not, can smaller sub-systems be broken out to produce better estimates?

Independent sub-parts can be assigned to different people, which helps parallelize the work. Who does the migration matters just as much as what gets migrated. During the Vue 1 to Vue 2 move, all developers pitched in to build the new functionality. For Vue 2 to Vue 3, a single expert performed most of the migration and then handed the updated codebase to feature teams for testing and finishing. Training sessions gave those teams a deeper look at Vue 3's breaking changes.

The core of the migration strategy always depends on the knowledge of the system as well as the importance of the features to be migrated.

Automate The Tedious Parts

Manual edits across hundreds of files waste time and introduce errors. Automation pays for itself quickly when it targets repetitive, predictable changes.

For the Vue 2 to Vue 3 migration, the migration build and its linting rules surfaced most problem areas in the application. Hand-written scripts then iterated through all 600+ Vue files in the project to:

• Add missing emit notations automatically.
• Replace event names that changed in Vue 3.
• Update common logic in unit tests, such as adding the global notation.

Regex-based find-and-replace handled large logic chunks, but the final stretch still required manual fixing. Existing tests were valuable for catching regressions: Jest with Test Utils and the Vue Testing Library covered unit tests, while Cypress with various plugins handled end-to-end testing.

Keep Users In The Loop

A new version must not feel like a downgrade to the people using it. Continuous feedback during development is the safeguard.

During the ground-up Vue 1 to Vue 2 rebuild, we collected customer feedback while simultaneously rebuilding the app. This kept the work aligned with what customers actually wanted. Beta access was opened in stages — first the Partner Portal, then the Visual Editor, then content editing, and finally the remaining features. Each stage generated feedback that could be incorporated before the next area was exposed.

Ask these questions when planning communication with users:

• How can customer feedback be collected early and often during development?
• How will existing customers be told about the new version and encouraged to switch?
• Which communication channels will be used? Can marketing amplify the update's benefits?
• Who owns internal communication, and which stakeholders need regular status updates?

Our concrete tactics included feedback buttons in the interface that linked to a form for rating specific areas and leaving open comments. That feedback went to the design team for evaluation and follow-up. Discord channels gave developers a direct line, and interactive “tours” showed users where features lived. A button in the old app let users switch seamlessly between versions, and social campaigns generated excitement around the release.

Identifying stakeholders is critical in all of this. An impact/influence matrix clarifies who is affected by the migration and who should shape it. That determines who needs close contact and who can be updated less frequently.

Monitor Progress And Expect Roadblocks

A migration that spans months needs regular checks to confirm it stays on course. Useful review questions include:

• Have all areas to be migrated been defined, and how is progress tracked per area?
• Are stakeholders and users being communicated with effectively, and are their concerns addressed?
• Have unexpected issues emerged that require adjusting the budget or timeline?
• Is the new version properly validated before production release?
• Do final results meet user and stakeholder expectations?

Two roadblocks stood out during our transitions. The first was customer expectations. We had planned to change some UX patterns and deprecate features we were unhappy with. Customers pushed back — they wanted the new version to feel familiar. Over time, we backtracked on many of those changes to match the old behavior more closely.

The second was testing. Updating unit tests for Vue 3 took more effort than updating the application code itself. The testing phase for this “soft migration” was extensive, and finding and fixing all issues took more than three weeks. QA engineers were essential in identifying what had broken.

The production rollout used a blue/green deployment. Because the Vue 2 and Vue 3 apps looked virtually identical, we routed a subset of user traffic to the new version while the majority stayed on the stable old one. After a week of production testing with only a fraction of users, any remaining issues surfaced without disrupting the broader user base. Close coordination with Sales and Support teams — who had direct contact with important clients — was critical during this window.

What Two Major Rewrites Taught Us

Building the Vue 2 Version

The total rebuild of Storyblok in Vue 2 came with a clear lesson: migrations of this scale are especially hard for developers who are new to the codebase. Giving those developers real ownership of the architecture, quality, and product direction turned the migration into a training exercise as much as a technical one. Onboarding and structured training became necessary parts of the process.

Another advantage came from involving existing users early. By introducing new design and features incrementally across different areas, customers could adapt at their own pace. This gradual rollout also gave them a chance to report bugs and share feedback before the full release.

Customers carry certain baseline expectations for any software:

• Reliability and stability.
• Ease of use.
• Regular updates and improvements.
• Support and assistance.
• Security and privacy.

A large migration can threaten all of these. It is critical to weigh the potential impact on the customer experience and take deliberate steps to soften the transition.

Lessons from the Vue 3 Upgrade

As the company grew, keeping the production app stable became more critical. The investment in unit and end-to-end testing during the Vue 2 era paid off when we moved to Vue 3, as the test suite helped us catch regressions and bugs throughout the process.

Thorough testing of the migrated system proved non-negotiable. With careful planning and execution, most issues were found and fixed before the upgrade reached production.

Having a separate design system that could be migrated first was also a significant advantage. It gave us a smaller, safer environment to study the Vue 3 migration guide and apply its lessons before tackling the more complex application code.

Finally, we learned that communication is essential. We set up internal Slack channels so marketing and other teams could stay informed about functionality changes and new features. This let the right people weigh in on how those features were designed.

What We Would Do Again

Moving Storyblok through three major Vue versions was a challenge for the entire organization. A solid migration plan needs to define the sequence of work, which parts are rebuilt versus upgraded, who is responsible, and a realistic timeline.

Our key takeaways centered on developer involvement and training, plus honest communication with stakeholders. Users and internal teams both need to be heard so that their expectations are actually met.

Testing remains the backbone of a safe migration, and skilled QA engineers make a visible difference in how smoothly the transition runs. Two rollout strategies also worked well for us: releasing the new version to a subset of users first, and migrating individual system parts one at a time. We combined both approaches.

If you are planning a system migration of your own, start with a well-defined plan. Account for budget and schedule, reserve time for testing and validation, and keep monitoring progress so you can adjust the plan as work proceeds.

Bring existing users into the process to surface concerns early, and make sure that the migration will genuinely improve things for users or developers. Keep the internal lines of communication open throughout so that everyone remains on board. Consider either gradual, part-by-part migration or a limited rollout to manage complexity — or use both.

Above all, work With your team. A migration needs many hands and a lot of time, and the quality of your collaboration will determine whether it is a smooth journey or a painful one.