Como Configurar um Site Astro Moderno em 2025

Introdução

Neste guia, vamos explorar como criar um site moderno e de alta performance usando Astro, React, Tailwind CSS e shadcn/ui.

Esta combinação oferece o melhor dos dois mundos:

• 🚀 Performance excepcional com SSG (Static Site Generation)
• ⚛️ Componentes React quando necessário
• 🎨 Design system consistente com Tailwind
• 🧩 Componentes acessíveis do shadcn/ui

Por Que Esta Stack?

Astro

Astro é um framework moderno focado em conteúdo. Diferente de SPAs tradicionais, Astro:

• Gera HTML estático por padrão
• Carrega zero JavaScript por padrão
• Suporta “islands architecture” para interatividade seletiva
• Funciona com qualquer framework (React, Vue, Svelte, etc.)

React Islands

Com Astro Islands, você pode usar React apenas onde necessário:

<ExampleDialog client:visible />

Isso significa que o JavaScript só é carregado quando o componente está visível no viewport.

Tailwind + shadcn/ui

Tailwind CSS fornece utilitários para estilização rápida, enquanto shadcn/ui oferece componentes prontos e acessíveis:

• ✅ Design tokens via CSS custom properties
• ✅ Dark mode nativo
• ✅ Componentes totalmente customizáveis
• ✅ Acessibilidade built-in

Configuração Inicial

1. Instalar Dependências

npm install -D @astrojs/react @astrojs/tailwind tailwindcss
npm install react react-dom

2. Configurar astro.config.mjs

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

export default defineConfig({
  integrations: [
    react(),
    tailwind({ applyBaseStyles: false }),
  ],
});

3. Setup do Tailwind

Crie tailwind.config.cjs:

module.exports = {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,ts,tsx}'],
  theme: {
    extend: {
      colors: {
        background: 'var(--color-bg)',
        foreground: 'var(--color-text)',
      },
    },
  },
};

Design System com Tokens CSS

Crie um arquivo src/design-system/tokens.css:

:root {
  --color-bg: 255 255 255;
  --color-text: 15 23 42;
  --color-primary: 37 99 235;

  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
}

[data-theme="dark"] {
  --color-bg: 15 23 42;
  --color-text: 248 250 252;
  --color-primary: 59 130 246;
}

Componentes shadcn/ui

Instale os componentes necessários:

npm install -D @radix-ui/react-dialog class-variance-authority clsx tailwind-merge

Crie o utilitário cn():

import { clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs) {
  return twMerge(clsx(inputs));
}

Agora você pode criar componentes como Button.tsx, Card.tsx, Dialog.tsx, etc.

Content Collections

Configure suas coleções em src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const articles = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    route: z.string(),
    publishDate: z.coerce.date(),
    tags: z.array(z.string()),
  }),
});

export const collections = { articles };

Layouts Modulares

Crie layouts reutilizáveis:

1. BaseLayout.astro - Layout base com SEO
2. PostLayout.astro - Para posts de blog
3. ReviewLayout.astro - Para reviews de produtos

Cada layout pode ter sua própria estrutura, mas todos compartilham o mesmo design system.

Performance & SEO

Headers de Segurança

Crie public/_headers:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Cache-Control: public, max-age=3600

Sitemap Automático

Instale @astrojs/sitemap:

import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://seusite.com',
  integrations: [sitemap()],
});

Schema Markup

Use JSON-LD para SEO:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Seu título aqui"
}
</script>

Deploy no Cloudflare Pages

1. Conecte seu repositório
2. Configure build:
   • Build command: npm run build
   • Output directory: dist
3. Deploy!

Cloudflare Pages automaticamente aplica os headers e redirects definidos em _headers e _redirects.

Conclusão

Com esta stack, você tem:

• ✅ Site ultra-rápido (SSG)
• ✅ Componentes interativos quando necessário (React Islands)
• ✅ Design system profissional (Tailwind + shadcn/ui)
• ✅ SEO otimizado
• ✅ Deploy automático

A combinação de Astro + React + Tailwind + shadcn/ui é perfeita para sites de conteúdo que precisam de performance excepcional sem sacrificar a experiência do desenvolvedor.

Próximos Passos

• Adicione analytics (Vercel Analytics, Plausible, etc.)
• Configure i18n para múltiplos idiomas
• Implemente search com Pagefind
• Adicione RSS feed para os posts

---

Gostou deste tutorial? Compartilhe com outros desenvolvedores que possam se beneficiar!