Adding CLI to existing projects

[thejackshelton]

@siguici I've noticed it seems like we could significantly improve usage by optimizing the workflow of existing projects. (which it's currently at an all time high organically!! 🎊 )

Adding to existing Astro projects is the most likely outcome I think, as many are coming from another framework and trying Qwik. I think we can be most helpful by having this first in the readme even, along with the creating new project docs right after it.

---

The "ideal" Developer Experience Goal:

• User should be able to spam "Enter" to get working defaults
• Zero-config approach where possible
• No need to understand JSX runtime conflicts
• CLI handles all the complex framework separation automatically

TLDR: "It just works" when you hit Enter 🚀

Perhaps something like:

npm create @qwikdev/astro@latest --add

which would be the equivalent of the current:

npm create @qwikdev/astro@latest . --add

I'm also noticing certain options are more suited for when a project is created from scratch.

---

> [email protected] npx
> create-astro .

│
◇  Do you want to add @QwikDev/astro to your existing project?
│  Yes
│
◇  Copy template files safely (without overwriting existing files)?
│  Yes
│
◇  Would you like to use the default template?
│  Yes
│
◇  Would you like to add CI workflow?
│  No
│
◇  Would you like to install npm dependencies?
│  Yes
│
◇  Would you like to initialize Git?
│  No
│
◇  What should be the name of this package?
│  test-existing-cli

These are the options I would pick if I was starting from an existing Astro project in the current CLI options. In this case, we likely already have git initialized.

---

The defaults could potentially be:

> [email protected] npx
> create-astro .

│
◇  Do you want to add @QwikDev/astro to your existing project?
│  Yes
│
◇  Copy template files safely (without overwriting existing files)?
│  Yes (maybe always safe? / removed) 
│
◇  Would you like to use the default template?
│  Yes (removed)
│
◇  Would you like to add CI workflow?
│  No
│
◇  Would you like to install npm dependencies?
│  Yes
│
◇  Would you like to initialize Git?
│  No (removed)
│
◇  What should be the name of this package?
│  test-existing-cli (removed)

My current thoughts, is the github readme should immediately go into:

## Have an existing project?

- [command across packages]

### [video showing it being added to an existing project]

## Create a new project

- [command across packages]

### [video showing a new project created]

rest of readme

A potential new option to the CLI init I think that would be beneficial:

Does your project have React, Solid, or Preact? (default: we need to collect some data points here in this case)

If they hit yes:

1. Adds an include statement pointing to the Qwik integration directory
2. Adds an exclude statement for other framework adapters
3. Places the tsconfig in the Qwik integration directory to prevent JSX runtime conflicts
   • Similar to how we handled Astro config documentation
   • Prevents jsxImportSource conflicts with other frameworks

https://github.com/kunai-consulting/public-astro-PoC/blob/main/src/components/qwik/tsconfig.json

similar to here

Example structure:

• ✅ Isolated tsconfig for Qwik
• ✅ Clear separation of framework-specific configs
• ✅ Documentation can be embedded directly in CLI-generated files

potential follow up:

• Where do you want to put your Qwik components? (default: src/components/qwik)

Thoughts? The CLI is so great already, and I defer to your judgement on this :)

[siguici]

These are great observations, and they come at the perfect time. I was actually thinking about how we could improve the CLI to enable integration with other JSX frameworks like React, Preact, or Solid.

Regarding adding to an existing project, the question about copying the template files is intended to allow the merging of files like tsconfig.json, .gitignore, package.json, as well as the copying of the source files from the base template (based on the user's choices), without overwriting files already defined in the user's project. Based on your remark, if the user is using another JSX framework, the files in src/components/ will be moved to src/components/qwik, or will remain as-is otherwise. I will also make sure to move the tsconfig.json from the selected template into the component directory without affecting existing configurations.

Regarding Git initialization, the current implementation could be improved. When the project already exists, it would make more sense to perform a commit for the addition of @qwikdev/astro, instead of a project initialization commit, if the .git directory already exists.

I will also adjust the order of the questions and the default responses, removing those that are unnecessary for adding to an existing project. I will take care of updating the README.md as mentioned earlier. However, I didn't quite understand the point about adding documentation to the generated files. Could you clarify that?

[siguici]

About Adding Multiple JSX Frameworks

If they say yes to having multiple jsx frameworks:

Ideally, their files could remain in the same place, and when they add the Qwik integration, it is a new qwik folder in the project, where the tsconfig inside has jsxImportSource scoped to that directory for Qwik

I think it can work without needing to touch their existing tsconfig.json. In the poc above we have a tsconfig for each framework.

You're absolutely right, and I fully agree. I'll take care of implementing this.

Currently, the CLI's approach is to copy all the files from the template matching the user’s options without overwriting any existing files—hence the prompt for copying template files. The idea is to allow integration into an existing project while leveraging a new template. This process copies only the missing files from the selected template into the working directory.

The goal is to provide a way to restore a project in case the user unintentionally deletes some of the template's files or wants to add them to their current project. The initial intent was to copy source (src, public) and configuration files (tsconfig.json, biome.json, etc.) without overwriting the user’s files.

About Git Initialization

Makes sense to me! Even more so that the commits would be what they have changed compared to the CLI, should make it even easier for reproductions and tracking down bugs 😄

Exactly! That’s precisely what I had in mind. The CLI already handles this case quite well, but the question is currently poorly phrased. I'll address this in my upcoming updates.

About Adding Documentation in Generated Files

Yeah! So I think in our cases the docs for these could be in the file we add them in.

tsconfig.json

/**

This is the tsconfig.json setup for the Qwik integration. When you added this file into your project, we also added an include statement in `astro.config.mjs`. Please be mindful of that when making any changes to this file.

@see https://docs.astro.build/en/guides/integrations-guide/react/#combining-multiple-jsx-frameworks
@see https://github.com/QwikDev/astro?tab=readme-ov-file#using-multiple-jsx-frameworks

 **/

Yes, I understood this well. I was referring specifically to this part of your explanation:

Example structure:

* ✅ Isolated tsconfig for Qwik

* ✅ Clear separation of framework-specific configs

* ✅ Documentation can be embedded directly in CLI-generated files

I was pointing to the last line regarding embedded documentation. Could you clarify it further?

[thejackshelton]

Ah for the embedded documentation I was mostly referring to the comments being as the "first line of fire" (first thing they see) when it comes to looking for help / guidance, with the docs being the last resort.

I wasn't aware of that with the templates! Perhaps we need a way to better explain that it only "diffs" with what is missing.

[siguici]

Ah for the embedded documentation I was mostly referring to the comments being as the "first line of fire" (first thing they see) when it comes to looking for help / guidance, with the docs being the last resort.

Ah, I get it now! 🧠 What you meant by embedded documentation is to have comments serve as the "first line of fire" 🔥 for users needing guidance, with external docs as a last resort. That makes total sense, and I'm fully onboard with this approach. I'll make sure to integrate it seamlessly! ✨

I wasn't aware of that with the templates! Perhaps we need a way to better explain that it only "diffs" with what is missing.

As for the templates, you're absolutely right—we should better explain that they act as a "diff" to identify what's missing and add only those parts. ⚡ This will avoid any confusion and help users better understand how we handle existing files. 📂

On managing conflicts with other JSX frameworks, I'll refine the implementation to ensure smooth integration. 🏗️

Honestly, with all these features, I think we're building the CLI of dreams. 🌟 At this point, I might stop using other CLIs altogether (just joking—or am I? 😏). Let's keep pushing the boundaries! 🚀

[thejackshelton]

Haha we have the best CLI I've seen, seriously 😆 . Maybe shadcn cli can compare in coolness

[siguici]

Haha we have the best CLI I've seen, seriously 😆 . Maybe shadcn cli can compare in coolness

Yes. Shadcn has a very advanced CLI.

[siguici]

If I understood correctly, here are the main changes and features to implement in the CLI:

1. Support for Multiple JSX Frameworks:

   • When a user integrates Qwik into a project already using another JSX framework (e.g., React, Solid), Qwik files will be placed in an isolated folder (src/components/qwik).
   • A dedicated tsconfig.json file will be added in this folder to scope jsxImportSource, without modifying existing configurations.

2. Improved Template Handling:

   • The CLI should only copy missing files into the project, avoiding overwriting existing ones.
   • A clear explanation of this process will be added to help users understand how it works.

3. Embedded Documentation in Generated Files:

   • Add detailed comments in generated files (e.g., tsconfig.json, astro.config.mjs) to guide users directly within the code.
   • These comments will include links to useful resources, allowing users to quickly access help or related guides.

4. Enhanced Git Management:

   • If a project already contains a Git repository, the CLI will create a specific commit for adding @qwikdev/astro instead of an initialization commit.
   • This will make it easier to track changes introduced by the CLI.

5. User Experience Optimization:

   • Adjust the order of questions posed by the CLI to make them more logical and intuitive.
   • Set sensible default choices for common scenarios.
   • Remove unnecessary questions when adding the CLI to an existing project.

Does this align with our discussions and your expectations? 😊