Remove need for making qwik libraries noExternal

[wmertens]

What is it about?

Improve DX and dev speed

What's the motivation for this proposal?

There are a few reasons why Qwik libraries need to be transformed during the build:

1. convert e.g. component$ to the equivalent QRL expressions
2. convert jsx() to the optimized _jsxSorted and _jsxSplit expressions
3. change isServer etc to their boolean values, so the code tree-shakes before processing imports inside blocks
4. to provide the Qwik client manifest and the Qwik Router map virtual imports
5. to make sure they are using the same Qwik Core and Router instances as the rest of the application, so that module scoped data is shared.

That's why these libraries need to be noExternal and optimizeDeps.exclude.

This means that devs need to add Qwik libraries to these configuration values, and that they get built for every dev build, they can't be preprocessed.

Proposed Solution / Feature

If we eliminate all these reasons, then Qwik libraries can be built ahead of time, and no special configuration is needed.

1. QRL conversion: The optimizer was already built to re-process inlinedQrls, so that a library could generate the QRL expressions and then client builds would reuse the generated hash and move the inlined code to segments. All that is needed is to enable QRL conversion in library builds again.
2. JSX conversion: This can also be done as part of library bundling. We disabled it in v1 to make library code compatible with v2.
3. Build constants: These are crucial for browser vs ssr builds. Therefore, two builds have to be generated for libraries. We can use the NPM exports map to differentiate between browser and import builds.
4. Virtual imports: These are basically global variables. Replace these imports with helper functions that get the shared instance. So getClientManifest() and getRouterMap()
5. Shared Module Scoped Data: On the client, there is no problem, because all code had to be bundled, and on the server, these can be made into global variables. The globalThis.__qwik variable can be used to make sure that multiple Qwik instances are actually the exact same version. On the client, multiple Qwik versions are allowed to co-exist, but on the server, only a single Qwik version and a single server build can co-exist.

All these require that the internal API remains the same: _jsxSorted, _jsxSplit, and the various QRL calls.

Conclusion

The needed changes are:

• make 2 builds for libraries, one browser and one regular
• replace virtual imports with API calls
• make module scoped shared data into globals on the server
• keep the used API calls the same across Qwik releases

Provided we can guarantee internal API stability and do some small changes, we can eliminate special treatment for Qwik libraries. Build optimizations can be applied, speeding up dev mode and builds.

Links / References

No response

[thejackshelton]

This sounds reasonable to me, but this is a lot of steps.

Also would this be a breaking change for Qwik libraries?

[wmertens]

Yes they would need to make a build for v2

[thejackshelton]

Wout, Michal, and I talked this. We agreed that it should be done before 2.0 rc, and the tradeoff being that library authors will be doing the transpilation. In return there is less surface area for potential issues with libraries, and library maintainers will be responsible for upgrading in the case of majors and keeping updated with the current qwik version.

[thejackshelton]

Coming from the @qwik.dev/astro integration work with Cloudflare Workers (workerd) + Astro 6 / Vite 7. This proposal would solve nearly every issue we're hitting.

Vite 7's Environment API splits module graphs per-environment (client, SSR/workerd, prerender/node). noExternal and optimizeDeps.exclude now need configEnvironment per-environment, not just ssr.noExternal. This causes:

• Q30 in workerd: dep optimization reloads re-execute modules while globalThis.__qwik persists. import.meta.hot.dispose doesn't run in workerd.
• Library QRL 404s: the plugin's load hook searches devServer.moduleGraph (legacy shared graph), but library .qwik.mjs files only exist in the workerd environment's graph. Browser requests for their QRL chunks get 404.
• Build failures: our standalone Qwik client build (for manifest generation) lacks Astro's plugins, so virtual:image-service, astro:assets, native modules, etc. all fail to resolve.

All of this traces back to Qwik libraries needing special treatment at dev/build time. Ideally libraries become normal packages. No noExternal, no optimizeDeps.exclude, no cross-environment module graph issues, no standalone client build. The Cloudflare integration would just work.

[maiieul]

Maybe we should revert to doing the full node_modules scan as it used to be if it's a lot of work ?

[wmertens]

wouldn't help in some cases, we had duplication issues with the scan too