Install shadcn/ui in Astro projects with React components and island architecture. Step-by-step guide for TypeScript and Tailwind CSS setup.

How to install shadcn/ui with Astro

Astro's island architecture lets you ship minimal JavaScript by default, then add React components with shadcn/ui exactly where you need interactivity.

Complete Astro setup

Create Astro project with React

pnpm create astro@latest my-app
cd my-app
npx astro add react tailwind

Or in one command:

pnpm dlx create-astro@latest my-app --template with-tailwindcss --install --add react

Configure TypeScript paths

Add to tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Initialize shadcn/ui

npx shadcn@latest init

The CLI configures components for Astro's src directory structure.

Add components

npx shadcn@latest add button card tabs

Use them in your Astro pages:

---
// src/pages/index.astro
import Layout from '../layouts/Layout.astro';
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"
---

<Layout title="Astro + shadcn/ui">
  <main>
    <Card className="m-8 p-6" client:visible>
      <h1>Welcome to Astro</h1>
      <Button client:load>Interactive Button</Button>
    </Card>
  </main>
</Layout>

Astro-specific features

Client directives

Control when React components hydrate:

<!-- Always interactive -->
<Button client:load>Click me</Button>

<!-- Interactive when visible -->
<Card client:visible>
  Content here
</Card>

<!-- Interactive on hover/focus -->
<Dialog client:idle>
  Dialog content
</Dialog>

<!-- No hydration, static HTML only -->
<Badge>Static badge</Badge>

File structure

astro.config.mjs

components.json

Deployment

Astro sites deploy anywhere:

Platform	Setup	Best For
Vercel/Netlify	Zero config deployment	Easy setup and previews
Cloudflare Pages	Excellent performance	Global edge performance
Static hosting	GitHub Pages, S3, etc.	Free and simple hosting
SSR platforms	Node.js, Deno Deploy	Server-side rendering

Next steps

With Astro + shadcn/ui ready:

Browse official components for forms, tables, and UI elements
Add charts for data visualization
Explore community components for extended functionality
Add useful hooks to enhance your components
Use pre-built blocks to quickly build common layouts

Astro's performance-first approach combined with shadcn/ui's flexibility gives you the best of both worlds—fast static sites with rich interactivity where needed.

Install shadcn/ui Astro