Day10 - Astro Series: UI framework integration

@ Astro

A beautiful gradient background with a heading: "Integrating UI Frameworks"

Introduction

Previously showed how to add client JavaScript in the .astro format to give components interactivity. One of Astro’s most appealing features is the ability to integrate major UI frameworks into components, enjoying the conveniences and benefits brought by different technologies and their ecosystems. This chapter will cover everything from installing the integration to building a React component.

Using UI Frameworks in Astro

Installation

Astro’s built-in astro add command can fully automate installing officially supported integrations🔗, including major frameworks like React, Vue, Svelte, and more.

Let’s start by installing React: npx astro add react. Any changes that are automatically made during the process will be shown in the terminal — just press y to proceed and the installation will complete quickly.

# Astro will automatically install
Astro will run the following command:
If you skip this step, you can run it again later.
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ npm install @astrojs/react @types/react-dom@^18.0.6 @types/react@^18.0.21 react-dom@^18.0.0 react@^18.0.0  │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯


Astro will make the following changes to your project config:


 ╭ astro.config.mjs ─────────────────────────────╮
 │ import { defineConfig } from 'astro/config';  │
 │                                               │
 │ import react from "@astrojs/react";           │
 │                                               │
 │ // https://astro.build/config                 │
 │ export default defineConfig({                 │
 │   integrations: [react()]                     │
 │ });                                           │
 ╰───────────────────────────────────────────────╯


Astro will make the following changes to D:\USER\Desktop\nebulous-nova\tsconfig.json


 ╭ D:\USER\Desktop\nebulous-nova\tsconfig.json ╮
 │ {                                           │
 │   "extends": "astro/tsconfigs/strict",      │
 │   "compilerOptions": {                      │
 │     "jsx": "react-jsx",                     │
 │     "jsxImportSource": "react"              │
 │   }                                         │
 │ }                                           │
 ╰─────────────────────────────────────────────╯

Creating a jsx file

You can now create jsx files anywhere under src and start writing React components. Then import them into Astro components where needed:

---
import Counter from '../components/Counter.jsx
---
<!-- Will render static content on the server only -->
<Counter />

By default all framework components render on the server and have no client-side interactivity. We need to explicitly mark when a component should be rendered on the client using the “Client Directives🔗” so that the component can be hydrated or fully client-rendered to become interactive. Here are some common directives:

<!-- Mark when the component should be rendered -->
<Component client:* />
  • client:load: High priority — use for components that need to load immediately; will hydrate as quickly as possible.
  • client:idle: Medium priority — begins loading and hydrating after the page has finished loading.
  • client:visible: Low priority — begins loading and hydrating when the component becomes visible in the viewport.
  • client:media: Low priority — begins loading and hydrating only when the page matches a specific media condition.
  • client:only: Skip server rendering and render the component entirely on the client.
---
// Example: mixing components from multiple UI frameworks in the same Astro component
import MyReactComponent from '../components/MyReactComponent.jsx';
import MySvelteComponent from '../components/MySvelteComponent.svelte';
import MyVueComponent from '../components/MyVueComponent.vue';
---
<div>
  <MySvelteComponent />
  <MyReactComponent />
  <MyVueComponent />
</div>

Integrating multiple UI frameworks in the same Astro component is possible, but be careful: when integrating multiple JSX-using frameworks (React, Preact, Solid), you must configure where each framework’s JSX is located so Astro knows how to render them:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import solid from '@astrojs/solid-js';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';


export default defineConfig({
  // Integrations to support various framework components
  // If you only use a single JSX-based framework, you don't need to set `include`!
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
    svelte(),
    vue(),
  ],
});

It’s usually recommended to create a folder named after the framework and put all related files there for organization.

Conclusion

For primarily static sites, Astro’s own templating language is often more than sufficient. But if you want to add client-side interactivity, or simply prefer to write in another UI language you’re familiar with, you can very easily integrate those frameworks into an Astro project!

Further reading

@astrojs/react🔗 - Astro DOCS