From 15471e6b4fd12381f9a2d1533ca580436d25b53a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 21 Aug 2023 09:47:28 -0300 Subject: [PATCH] [docs] JSX framework integration READMEs (#8151) --- packages/integrations/preact/README.md | 36 ++++++++++++++++++++++++++ packages/integrations/react/README.md | 33 +++++++++++++++++++++++ packages/integrations/solid/README.md | 35 +++++++++++++++++++++++++ 3 files changed, 104 insertions(+) diff --git a/packages/integrations/preact/README.md b/packages/integrations/preact/README.md index f0ae3b364742..61e074f19a72 100644 --- a/packages/integrations/preact/README.md +++ b/packages/integrations/preact/README.md @@ -115,6 +115,42 @@ Check out the [`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) and > **Note** > Currently, the `compat` option only works for React libraries that export code as ESM. If an error happens during build-time, try adding the library to `vite.ssr.noExternal: ['the-react-library']` in your `astro.config.mjs` file. +## Options + +### Combining multiple JSX frameworks + +When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed. + +Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single JSX framework! + integrations: [ + preact({ + include: ['**/preact/*'] + }), + react({ + include: ['**/react/*'] + }), + solid({ + include: ['**/solid/*'], + }), + ] +}); +``` + + ## Examples - The [Astro Preact example](https://github.com/withastro/astro/tree/latest/examples/framework-preact) shows how to use an interactive Preact component in an Astro project. diff --git a/packages/integrations/react/README.md b/packages/integrations/react/README.md index 8009972b3047..aca6eba7d9b0 100644 --- a/packages/integrations/react/README.md +++ b/packages/integrations/react/README.md @@ -63,6 +63,39 @@ To use your first React component in Astro, head to our [UI framework documentat ## Options +### Combining multiple JSX frameworks + +When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed. + +Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single JSX framework! + integrations: [ + preact({ + include: ['**/preact/*'] + }), + react({ + include: ['**/react/*'] + }), + solid({ + include: ['**/solid/*'], + }), + ] +}); +``` + ### Children parsing Children passed into a React component from an Astro component are parsed as plain strings, not React nodes. diff --git a/packages/integrations/solid/README.md b/packages/integrations/solid/README.md index 5c3dbeeb8aa8..7a2db0723f47 100644 --- a/packages/integrations/solid/README.md +++ b/packages/integrations/solid/README.md @@ -61,6 +61,41 @@ To use your first SolidJS component in Astro, head to our [UI framework document - 💧 client-side hydration options, and - 🤝 opportunities to mix and nest frameworks together +## Options + +### Combining multiple JSX frameworks + +When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed. + +Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single JSX framework! + integrations: [ + preact({ + include: ['**/preact/*'] + }), + react({ + include: ['**/react/*'] + }), + solid({ + include: ['**/solid/*'], + }), + ] +}); +``` + ## Troubleshooting For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!