🦋 Changeset detected

Latest commit: e3d0dd2

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Merging this PR will not alter performance

✅ 18 untouched benchmarks

_{Comparing ocavue-forks:ocavue/multi-jsx-3 (e3d0dd2) with main (e6e146c)¹}

Ok cool, so this is basically all handled inside of the integration renderers. This prevents us from having to run the code if we already know its outside of the directory scope, is that right?

Ok cool, so this is basically all handled inside of the integration renderers. This prevents us from having to run the code if we already know its outside of the directory scope, is that right?

That's correct.

@ocavue can you add this to the React integration as well?

Just noting that since there are potential breaking changes here, this would need some kind of breaking change guidance: https://contribute.docs.astro.build/docs-for-code-changes/changesets/#breaking-changes

It would probably be a good idea to include any of the framework integrations with breaking changes to this list, too: https://v6.docs.astro.build/en/guides/upgrade-to/v6/#official-astro-integrations (Right now, it's just the adapters, but if this affects e.g. something previously rendered as one JSX framework could now be rendered as another, we should have a major changeset for that integration with the breaking change notification and how to revert to previous behaviour, and then we can just link to the changelong from the upgrade guide like we do for adapters currently)

Hey @ocavue, great work on this! The speculative rendering + console.error patching approach has always been fragile, so moving toward explicit routing is a solid direction.

I maintain Astro's Qwik integration and wanted to flag a few things since the PR description mentions us as a renderer that should adopt this approach:

What should stay if this PR merges as-is: The Component.name === 'QwikComponent' checks should stay for now. Qwik components don't use client:load/client:visible/etc., Qwik uses resumability instead of hydration. Since metadata.componentUrl is only populated for hydrated components (the known limitation you noted), removing those checks would cause React/Preact/Solid to speculatively render Qwik components again.

What doesn't fit Qwik: The include/exclude pattern is a worse DX fit for Qwik. Qwik's check() uses structural detection via isQwikComponent(). it inspects the component itself rather than relying on file paths. This means Qwik components work without users having to organize files into framework-specific directories or add include patterns to their config. Asking Astro Qwik users to adopt path-based filtering would be a regression from "it just works."

Suggestion: If componentUrl were populated for all components (not just hydrated ones), the path-based filtering would work reliably for the frameworks that need it (React/Preact/Solid), while Qwik could continue using structural detection without any changes.

That would close the known limitation and make the QwikComponent name checks in each integration truly redundant. Users configure preact({ include: ['**/preact/**'] }), a Qwik component at src/components/qwik/Counter.tsx would be rejected by Preact's path filter before it ever reaches the speculative rendering code. Today, without componentUrl on SSR-only components, the hardcoded name check is the only thing preventing that.

Happy to help test this against @qwikdev/astro once it lands, just want to make sure the existing integration isn't broken and that we're not expected to adopt a pattern that doesn't fit Astro Qwik's model.

What should stay if this PR merges as-is: The Component.name === 'QwikComponent' checks should stay for now.

Is this a convention that all Qwik components have?

Asking Astro Qwik users to adopt path-based filtering would be a regression from "it just works."

I don't think anyone is asking integrations to adopt this behavior. It makes sense for React, Preact, and Solid since all of those use regular function exports that are not easily distinguishable from each other.

What should stay if this PR merges as-is: The Component.name === 'QwikComponent' checks should stay for now.

Is this a convention that all Qwik components have?

Yes, it's the standard convention. component$() is Qwik's component API and all components created with it have that name.

Asking Astro Qwik users to adopt path-based filtering would be a regression from "it just works."

I don't think anyone is asking integrations to adopt this behavior. It makes sense for React, Preact, and Solid since all of those use regular function exports that are not easily distinguishable from each other.

That's good to hear. the PR description mentioned @qwikdev/astro as a renderer that should use this approach, so I wanted to make sure that wasn't the expectation. If Qwik can keep using structural detection as-is, we're all good.

@sarah11918 I don't think there's a breaking change here as far as I can tell. This logic only applies when using include/exclude filters, the user is opting into only those files being considered already, this is just fixing a gap.

What should stay if this PR merges as-is: The Component.name === 'QwikComponent' checks should stay for now.

I agree. Currently, because of the "Known limitation" I mentioned in the PR description, the check is not sufficient. I still keep all existing (and fragile) checking code as it is.

What I hope is that once I update the Astro compiler side and make componentUrl populated for all components, as you mentioned, I can remove these checks in one day. That would be a different PR, though.

The include/exclude pattern is a worse DX fit for Qwik. Qwik's check() uses structural detection via isQwikComponent()

IMHO, the implementation behind isQwikComponent() is not sound. It uses component.name and component.toString(), which are not strict.

For example, the following React component will pass the isQwikComponent() check incorrectly:

import React from 'react'

function QwikComponent() {
    return React.createElement(
      "div", 
      {}, 
      "This is a React component " + 
         "with an unusual name " + 
         "and some magic text in the function body " + 
         "_jsx_q."
    )
}

It seems that the only reliable ways in theory to check if a variable is a component are:

1. Path-based filtering. It's users' responsibility to specify the correct path.
2. maybeComponent instanceof MyFrameworkClass
   (and similar MyFrameworkComponent.isPrototypeOf(maybeComponent))
3. maybeComponent.__internal_label__ === Symbol.for("my_framework_symbol")

Although I admit in particular, the current isQwikComponent() implementation can work almost in all real use cases.

@ocavue can you add this to the React integration as well?

Done

Just noting that since there are potential breaking changes here, this would need some kind of breaking change guidance: https://contribute.docs.astro.build/docs-for-code-changes/changesets/#breaking-changes

I don't think there's a breaking change here as far as I can tell.

I agree with @matthewp that there isn't a real breaking change. It only breaks a user's project if

1. The user is using multiple JSX frameworks (e.g., React + SolidJS), and
2. The user has already added include/exclude filters as shown in the docs "Combining multiple JSX frameworks", and
3. The include/exclude filters are incorrect (e.g., missing some components in the include filter).

In this case, the user's project will fail to build after updating to the latest versions.

I would say it's more like a bug fix than a major change. I also updated the error message in this commit to better indicate the reason for these users.

IMHO, the implementation behind isQwikComponent() is not sound. It uses component.name and component.toString(), which are not strict.

Haha yeah, this is a case where it's technically unsound but practically never happens. They could probably be improved further with linter tooling but that's still easing symptoms. We do mention the path based way to do it, and mention it in the README, but it is more of a precaution.

Symbols actually seem the most technically feasible of those options. That would mean framework authors need to create a unique symbol for each framework.

"It's only a breaking change if..."

In the past, we have considered the user whose project worked (even if only inadvertently) who might notice a change, which is why I brought this up. But if you're choosing not to here, that's your call! It's only my responsibility to point this out.

I'm not seeing the scenario where a user's project would break after this change. Can you give a concrete example @ocavue ? We are using the same include/exclude filter, so an "incorrect" one would still be incorrect when it is called against this code.

The real change here is that we still always do the check against frameworks, which is imperfect for JSX frameworks (React, Solid, and Preact at least) and causes double renders and other weirdness. This seems like a bug fix to me.

@matthewp

I'm not seeing the scenario where a user's project would break after this change. Can you give a concrete example

There is an example in astro's repo itself:

In packages/astro/test/fixtures/static-build-frameworks/, you can find three JSX components:

src/
  components/
    Nested.jsx    <-- A React component 
    RCounter.jsx  <-- A React component 
    PCounter.jsx  <-- A Preact component

Here is its astro.config.mjs:

import preact from '@astrojs/preact';
import react from '@astrojs/react';
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
	integrations: [react({
		include: ["**/react/*", "**/RCounter.jsx"]
	}), preact({
		include: ["**/preact/*", "**/PCounter.jsx"]
	})],
});

Notice that src/components/Nested.jsx doesn't actually match any of the include filter.

Before this PR, this example can work. react({...}) is the first integration in astro.config.mjs. Astro uses react to render all three JSX components during SSR. Not quite right technically, but users won't see any error anyway.

After this PR, RCounter.jsx is rendered by react (same as before 😐), PCounter.jsx is rendered by preact (better 🥰), but Nested.jsx will not render at all (😱). The following error will show:

$ cd packages/astro/test/fixtures/static-build-frameworks/
$ ./node_modules/.bin/astro build

[ERROR] Error: Unable to render NestedCounter!

This component likely uses @astrojs/react, @astrojs/preact, @astrojs/solid-js or @astrojs/vue (jsx),
but Astro encountered an error during server-side rendering.

Please ensure that NestedCounter:
1. Does not unconditionally access browser-specific globals like `window` or `document`.
   If this is unavoidable, use the `client:only` hydration directive.
2. Does not conditionally return `null` or `undefined` when rendered on the server.
3. If using multiple JSX frameworks at the same time (e.g. React + Preact), pass the correct `include`/`exclude` options to integrations.

If you're still stuck, please open an issue on GitHub or join us at https://astro.build/chat.

(Notice that the (3.) in the error message is new added by this pull request.)

To fix this test fixture, I move the Nested.jsx file under react/ in
commit f27186c so that it won't throw error.

@ocavue Thanks for the explanation. I consider this a bug then, the user has explicitly opted that component from being treated as React, and that we did so by mistake is a bug.