Add experimentalReactChildren option to React integration (#8082)

* wip: support true react vnodes in renderer

* Add new experimentalReactChildren option to React integration

* Update the test

* Add docs

* Update packages/integrations/react/server.js

Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>

* Update with a better test

* Update .changeset/yellow-snakes-jam.md

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* Update packages/integrations/react/README.md

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* Update packages/integrations/react/README.md

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

---------

Co-authored-by: Nate Moore <nate@astro.build>
Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

1 files changed, 40 insertions, 0 deletions

diff --git a/packages/integrations/react/README.md b/packages/integrations/react/README.md
index 48c45881f..7504490e0 100644
--- a/packages/integrations/react/README.md
+++ b/packages/integrations/react/README.md
@@ -61,6 +61,46 @@ To use your first React component in Astro, head to our [UI framework documentat
 - 💧 client-side hydration options, and
 - 🤝 opportunities to mix and nest frameworks together
 
+## Options
+
+### Children parsing
+
+Children passed into a React component from an Astro component are parsed as plain strings, not React nodes.
+
+For example, the `<ReactComponent />` below will only receive a single child element:
+
+```astro
+---
+import ReactComponent from './ReactComponent';
+---
+
+<ReactComponent>
+  <div>one</div>
+  <div>two</div>
+</ReactComponent>
+```
+
+If you are using a library that *expects* more than one child element element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker.
+
+You can set the experimental flag `experimentalReactChildren` to tell Astro to always pass children to React as React vnodes. There is some runtime cost to this, but it can help with compatibility. 
+
+You can enable this option in the configuration for the React integration:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+
+export default defineConfig({
+  // ...
+  integrations: [
+    react({
+      experimentalReactChildren: true,
+    })
+    ],
+});
+```
+
 ## Troubleshooting
 
 For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!