This document describes Astro's UI framework integration system, which enables React, Vue, Svelte, Solid, and Preact components to be rendered within Astro sites. Framework integrations handle server-side rendering (SSR) during build time, client-side hydration via directives, and Vite plugin coordination for development and production environments. This system allows Astro to function as a "meta-framework" that orchestrates multiple UI libraries within a single project.
Framework integrations implement the Astro integration API to hook into the build pipeline and configure framework-specific rendering and bundling behavior. Each integration provides three primary capabilities: Vite plugin registration, server-side component rendering, and client-side hydration runtime.
The following diagram bridges the high-level integration concepts to the specific code entities that implement them.
Each integration package exports a factory function that returns an AstroIntegration object. The integration registers itself during the astro:config:setup hook by calling addRenderer() with paths to server and client entry points.
Sources: packages/integrations/react/src/index.ts171-214 packages/integrations/vue/src/index.ts189-217 packages/integrations/preact/src/index.ts55-113 packages/integrations/solid/src/index.ts73-111 packages/integrations/svelte/src/index.ts18-51
All framework integrations follow a consistent pattern for coordinating between Astro's build system and the framework's own compiler/runtime:
| Package Component | Implementation Detail | Role |
|---|---|---|
| Integration Factory | default export in src/index.ts | Uses addRenderer and updateConfig hooks to setup environment and plugins. |
| Server Renderer | server.ts | Implements SSR check and renderToStaticMarkup functions for component rendering. |
| Client Entrypoint | client.ts | Client-side hydration mounting and runtime logic. |
| Environment Plugin | configEnvironmentPlugin() | Configures Vite's dependency optimization (optimizeDeps) and module deduplication. |
The AstroRenderer object defines how Astro interacts with the framework during build and runtime. Core properties include:
name: Unique identifier of the renderer (e.g., @astrojs/react).clientEntrypoint: Path to the client-side runtime code that hydrates components in the browser.serverEntrypoint: Path to the server-side code responsible for SSR.For example, the React renderer provides:
Sources: packages/integrations/react/src/index.ts27-33 packages/integrations/vue/src/index.ts19-33 packages/integrations/preact/src/index.ts10-16 packages/integrations/solid/src/index.ts58-64 packages/integrations/svelte/src/index.ts9-15
Astro serializes component props for server-side rendering (SSR) and safely rehydrates them client-side. This involves transforming props into a serialized string form, preserving special JavaScript types like Date, Map, BigInt, and RegExp.
The serialization process transforms complex JS props into a JSON-compatible structure with type annotations:
The PROP_TYPE integer map tags values with a type index so they can be reconstructed during hydration. The function convertToSerializedForm recursively traverses props, transforming recognized types into tagged tuples (e.g., [3, "2023-06-06T...Z"] for Dates). This ensures correct hydration on the client.
Sources: packages/astro/src/runtime/server/serialize.ts1-116
Astro implements partial hydration using a custom Web Component <astro-island> which hydrates UI framework components on demand, triggered by different client:* directives.
The AstroIsland class (defined in astro-island.ts) serves as the bridge between the static HTML and the framework's hydration runtime.
client:load, client:idle, client:visible, client:media.reviveObject together with propTypes encoding to rehydrate props correctly.Sources: packages/astro/src/runtime/server/astro-island.ts1-201 packages/astro/src/runtime/server/scripts.ts32-45
getReactMajorVersion and isSupportedReactVersion functions in packages/integrations/react/src/version.ts determine the version to select appropriate configuration.injectScript in the astro:config:setup hook.experimentalDisableStreaming) and enabling experimental React children (experimentalReactChildren).@vitejs/plugin-react with exclusion for .astro files to avoid parser conflicts.react and react-dom, includes react-dom/server for SSR via configEnvironmentPlugin.Sources: packages/integrations/react/src/index.ts171-214 packages/integrations/react/src/index.ts123-167 packages/integrations/react/src/index.ts31-70 packages/integrations/react/src/index.ts88-94 packages/integrations/react/src/version.ts9-13
appEntrypoint for initializing Vue apps (plugins, state).virtual:astro:vue-app to load user's app setup dynamically.getJsxRenderer() if options.jsx is true.@vitejs/plugin-vue and optionally @vitejs/plugin-vue-jsx.configEnvironmentPlugin.Sources: packages/integrations/vue/src/index.ts37-107 packages/integrations/vue/src/index.ts149-187 packages/integrations/vue/src/index.ts11-12 packages/integrations/vue/src/index.ts20-26 packages/integrations/vue/src/index.ts110-147
vitefu.crawlFrameworkPkgs to detect framework packages referencing Svelte for SSR bundling.@sveltejs/vite-plugin-svelte with preprocessing.svelte from optimization during SSR to avoid duplicate runtime instances.Sources: packages/integrations/svelte/src/index.ts20-80 packages/integrations/svelte/src/index.ts36-42 packages/integrations/svelte/src/index.ts77
compat option, adding preact/compat to optimizeDeps.@preact/signals.@preact/preset-vite configured with reactAliasesEnabled: compat.Sources: packages/integrations/preact/src/index.ts20-113 packages/integrations/preact/src/index.ts138-162 packages/integrations/preact/src/index.ts70-77
solid-devtools during development.vite-plugin-solid with ssr: true.optimizeDeps to include @astrojs/solid-js/client.js and exclude server entrypoints.Sources: packages/integrations/solid/src/index.ts10-126 packages/integrations/solid/src/index.ts33-42 packages/integrations/solid/src/index.ts49 packages/integrations/solid/src/index.ts121-123
Framework integrations coordinate Vite configuration to optimize dependencies and deduplicate modules.
Sources: packages/integrations/react/src/index.ts114-160 packages/integrations/vue/src/index.ts149-185 packages/integrations/preact/src/index.ts115-163 packages/integrations/solid/src/index.ts114-125 packages/integrations/svelte/src/index.ts53-78
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.