Framework Components

Purpose and Scope

Astro’s framework component story lets a project keep Astro as the page, routing, and content shell while using familiar UI frameworks for parts of the interface. The official guide describes this as building Astro islands with the UI frameworks of your choice, including React, Preact, Svelte, Vue, SolidJS, and AlpineJS. In practice, this means a framework component can be imported into an Astro page, layout, or component, rendered as static HTML by default, and hydrated only when a client directive asks for browser-side interactivity.

This page focuses on the repository signals available for framework examples. The devcontainer definitions show that the repo treats each framework example as a runnable Astro project with the same development contract: open the example workspace, install dependencies, build Astro packages from the monorepo, and start the example server on port 4321. That shared shape is important because it makes React, Preact, Solid, Alpine, Lit, and mixed-framework examples comparable when debugging integration behavior or demonstrating islands. Sources: .devcontainer/framework-alpine/devcontainer.json, .devcontainer/framework-lit/devcontainer.json, .devcontainer/framework-multiple/devcontainer.json, .devcontainer/framework-preact/devcontainer.json, .devcontainer/framework-react/devcontainer.json, .devcontainer/framework-solid/devcontainer.json

Core Primitives

A framework component is a component authored in a UI framework rather than in Astro’s .astro component syntax. The official docs show the authoring model: import the component from a relative path in the Astro component script, then use it in the Astro template alongside HTML, Astro components, and JSX-like expressions. Without a hydration directive, Astro renders that component on the server as static HTML. This default keeps JavaScript out of the browser for components that are only needed for templating or display.

An island is the interactive boundary around a component that needs browser JavaScript. Astro’s island model lets the page remain mostly static while a specific React, Preact, Svelte, Vue, Solid, Alpine, or other integration component hydrates on the client. That distinction is the key decision point for developers: use the framework component syntax freely for composition, but reserve hydration for widgets that actually need state, event handlers, or lifecycle behavior in the browser.

An integration is the package-level bridge that teaches Astro how to render and hydrate a framework. The official framework guide lists official integrations for AlpineJS, Preact, React, SolidJS, Svelte, and Vue, and the Preact guide shows the expected install path through astro add preact or manual package installation. The requested repository paths do not contain integration source code, but they do show separate example environments for several of those framework families and one kitchen-sink example for multiple frameworks in the same Astro app.

Relevant Source Files

• .devcontainer/framework-alpine/devcontainer.json - Defines the Alpine example workspace at /workspaces/astro/examples/framework-alpine, forwards Astro’s development port, builds the monorepo after install, starts the app with pnpm start --host, and opens src/pages/index.astro for inspection.
• .devcontainer/framework-lit/devcontainer.json - Defines the Lit example workspace at /workspaces/astro/examples/framework-lit with the same install, build, preview, and editor customization contract as the other framework examples.
• .devcontainer/framework-multiple/devcontainer.json - Defines the kitchen-sink multiple-framework example workspace at /workspaces/astro/examples/framework-multiple, which is the primary source-backed signal for using more than one UI framework in a single Astro example.
• .devcontainer/framework-preact/devcontainer.json - Defines the Preact example workspace at /workspaces/astro/examples/framework-preact, aligning the official Preact integration guide with a runnable repository example.
• .devcontainer/framework-react/devcontainer.json - Defines the React example workspace at /workspaces/astro/examples/framework-react, using the same port, command, and editor setup as the other framework examples.
• .devcontainer/framework-solid/devcontainer.json - Defines the Solid example workspace at /workspaces/astro/examples/framework-solid, giving Solid the same example lifecycle as React and Preact.

System-to-Code Mapping

The devcontainer files map framework documentation concepts to concrete repository entry points. Each file names a framework-oriented example, points workspaceFolder at an example under /workspaces/astro/examples/, uses ../examples.Dockerfile as the shared container build recipe, forwards port 4321, and labels that port as Application with preview auto-opening. That consistency means a maintainer can switch from React to Preact, Solid, Alpine, Lit, or the multiple-framework example without learning a different local workflow. Sources: .devcontainer/framework-alpine/devcontainer.json, .devcontainer/framework-lit/devcontainer.json, .devcontainer/framework-multiple/devcontainer.json, .devcontainer/framework-preact/devcontainer.json, .devcontainer/framework-react/devcontainer.json, .devcontainer/framework-solid/devcontainer.json

The editor setup is also deliberately uniform. Each framework devcontainer opens src/pages/index.astro, which reflects the official guide’s teaching path: framework components are consumed from Astro pages, layouts, and components, not from a separate application shell. The VS Code extensions include astro-build.astro-vscode and esbenp.prettier-vscode, so the example environment is optimized for editing Astro files and formatting the surrounding project. That combination keeps the reader’s attention on island usage rather than on container or editor setup details.

Framework example	Workspace folder	Primary use
Alpine	/workspaces/astro/examples/framework-alpine	Alpine-style interactivity in an Astro page
Lit	/workspaces/astro/examples/framework-lit	Web component-oriented framework example
Multiple frameworks	/workspaces/astro/examples/framework-multiple	Mixed UI framework islands in one Astro project
Preact	/workspaces/astro/examples/framework-preact	Preact components and hydration in Astro
React	/workspaces/astro/examples/framework-react	React components and hydration in Astro
Solid	/workspaces/astro/examples/framework-solid	Solid components and hydration in Astro

Execution Flow

A framework example container follows the same startup sequence across all supplied paths. First, the container is built from the shared examples Dockerfile. Then postCreateCommand runs pnpm install and builds the repository from /workspaces/astro with pnpm run build. The devcontainer waits for that post-create command before treating the environment as ready, which protects the example from starting against unbuilt workspace packages. After attach, the configured Server task runs pnpm start --host in the example workspace and exposes the application through port 4321. Sources: .devcontainer/framework-alpine/devcontainer.json, .devcontainer/framework-lit/devcontainer.json, .devcontainer/framework-multiple/devcontainer.json, .devcontainer/framework-preact/devcontainer.json, .devcontainer/framework-react/devcontainer.json, .devcontainer/framework-solid/devcontainer.json

For a developer trying a framework island, the practical flow is therefore straightforward. Open the matching devcontainer or Codespaces environment, wait for dependency installation and the monorepo build, inspect src/pages/index.astro, and then view the application preview on port 4321. In that Astro page, the framework component should appear as part of the page template. If the component is purely presentational, it can remain server-rendered. If it needs browser behavior, add the appropriate Astro client directive according to the public framework component guide.

The multiple-framework example matters because Astro’s model is not limited to a single UI framework per site. The official docs say one or several front-end framework integrations can be installed and configured in a project, and the repository mirrors that concept with the framework-multiple devcontainer. When evaluating mixed islands, use that example to verify that each island boundary remains explicit. The intent is not to merge framework runtimes into a single global app; it is to let independent components hydrate only where the page needs them.

Practical Guidance

When choosing between React, Preact, Solid, Svelte, Vue, Alpine, and similar integrations, start from the component’s ownership and runtime needs. Existing product UI may be easiest to reuse in React or Vue. A small interactive enhancement may fit Alpine. Preact can be attractive when the team wants a React-like API with a smaller runtime, as described in the official Preact integration guide. Solid and Svelte often appeal when the component is authored specifically for their compilation or reactivity models. Astro’s role is to host these choices without forcing the whole page into one framework.

The most important performance habit is to separate component rendering from component hydration. The official framework guide states that framework components render on the server as static HTML by default. That means importing a React or Preact component into an Astro page does not automatically ship its JavaScript to the browser. Treat hydration as an opt-in behavior for islands that need client-side state, effects, event listeners, or live updates. This keeps Astro’s lightweight-output promise intact while still allowing rich interaction at the edges of a page.

Use the devcontainer examples as reproducible sandboxes for framework behavior. If a bug appears only in one framework, open the matching example workspace and compare it with another framework container that shares the same startup commands and port behavior. If a bug appears in the multiple-framework example, check whether it is caused by integration configuration, conflicting assumptions between framework runtimes, or an island that is hydrated more broadly than necessary. The shared container contract reduces environmental noise so maintainers can focus on component and integration behavior.

Next Steps

To go deeper, read the integrations overview after this page to understand how framework packages are added to astro.config.*, then read the directives and syntax reference to choose the right hydration directive for each island. For task-based learning, follow the islands tutorial path: add a UI framework such as Preact, create an interactive component, and compare it with a non-island solution. For repository exploration, start from the relevant example devcontainer, open src/pages/index.astro, and trace the framework component imports used by that example. Sources: .devcontainer/framework-multiple/devcontainer.json, .devcontainer/framework-preact/devcontainer.json, .devcontainer/framework-react/devcontainer.json