RFC Qwik Migrations

[shairez]

Discussed in #215

Champion: @dmitry-stepanenko

^{Originally posted by shairez January 26, 2025}

What is it about?

Adding a qwik migrate cli command to migrate between versions

What's the motivation for this proposal?

Problems you are trying to solve:

• Migrating between versions of Qwik can sometimes require manual updates, especially for larger codebases.
• Developers may struggle to keep up with breaking changes or best practices introduced in newer versions.
• Lack of an automated tool for upgrades can slow down adoption of new features and improvements in the framework.

Goals you are trying to achieve:

• Provide an automated and guided way to migrate Qwik projects to newer versions.
• Reduce the time and effort needed to upgrade projects, especially for large-scale applications.
• Ensure that migrations are smooth and consistent, with minimal manual intervention.
• Offer a reliable way to identify breaking changes and recommended updates for both code and configuration.

Any other context or information you want to share:

This feature would be inspired by similar tools like Nx Migrate and Angular Upgrade, which are widely used and valued in their respective ecosystems. They help ensure that upgrading a project is a seamless process. A similar capability for Qwik would provide significant value to the developer community, especially as Qwik continues to grow and evolve.

---

Proposed Solution / Feature

What do you propose?

(suggested by @dmitry-stepanenko )

• we should be able to migrate versions and provide code migrations
• user should be able to see the list of migrations and opt-out before running the whole thing
• migrations should be tied to a specific version of qwik
• we should support both standalone repos and monorepos
• it should be compatible with qwik-nx plugin (probably as a wrapper from qwik-nx side, no Nx code should be involved)
• use ts-morph for code migrations (alternatives?)
• 3rd party migrations support?

Code examples

# Basic usage  
qwik migrate  

# Specify a target version  
qwik migrate --to 2.0.0  

# Dry-run to preview changes  
qwik migrate --dry-run  

# Use a migration script for a specific package (e.g., Qwik UI)  
qwik migrate --package qwik-ui  

---

Links / References

Prior art:

https://nx.dev/nx-api/nx/documents/migrate

https://angular.dev/cli/update