Astro

Framework

Como instalar e configurar WI.UI em um projeto Astro com React islands e Tailwind v4.

Pre-requisitos

Astro 4+
Integracao @astrojs/react
Tailwind CSS v4 (via @astrojs/tailwind)
TypeScript (recomendado)

Se ainda nao tem um projeto:

pnpm create astro@latest meu-projeto

Adicione React e Tailwind:

pnpm astro add react tailwind

Via CLI (recomendado)

O CLI detecta Astro automaticamente.

pnpm dlx @wi-ui/cli init

Instalacao manual

1. Instalar dependencias

pnpm add clsx tailwind-merge

2. Criar utilitario cn()

src/lib/cn.ts

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

3. Configurar path alias

tsconfig.json

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

4. Criar pasta de componentes

mkdir -p src/components/ui

Configuracao

wi-ui.json

{
  "framework": "astro",
  "componentsDir": "src/components/ui",
  "libDir": "src/lib",
  "importAlias": "@/"
}

CSS com design tokens:

src/styles/global.css

@import "tailwindcss";

@theme {
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0 0);
  --color-muted: oklch(0.97 0 0);
  --color-muted-foreground: oklch(0.556 0 0);
  --color-border: oklch(0.922 0 0);
  --color-primary: oklch(0.8234 0.1927 206.47);
}

.dark {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-border: oklch(0.269 0 0);
}

Adicionar componente

pnpm dlx @wi-ui/cli add button card

Uso

Componentes WI.UI sao React — use a diretiva client:load para hidratar no Astro:

src/pages/index.astro

---
import Layout from "../layouts/Layout.astro";
import { Button } from "@/components/ui/button";
---

<Layout>
  <div class="flex min-h-screen items-center justify-center">
    <Button client:load>Comecar agora</Button>
  </div>
</Layout>

Importante

Componentes interativos (com estado, eventos) precisam de client:load ou client:visible
Componentes puramente visuais (Badge, Separator) funcionam sem diretiva client
Use client:visible para componentes abaixo da dobra (melhor performance)

Estrutura do projeto

meu-projeto/
├── src/
│   ├── components/
│   │   └── ui/              # Componentes WI.UI (React)
│   │       ├── button.tsx
│   │       └── ...
│   ├── layouts/
│   │   └── Layout.astro
│   ├── lib/
│   │   └── cn.ts            # Utilitario de classes
│   ├── pages/
│   │   └── index.astro
│   └── styles/
│       └── global.css       # Tailwind + tokens
├── astro.config.mjs
├── wi-ui.json               # Config WI.UI
└── package.json