From bd18e14a2c05d473b9822ddaf9ebada48e2d75dd Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Wed, 21 Jul 2021 18:10:03 -0500 Subject: 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 * 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 Co-authored-by: Abdullah Mzaien * 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 Co-authored-by: Abdullah Mzaien --- docs/src/pages/reference/renderer-reference.md | 45 ++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) (limited to 'docs/src') 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. -- cgit v1.2.3