Skip to content

Getting started with React components in Astro

React Gut Check

Here are the very first, super-basic things to check that might be causing your perfectly-awesome React components to throw Astro errors:

1. Specify the React renderer in astro.config.mjs

Astro can render a variety of components: React, Svelte, Vue, Preact, Solid ā€¦ but, it first needs to import the appropriate renderer(s) to do so. If you didnā€™t specify renderers when creating your project, your astro.config.mjs may have started with an empty renderers array, or it may have been commented out. It should include all renderers for components you intend to use. Make sure the following is in your config file at the root of your project (example shown with renderers for React and Svelte, but you only need the one(s) you intend to use):

astro.config.mjs
export default {
renderers: ['@astrojs/renderer-react','@astrojs/renderer-svelte'],
}

2. Import your React component with its file extension

You have made sure to include your React renderer, but your super-happy-awesome React component still causes an error? Perhaps something like ā€œFailed to fetch dynamically imported moduleā€?

This can be a particular Dā€™oh! moment when first getting used to writing React in Astro, especially if youā€™re copy-pasting or uploading React files into your Astro project. Your React component may itself be importing child components, and you arenā€™t used to writing a file extension for those imports. But, Astro does require you to type out the full import path. So, you may have to inspect all your imports carefully to make sure all .js/.jsx file extensions are included.

src/pages/my-astro-page.astro
---
import BaseLayout from '../layouts/BaseLayout.astro';
import MyReactComponent from '../components/MyReactComponent.jsx'
---

3. Hydrate your React component for interactivity

Why do we fall for this one over and over again? Your technically-perfect React component has been imported into your .astro file, extension and all, and it looks like itā€™s working. But itā€¦ doesnā€™t work?

Check to see that you have specified a hydration method with a client:* directive!

If you render <MyAmazingReactComponentThatShouldTotallyWork /> in an Astro page, the way you would in a React component, youā€™ll only get the static HTML representation of your component, with no interactivity. To include your componentā€™s functionality, be sure to specify one of the available options such as:

<MyAmazingReactComponentThatShouldTotallyWork client:load /> (to load instantly) or <MyAmazingReactComponentThatShouldTotallyWork client:visible /> (to load only when the component becomes visible on the page. This is handy for something lower on the page that doesnā€™t need to load until / unless the user scrolls down to it)

These are the top three items on my checklist when a React component isnā€™t working, especially if Iā€™ve been writing my React code separately in a different environment, outside of my main Astro project with the intention of adding the files later.

I mean, sure, there could be a flaw in my React code, but I can sometimes save myself a whole lot of pain and suffering if I just check these things first!

Toggle Comments

Ā© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0