Qwik Community Plugins Support

[shairez]

What is it about?

A way to expand Qwik without increasing core size

What's the motivation for this proposal?

Problems you are trying to solve:

• Currently the Qwik monorepo contains a lot of adapters, plugins and integrations. We would like to make sure anything that is in core stays stable over time and it's hard to do it with an ever growing number of possible integrations.

Goals you are trying to achieve:

• Keep qwik core stable and trustworthy
• Give a way to community contributors to integrate their package into the Qwik CLI

Any other context or information you want to share:

---

Proposed Solution / Feature

A Qwik plugin system.

Scanability

Every package in node_modules that starts with a specific convention like qwik- should be scanned for its qwik-plugin-manifest.json file which describes specific instructions of which files to copy, modify, etc.

Extracting some of the existing plugins from core

Separating possible integrations as "maintained by core team" (anything under the QwikDev org) or "maintained by community" (anything under the QwikCommunity org) will allow the core team to take responsibility of fewer things but make sure they are always stable / maintained.

File management

We need to brainstorm how different types of plugins will look like (usually there is a difference between the types).

Plus, we would need to modify the Qwik CLI to be aware of external integrations so we could install or add them with ease (running their script).
We would need to provide an infrastructure for copying new files and modifying existing files that are read from the plugin's manifest.

Discoverability

We need a way to list core plugins and community plugins in a searchable area under the Qwik docs

---

Links / References

Here are some examples for existing plugin systems from several projects:

• https://docs.cypress.io/guides/component-testing/third-party-definitions

• https://nx.dev/extending-nx/recipes/create-preset

Example for a "discover plugins" page -

• https://nx.dev/plugin-registry

[ianlet]

Adding this one for inspiration:

• https://github.com/npm/cli/blob/latest/docs/lib/content/commands/npm-init.md

Which is the usual npm|pnpm|yarn create [...] command.

And this one for an other example of "plugin registry":

• https://github.com/asdf-vm/asdf-plugins

[ianlet]

Here's a few things I started thinking about to design the plugin system...

Plugin types

• starters: to create a new qwik application/library
• server adapters: to setup a server adapter
• integrations: to add new features to your app through an integration
• templates: to create new files (e.g. components) into your app

But in the end, the type doesn't change much except for categorizing them (to list them in the docs).
Because plugins might all update project files (package.json, vite.config.ts, etc.), copy files, apply some user args to templates, or all of these at the same time.

Plugin development

Or how plugin developers will declare their plugins.

Option 1 - Free for all

• full flexibility for the plugin dev, but no tooling at all
• can mess the end user projects real bad

Option 2 - Programmatic approach

• similar to yeoman, the Qwik team provides tools to copy/merge files in a programmatic way (e.g. installDep("vite", "2.1.2"), copyFile("..."), etc.)
• still flexible for the plugin dev, with some tooling
• can still mess the end user project

Option 3 - Declarative approach (manifest)

• no code approach, full tooling, less flexibility
• cannot really mess the end user project as Qwik provides all the tools
• more work for the Qwik team

Plugin discoverability

In reality, we can easily use any plugins if they are in npm and that they follow a given pattern (e.g. qwik-plugin-<name>). The point here is really just about listing which plugins are available (on the docs website and through the CLI, ideally).

Option 1 - Full npm registry

• no maintenance at all for the Qwik team
• can be tricky to list available plugins (ref. list npm packages)

Option 2 - Minimal qwik registry

• github repository where people list their plugins
• little effort to set up
• requires some team members to watch that repo, review PRs, and merge PRs

Option 3 - Full qwik registry

• web app where people submit by themselves their packages to be listed
• big setup effort + infra
• no reviewing afterwards

---

In terms of high level design, I honestly don't think there is much more to think about. Then it will depend on the chosen approaches (programmatic VS declarative, raw npm registry VS github repo VS full webapp).

Personally I vote for the declarative approach (manifest) and the github repository. Depending on what others choose, I can start describing how the underlying solution will look like.

[wmertens]

In terms of tooling I think the current support in the qwik cli is sufficient.

For the registry, the safest way is having a repo that people submit PRs to. However the safety is still very minimal, because we're not going to vet every release of every plugin.

A registry also speeds up lookups, allows grouping by type, and does some sanity filtering too. It also doesn't place limitations on the name, as long as the plugin configuration is in the package.

[ianlet]

In terms of tooling I think the current support in the qwik cli is sufficient.

Yes it's a good start. My only concern is that it's a bit confusing for first time plugin devs and that I'm not sure the manifest in its current form will scale well (e.g. add interactivity with the end user to control what the plugin does).

Also as it is now, if a plugin dev wants to offer at the same time a starter, an integration, and some templates, they will have to create different packages for each one.

[shairez]

Thanks @ianlet !

I like the manifest approach, and having a repo or a registry file on the monorepo people can "PR" into.

BTW, @dmitry-stepanenko I think you also had some thoughts about this right?