`.jsx` vs `.astro` comparison should include the conceptual differences between the two

[Jutanium]

Currently, we have a .jsx vs .astro comparsion that covers the syntactic differences between the two languages.

This is helpful, but there's another difference that I want to point out.

JSX is used in app frameworks like React and Solid. There, JSX is used to include dynamically updated values. For example, in React you might see:

<div>
  Your name is {name}
  <input type="text" onChange={updateName}/>
</div>

Here, {name} means: whenever the value of name changes, make sure it shows up here. In Astro, .astro looks like JSX, and shares many of its features, but is not used for this key purpose.

I would like to make that clear in this section by explaining the purpose of the .astro syntax, which is to include dynamic values (not reactive values).

Dynamic: we don't know what the value is, let's include it via a variable! It's not going to change, though: we run this once (on the server).

Reactive: we don't know what the value is and it's going to change.

[crutchcorn]

I'm also noticing that in this comparison, it says that "attributes" are "camelCase" for JSX

https://docs.astro.build/en/comparing-astro-vs-other-tools/#astro-vs-jsx

But this is actually an implementation detail of React's JSX transpiler. EG: SolidJS does not have this behavior.

The same could be said about the class vs className usage. In fact, even React's aria-label and other aria props use dash-case

Because of this, some of the discussion in the Astro Discord lead to an idea I had to:

• Splitting the JSX usage into being tabbed for each framework that supports JSX (React/Preact/SolidJS for now)
• Inside of the tabs, use a specific table for the nuances such as class vs className alongside more naunce as-needed

Does this sound like a good plan?

[Jutanium]

I question how useful the table is altogether if the goal is to help people learn .astro coming from JSX. Is that the goal in this section? Let's define one and then we can decide whether to potentially ditch the table entirely

[crutchcorn]

For me, as a more senior engineer familiar with the nuances of JSX, it absolutely was.

Glance-ability is a big part of how I personally read docs when I'm doing early evaluation, so this was important for me to have a reference point to get started

[Jutanium]

In that case, is it worth detailing the nuances of JSX syntax across frameworks if the focus in on .astro?

It may be that JSX does deserve that focus because, well, we support those JSX frameworks, so this section might serve a dual purpose!

[crutchcorn]

Right, to your point it's a supported strategy to mix-n-match JSX syntaxes. As such, not only does this help learn .astro syntax, but I think it'd be a good reference guide for those using Astro + [JSX here]

[Jutanium]

A relevant but separate point:

One annoyance I had that we can improve with the table is the long duplicated expressions. I found myself instinctually reading both instances of

{items.map(item => <li>{item}</li>)}

checking to see if there was a difference, when the point of showing both was that there wasn't a difference.

[Jutanium]

@sarah11918 for next steps would you agree with:

1. redefining the purpose of this section to both explain .astro and .jsx, using their similarities and differences to further that goal
2. elaborating on the conceptual difference between .astro and .jsx as described in the OP
3. redesigning the JSX table to explain different implementations of JSX that you might encounter as described by @crutchcorn

I'd also suggest: 4. Moving this section to its own page. It already serves a different purpose to the other "Astro vs X" comparisons, and these suggested changes (along with our brainstormed changes to "Astro vs X") would change that further.

[sarah11918]

Initial reactions, just my own thoughts here:

1. It's been a long-standing principle that docs isn't for "teaching you things that aren't Astro." So, to think of this as a way to teach/explain flavours of JSX (end sentence) isn't really within the current scope, and would require re-thinking here. The original purpose of this chart was certainly to help "teach Astro" through something that (a) Astro looks a lot like, and (b) readers may have prior experience with. Something Something "Astro Academy" might very well have an expanded mandate. Furthermore, we can't end up making ourselves too responsible for keeping up with any changes should anything change upstream, so I'm not convinced we should be claiming and doing the "explain JSX itself" here.

2. I agree it's a good idea to expand on conceptual differences. I think maybe this brings it close to what Fred is currently working on with the new Core Concepts section? See draft #893 So, it would be worth exploring whether there is any overlap here, because maybe Fred wants to tackle this conceptual part in his section pages there.

3. Following on point 1, I think a good intermediate step would be refining the table so that it's HELPFUL. We could have some cells simply indicate "same" or "no change" instead of, as you mentioned, typing out something long that the reader is responsible to check for any difference. (Especially when, at least on my screen, the columns are unequal lengths. So, even when the two cell contents ARE the same, they LOOK different because of line breaking.) For the specific example re: camelCaseOrNot - I don't think it helps the person learning Astro to know which case every other implementation uses. The goal is, they need to know the case that ASTRO uses in a particular situation, and WHEN that might be different from what they expect or are used to. I don't think it's on us to meticiulously note, OK, this framework uses this case, but this one uses that... I think instead it's, "Astro uses this case. Be aware, SOME or even MOST implementations of JSX might use this instead." I think THAT is a helpful chart for these docs.

4. Would consider! I think this depends in part on 2. I know we moved this chart out of components because that page was getting really long, and it seemed like a "comparison-y" place to put it. I also know we don't "like" Astro vs X anymore, so that page will need some think-work.

[sarah11918]

Why hellooooo, long-standing Issue in the Docs repo!

Given that so much time has passed, the chart in question no longer exists and the content has been moved to another page entirely... what do we think about what's going on in #1359 in order to close this one?

I propose that whatever remaining issues this does NOT solve, we create new! separate! fun! issues. e.g. I think we've already discussed things like Should we have specific "coming from.... (React, Svelte, Vue...)" guidance? If we make an issue about THAT itself, then I think a lot of what was mentioned above gets included in that new discussion, while allowing us to at least explicitly make the dynamic/reactive distinction clearly, concisely, and immediately in an appropriate spot in existing docs.

[Jutanium]

Agreed! See you there and on future issues!