docs: document Oxc React Compiler and Babel migration

[hanford]

Description (required)

Documents the experimental Oxc React Compiler option introduced in @astrojs/react v7.0.0, including its API block, default behavior, installation, React 17/18 runtime dependency, and an annotation-mode configuration example.

Adds a separate v7 upgrade section for the removed babel integration option, linked from a tip at the top of the page. A single configuration diff shows how to move custom Babel transforms into vite.plugins. Links to the Babel plugin documentation cover advanced configuration, and the upgrade section explains avoiding duplicate React Compiler transformations.

The docs retain the current implementation's compiler option name. Implementation: withastro/astro#17951.

Validation: Prettier and git diff --check passed. pnpm check reported 0 errors, 0 warnings, and one existing hint. Verified the API block, package-manager installation commands, upgrade section, migration diff, and section navigation in the local preview.

References

• Implementation: feat(react)!: use Oxc for JSX and add React Compiler support astro#17951
• Related issue: Support the Oxc React Compiler in @astrojs/react astro#17952

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/integrations-guide/react.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: 3e76662
• Preview: https://docs-react-oxc-compiler.previews.docs.astro.build
• Workflow run: View logs

[ArmandPhilippot]

Thank you, @hanford! I left some suggestions because:

• we need a <Since /> to callout this is new and not available for everyone
• it might be helpful to start with what is the default behavior to explain when/why users might want to enable this feature. I'm not sure everyone knows what the React compiler does and that this is something obvious to them.
• the "Migrating..." section is misplaced: this is not an integration option
• as Matthew said, I think we're giving too much details about Babel. Our job is only to document how Astro works.
• I felt that some sentences were misplaced or not connected to the next sentence in the paragraph. So, I reorganized or rewrote a few passages.

Feel free to check if what I wrote is still accurate! This is your feature, you know it better than me.

Also, and maybe @matthewp as an opinion on this:
I was wondering why this is experimental... Experimental features are usually prefixed with experimental (e.g. experimentalReactChildren, experimentalDisableStreaming) and that's not the case here. I can see now that it's actually experimental upstream.

I don't know/recall how we deal with experimental features when they are upstream... But, I wonder if this lack of consistency might confuse users (as I was) and if this option shouldn't be named experimentalCompiler rather than compiler.

I guess experimentalCompiler is annoying because we would need another major when this becomes stable upstream? But I prefer to highlight the inconsistency here.

[hanford]

Thanks @ArmandPhilippot! I’ve incorporated your suggestions and checked the technical details. The docs now include the block, explain the default behavior and compiler benefits, and move migration into a separate v7 upgrade section with shorter Babel guidance.

On naming, I lean toward keeping compiler, since the experimental status comes from upstream Oxc. We call that out explicitly in the docs, and keeping the name avoids another API migration when it stabilizes. I see your consistency concern, though... @matthewp, do you have a preference?