AstroHow-ToBeginner · 4 min read

How to Use Preact with Astro: Simple Integration Guide

To use preact with astro, install the @astrojs/preact integration and add it to your astro.config.mjs. Then, import and use Preact components inside your Astro files with client:load or other client directives.

📐

Syntax

First, install the Preact integration package. Then, add it to your Astro config file. Import Preact components in your Astro pages or components and use client directives to hydrate them on the client.

npm install @astrojs/preact preact installs the needed packages.
astro.config.mjs includes preact() in the integrations array.
Import Preact components with import Component from './Component.jsx'.
Use client:load or client:idle on the component tag to enable client-side interactivity.

astro

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [preact()],
});

---

---

import MyPreactComponent from '../components/MyPreactComponent.jsx';

<MyPreactComponent client:load />

💻

Example

This example shows a simple Astro page using a Preact button component that increments a counter when clicked. The client:load directive hydrates the component on the client so it becomes interactive.

astro

// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [preact()],
});

// src/components/Counter.jsx
import { useState } from 'preact/hooks';

export default function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

// src/pages/index.astro
---
import Counter from '../components/Counter.jsx';
---
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Astro with Preact</title>
  </head>
  <body>
    <h1>Welcome to Astro + Preact</h1>
    <Counter client:load />
  </body>
</html>

Output

<h1>Welcome to Astro + Preact</h1> <button>Count: 0</button> (clicking increments count)

⚠️

Common Pitfalls

Forgetting to install @astrojs/preact and preact packages causes import errors.
Not adding preact() to astro.config.mjs means Preact components won't work.
Using Preact components without a client directive like client:load results in static output with no interactivity.
Mixing React and Preact imports can cause conflicts; use only Preact imports.

astro

/* Wrong: Missing integration and client directive */
import Counter from '../components/Counter.jsx';

<Counter />

/* Right: Add integration and client directive */
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [preact()],
});

// In Astro file
<Counter client:load />

📊

Quick Reference

Here is a quick checklist to use Preact with Astro:

Install @astrojs/preact and preact.
Add preact() to astro.config.mjs integrations.
Import Preact components with import Component from './Component.jsx'.
Use client directives like client:load to hydrate components.
Do not mix React and Preact imports.

✅

Key Takeaways

Install and add @astrojs/preact integration to your Astro config to enable Preact support.

Use client directives like client:load on Preact components to make them interactive in Astro.

Always import Preact components from 'preact' and avoid mixing React imports.

Without client directives, Preact components render static HTML with no interactivity.

Check your package installs and config if Preact components fail to load or hydrate.