Expose JSX compilation to renderers (#588)

* feat: add support for `jsxImportSource`, new JSX transform

* Renderer: add Solid renderer (#667)

* feat: add support for `jsxImportSource`, new JSX transform

* WIP: solid renderer

* [Renderer] Solid (#656)

* feat: add support for `jsxImportSource`, new JSX transform

* WIP: solid renderer

* Solid renderer: fix SSR of children, hydration (top level)

Caveat: cannot hydrate children/descendants of hydrated parents

* Fix hydration of fragments

* fix: SyntaxError in React/Preact renderers

* fix: errors in React/Preact renderers

* feat: update react external

* chore: update examples

* chore: delete old changelog

* chore: update astro config

Co-authored-by: Nate Moore <nate@skypack.dev>

* Changing the preact to Solid (#669)

* chore: use new client:visible syntax

* fix: dev script issue

* chore: cleanup SolidJS example

* docs: update framework example docs

* chore: cleanup framework-multiple example

* fix: remove SolidJS false-positives from Preact renderer

* chore: add changeset

Co-authored-by: eyelidlessness <eyelidlessness@users.noreply.github.com>
Co-authored-by: Abdullah Mzaien <s201540830@kfupm.edu.sa>

* feat(create-astro): add Solid support

* docs: add JSX options to renderer reference

* chore: add changeset for P/React renderers

* fix: move react/server.js to external

* chore: remove brewfile

* Revert "feat: add support for `jsxImportSource`, new JSX transform"

This reverts commit 077c4bfc135c58a85d4ebfca6012e90403694d8d.

* fix: remove `react-dom/server` from `external`

* chore: remove unused dependency

* feat: improve JSX error messages

* Revert "Revert "feat: add support for `jsxImportSource`, new JSX transform""

This reverts commit f6c2896b9ec6430611fc0abae7d586c42aca87e5.

* docs: update jsxImportSource

* feat: improve error message

* feat: improve error logging for JSX renderers

* tests: add jsx-runtime tests

* chore: update snowpack

Co-authored-by: eyelidlessness <eyelidlessness@users.noreply.github.com>
Co-authored-by: Abdullah Mzaien <s201540830@kfupm.edu.sa>

1 files changed, 45 insertions, 0 deletions

diff --git a/docs/src/pages/reference/renderer-reference.md b/docs/src/pages/reference/renderer-reference.md
index 542905efe..9dfd073a4 100644
--- a/docs/src/pages/reference/renderer-reference.md
+++ b/docs/src/pages/reference/renderer-reference.md
@@ -62,9 +62,54 @@ export default {
   external: ['dep'] // optional, dependencies that should not be built by snowpack
   polyfills: ['./shadow-dom-polyfill.js'] // optional, module scripts that should be loaded before client hydration.
   hydrationPolyfills: ['./hydrate-framework.js'] // optional, polyfills that need to run before hydration ever occurs.
+  jsxImportSource: 'preact', // optional, the name of the library from which JSX is imported
+  jsxTransformOptions: async () => { // optional, a function to transform JSX files
+    const { default: { default: jsx }} = await import('@babel/plugin-transform-react-jsx');
+    return {
+      plugins: [
+        jsx({}, { runtime: 'automatic', importSource: 'preact' })
+      ]
+    }
+  }
 };
 ```
 
+### JSX Support
+
+Astro is unique in that it allows you to mix multiple types of JSX/TSX files in a single project. It does this by reading the `jsxImportSource` and `jsxTransformOptions` from renderers and transforming a file with [Babel](https://babeljs.io/).
+
+#### `jsxImportSource`
+This is the name of your library (for example `preact` or `react` or `solid-js`) which, if encountered in a file, will signal to Astro that this renderer should be used.
+
+Users may also manually define `/** @jsxImportSource preact */` in to ensure that the file is processed by this renderer (if, for example, the file has no imports).
+
+#### `jsxTransformOptions`
+This is an `async` function that returns information about how to transform matching JSX files with [Babel](https://babeljs.io/). It supports [`plugins`](https://babeljs.io/docs/en/plugins) or [`presets`](https://babeljs.io/docs/en/presets) to be passed directly to Babel.
+
+> Keep in mind that this transform doesn't need to handle TSX separately from JSX, Astro handles that for you!
+
+The arguments passed to `jsxTransformOptions` follow Snowpack's `load()` plugin hook. These allow you to pass separate Babel configurations for various conditions, like if your files should be compiled differently in SSR mode.
+
+```ts
+export interface JSXTransformOptions {
+  (context: {
+    /** True if builder is in dev mode (`astro dev`) */
+    isDev: boolean;
+    /** True if HMR is enabled (add any HMR code to the output here). */
+    isHmrEnabled: boolean;
+    /** True if builder is in SSR mode */
+    isSSR: boolean;
+    /** True if file being transformed is inside of a package. */
+    isPackage: boolean;
+  }) => {
+    plugins?: any[];
+    presets?: any[];
+  }
+}
+```
+
+####
+
 ### Server Entrypoint (`server.js`)
 
 The server entrypoint of a renderer is responsible for checking if a component should use this renderer, and if so, how that component should be rendered to a string of static HTML.