Enhance Qwik CLI to allow migrating automatically from Qwik 1 the Qwik 2

[GregOnNet]

Story

To make the experience migrating from Qwik 1.x to version 2, a developer should be able to do it with one single command.

Goal

• We provide a CLI command allowing developers to automatically migrate from version 1.x to version 2.

Tasks of the migration command

• [ ] Automatically change the scope-name from @builder.io to qwikdev (the name qwikdev is still discussed internally).
• [ ] Automatically update all dependencies of Qwik to the most recent version.

Migration Process

• Pretending we already implemented a command like qwik migrate-v2
• The developer would need to update qwik, before the command is available
• This means we need to implement the command and publish it as part of Qwik 1.x.

[!NOTE] The Angular CLI or NX download the newest version of the CLI before they execute updates and migrations to get the most recent updated. Since we start with this project, we require the developer to update Qwik manually to receive the migration command. Downloading a newer Version of Qwik and then executing the update, might be out-of-scope for us.

flowchart TD
    A[npm install @builder.io/qwik@^1] -->|Get version of Qwik providing migration command| B(qwik migrate-v2)
    B --> C{Execute Migration}
    C -->|Update scope in project| D[@builder.io => @qwikdev]
    C -->|Update Qwik dependencies| E["`
                @types/eslint
                @types/node
                @typescript-eslint/eslint-plugin
                @typescript-eslint/parser
                eslint
                eslint-plugin-qwik
                prettier
                typescript
                undici
                vite
                vite-tsconfig-paths
              `"]
   D & E--> L{{🎊 Complete Migration by telling a joke?}}

The chart illustrates the migration process

1. Install the most recent version of Qwik 1.x to get the migration command
2. Execute migration command
3. Rename the package scope from @builder.io to @qwikdev
4. Update Qwik's dependencies in package.json

🧪 integration tests

vite.config.ts

-  import { qwikCity } from '@builder.io/qwik-city/vite';
+ import { qwikCity } from '@qwikdev/qwik-city/vite';

tsconfig.json

-  "jsxImportSource": "@builder.io/qwik",
+ "jsxImportSource": "@qwikdev/qwik",

entry.dev.ts

- import type { RenderOptions } from '@builder.io/qwik';
+import type { RenderOptions } from '@qwikdev/qwik'; // ❓ @qwik/core?

entry.preview.ts

- import { createQwikCity } from '@builder.io/qwik-city/middleware/node';
+ import { createQwikCity } from '@qwikdev/qwik-city/middleware/node';  // ❓ What to do with deep imports? 

entry.ssr.ts

- import type { RenderToStreamOptions } from '@builder.io/qwik/server';
+ import type { RenderToStreamOptions } from '@qwikdev/qwik/server';  // ❓ Do we have sub-packages like this?
+ import type { RenderToStreamOptions } from '@qwikdev/server'; // 💡 Alternative would be @qwik/server
- import { renderToStream } from '@builder.io/qwik/server';
+import { renderToStream } from '@qwikdev/qwik/server'; 

root.tsx

- import {  QwikCityProvider,  RouterOutlet,  ServiceWorkerRegister} from '@builder.io/qwik-city';
+ import {  QwikCityProvider,  RouterOutlet,  ServiceWorkerRegister} from '@qwikdev/qwik-city';

component$

- import { component$ } from '@builder.io/qwik';
+ import { component$ } from '@qwikdev/qwik';

- import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
+ import { $, component$, useSignal, useStyles$ } from '@qwikdev/qwik';

- import type { QRL } from '@builder.io/qwik';
+ import type { QRL } from '@qwikdev/qwik';
- import { component$ } from '@builder.io/qwik';
+ import type { QRL } from '@qwikdev/qwik';

[GregOnNet]

Hey @shairez ,

Dmitriy told me about the renamings: @builder.io/ to @qwikdev/ (@qwikdev/qwik, @qwikdev/qwik-city etc)

To me @qwikdev/qwik has redundancies. 2 times qwik. Personally, I would prefer @qwik-dev over qwikdev, too. But if it was decided by the team I can live with it.

Did you discussed further renamings for the future to have cleaner package-names?

cc @dmitry-stepanenko

[GregOnNet]

Discussed with @shairez The package name is still debatable.

@qwikdev/qwik could still become @qwikdev/core.

cc @dmitry-stepanenko

[shairez]

So we have a couple of options here:

For org names: @QwikDev/ @qwik-dev/ @qwik.dev/ (like the website)

For packages: (let's say with @QwikDev/ as a prefix: @QwikDev/core @QwikDev/qwik

[GregOnNet]

@qwik.dev/core is good to read.

• The framework name Qwik stands out
• By accident we communicate the homepage-URL

I am concerned if a . in a scope-Name comes with trade-offs. 🤔 But we already have it in @builder.io. Maybe there are no problems to worry about.

[GregOnNet]

Hi @shairez,

currently, Qwik 1.x exposes sub-packages, e.g @builder.io/qwik/server. Will Qwik 2 preserve the existing package-structure, or do we plan changes in that area, too?

Could @builder.io/qwik/server become @builder.io/server?

I am asking, because we want to know if we just replace the scope-name or if we need to be capable of replacing whole import paths.

[GregOnNet]

@dmitry-stepanenko Do you know if all Qwik dependencies are mentioned in the chart that need to be updated?

[dmitry-stepanenko]

I also think that @qwik.dev/core is the best option among others.

I also think that we should name the CLI command qwik migrate-v2 instead of just qwik migrate, as I'd preserve the latter for real migration capabilities that we could prepare at a later point.

Will Qwik 2 preserve the existing package-structure, or do we plan changes in that area, too?

V2 seems to not have any changes to the structure, thus imports like @builder.io/qwik/server are still in place. And I'd doubt we should make any changes like @builder.io/server, because that would mean creating a separate package for things that are used internally in existing package and are not supposed to work separately. Like angular's way of distributing the framework with 10+ packages is a bit of an overkill IMO

Do you know if all Qwik dependencies are mentioned in the chart that need to be updated?

Dependency upgrade will consist of 3 parts:

• uninstalling @builder.io/qwik & @builder.ioqwik-city packages
• installing @qwik.dev/qwik & @qwik.dev/qwik-city packages (assuming the new name is @qwik.dev/*
• upgrading all Qwik's dependencies
  • @types/eslint
  • @types/node
  • @typescript-eslint/eslint-plugin
  • @typescript-eslint/parser
  • eslint
  • eslint-plugin-qwik
  • prettier
  • typescript
  • undici
  • vite
  • vite-tsconfig-paths

While bumping dependencies we should make sure we don't override those that are higher than what we'll be installing

Along with that it also makes sense to upgrade all internal integrations that qwik supports (things like qwik-react, qwik-worker etc). Probably it will be the best to check for integration existence and update corresponding names/files using separated logic.

[GregOnNet]

Would we need to check for the used node-version in order to install the correct @types/node package?

[GregOnNet]

I started looking where we need to extend the existing CLI. Here is something related to qwik add: https://github.com/QwikDev/qwik/blob/fcb56b0391a02493af72dca84af9f7fae538a2c3/packages/create-qwik/src/helpers/logAppCreated.ts#L25