withastro / docs

Astro documentation
https://docs.astro.build/
MIT License
1.34k stars 1.5k forks source link

Request: Clarify "out-of-the-box" JSX/TSX support #8939

Closed kjkent closed 3 months ago

kjkent commented 3 months ago

đź“‹ Explain your issue

I'm confused trying to understand the extent to which Astro, without the React (or another framework) integration, supports JSX/TSX syntax.

Support for .jsx and .tsx files is currently mentioned in the docs here and here (both on the guides/imports page)

It is noted:

While Astro understands JSX syntax out-of-the-box, you will need to include a framework integration to properly render frameworks like React, Preact and Solid.

Could the extent to which the syntax/filetype is supported be explained a little more explicitly? I can see types for JSXTransformConfig and JSXTransformFn in the Astro source, but writing even the simplest JSX, such as const testJsx = () => <p>Hello, world!</p> leads to a build error like Cannot find module 'react/jsx-dev-runtime' imported from <testJsx.jsx>

In the docs-given example:

import { MyComponent } from './MyComponent.jsx';

What JSX could be declared/implemented/returned by MyComponent that would not require a framework integration to be installed?

It's late, so I appreciate I may not be firing on all cylinders, but I do wonder if this clarification may be a beneficial amendment to the docs. I appreciate your time; thanks!

delucis commented 3 months ago

I may be mistaken, but I believe the answer is that Astro cannot render any JSX/TSX without a framework integration for one of the frameworks that use JSX (React, Preact, Solid, Qwik…)

It might be possible to build a simple “server-only” JSX renderer with no client, but it’s not built in to Astro currently

sarah11918 commented 3 months ago

Hi @kjkent ! I've been discussing with our platform team, and the nuance would be "you can use JSX for server templating, but not for client interactivity." According to them, it's a flow we do not particularly encourage though.

I think this might be a case where "technically true" doesn't translate to "particularly helpful" and the suggestion I've received from them has been to remove this reference entirely. The simpler, and more helpful advice would be to avoid any suggestion that JSX integrations are optional.

My docs recommendation would be to

Astro does not support JSX in .js files. JSX will only be handled inside of files that end with the .jsx (or .tsx) file extensions, and requires a UI framework integration (React, Preact, Solid) to render.

Are you interested in making a PR to the imports page to reflect this change in our advice?

delucis commented 3 months ago

Just to confirm a second time, JSX/TSX without a framework integration is not supported. Trying to render a JSX component throws a “No matching renderer found” error.

I created a small reproduction here: https://stackblitz.com/edit/github-tw3rmw?file=src%2Fpages%2Findex.astro

kjkent commented 3 months ago

@sarah11918 hello! Regarding the server templating, I'm curious as to how that could work if, by default, errors are raised when trying to return any HTML content within a JSX file. I ask purely out of curiosity!

Regarding the PR with the docs change; happily -- I'll get on that now and will tag this issue in the PR.

delucis commented 3 months ago

Regarding the server templating, I'm curious as to how that could work

I believe this was a mistake. In theory, Vite (which Astro builds on) offers built-in support for JSX files, so I think there was some speculation that maybe that would extend to Astro too, but it doesn’t seem to be the case. And there’s probably not much motivation to change this for a couple of reasons:

Regarding the PR with the docs change; happily -- I'll get on that now and will tag this issue in the PR.

Amazing! Thank you again for flagging this đź’ś

kjkent commented 3 months ago

@delucis Thank you for the clarification! I think I'm in the 1% (not financially, notably :smiling_face_with_tear:) as I was looking for a way to just write JSX and have it transpiled for use as an SSG -- perhaps along the same vein as React Server Components. That said, this approach is clearly against the tide, and I wonder if there are reasons behind this!

So sorry that I haven't sent the PR earlier, it's... been a week; it's now up as #8981

delucis commented 3 months ago

Thanks for the PR! And again, to stress, adding one of the framework integrations like React or Preact will still let you write JSX that is only used for server rendering with no JavaScript shipped to the browser, so your use case should still be supported if you want.