Astro and React Islands Setup

Bootstrapping an Astro project uses npx create astro@latest, which runs an interactive wizard to choose a template, TypeScript settings, and package manager. Astro supports multiple starters including a blank template, a blog template, and documentation templates.

Astro integrations add framework support to a project. Running npx astro add react automatically installs @astrojs/react, react, and react-dom, and updates astro.config.mjs to include the React integration. The entire setup takes one command.

An .astro file is Astro's component format. It consists of a frontmatter section (JavaScript between --- fences) and a template section. By default, an Astro file outputs static HTML — no JavaScript is sent to the browser unless you explicitly add a client directive.

Importing a React component into an Astro file uses standard ES module syntax: import Counter from './Counter.jsx'. Without a client directive, Astro server-renders the React component to static HTML and sends that HTML to the browser — zero JavaScript shipped for the component.

Adding client:visible to the component tag in the Astro template turns it into an island: <Counter client:visible />. Astro now ships the Counter's JavaScript, hydrates it when it scrolls into view, and makes it interactive. Without the directive, it is static HTML.

React components used as Astro islands are written in standard React — they use hooks, state, effects, and any React library. There is no Astro-specific API inside the React component itself. The island boundary is defined in the Astro template, not inside the component code.

Each island instance is an independent React tree. Two Counter islands on the same page do not share state. If you need shared state, you have three options: merge them into one island, use URL search params for serializable state, or use a shared state library like nanostores.

The @nanostores/react library provides lightweight atoms that any island can subscribe to. One island writes to a nano store atom, another island reads it. Because nano stores are framework-agnostic, this pattern also works across React and Vue islands on the same page.

Astro Content Collections provide a type-safe way to manage Markdown and MDX files. Define a collection schema with Zod, place Markdown files in src/content/, and Astro generates fully typed query functions. This is the standard pattern for blog posts, documentation, and product pages.

Running astro build generates a dist/ folder of static HTML files. For each page, Astro outputs an HTML file with the server-rendered content and only the JavaScript bundles needed for the islands on that page. Pages with no islands output zero JavaScript.

The static output can be deployed to any CDN (Netlify, Vercel, Cloudflare Pages) without a server. For server-side rendering needs (dynamic routes, API endpoints), Astro supports SSR adapters for Node.js, Vercel Edge, Cloudflare Workers, and Deno. Islands work identically in both modes.

What is the minimum change needed to an imported React component in an Astro template to make it interactive on the client?

Set up Astro with React using npx astro add react. Astro files are static by default; adding a client: directive to a React component tag turns it into a hydrated island. React components are standard React with no Astro-specific APIs. State is isolated per island; nanostores enable cross-island communication. The build outputs static HTML with only the island JavaScript needed.