Tutorial rápido: 5 pasos desde npm install hasta una página Astro terminada
Tutorials 10 min read

Proyecto Astro en 5 Minutos

Arnold Wender
Arnold Wender
#Astro #Tutorial #npm #Component Library #Storybook

Tienes un proyecto Astro y no quieres empezar desde cero. Aquí está el camino más rápido desde una página vacía hasta un sitio web funcional con navegación, SEO, accesibilidad y sistema de diseño.

150
Componentes
17
Categorías
0
Dependencias
8
Templates de inicio

Requisito previo

Un proyecto Astro existente (v4 o v5). Si aún no tienes uno:

npm create astro@latest mi-proyecto
cd mi-proyecto

Los 5 pasos de un vistazo

De una página vacía a un sitio web terminado

  1. Instalar el paquete

    Un comando npm — sin dependencias de runtime, solo archivos .astro y .ts.

  2. Explorar en Storybook

    Navega por 549 stories con controles interactivos para encontrar los componentes adecuados.

  3. Configurar el BaseLayout

    Combina SEO, Header, Footer, Breadcrumbs y Accessibility Toolbar en un solo layout.

  4. Construir páginas con secciones

    Componer Hero, Features, FAQ, Testimonials y secciones CTA.

  5. Personalizar el diseño con tokens

    Sobrescribir CSS custom properties o usar el DesignSystemProvider.

Paso 1: Instalar

npm install @wendermedia/astro-components

El paquete tiene cero dependencias de runtime. Solo trae componentes Astro — archivos .astro y .ts que se compilan directamente en tu proceso de build.

Paso 2: Explorar en Storybook

Antes de importar cualquier cosa, abre el Storybook en vivo y mira lo que hay disponible:

wm-astro-components.netlify.app

La página Docs de cada componente muestra:

  • Props con tipos y valores por defecto
  • Preview en vivo con controles interactivos
  • Variantes (Light/Dark, diferentes tamaños, estados)
  • CSS custom properties que usa el componente
  • Check de accesibilidad vía la pestaña A11y

Paso 3: Configurar el BaseLayout

Una página Astro típica necesita cuatro cosas: meta tags SEO, estructura básica, navegación y herramientas de accesibilidad. Todo va en un layout central.

---
// src/layouts/BaseLayout.astro
import { SEO } from '@wendermedia/astro-components/seo';
import { Header, Footer } from '@wendermedia/astro-components/layout';
import { SkipLinks, AccessibilityToolbar } from '@wendermedia/astro-components/accessibility';
import { Breadcrumbs } from '@wendermedia/astro-components/navigation';

interface Props {
  title: string;
  description: string;
}

const { title, description } = Astro.props;
---

<!doctype html>
<html lang="es">
  <head>
    <SEO title={title} description={description} />
  </head>
  <body>
    <SkipLinks />
    <Header />
    <Breadcrumbs items={[{ label: 'Inicio', href: '/' }, { label: title }]} />
    <main id="main-content">
      <slot />
    </main>
    <Footer />
    <AccessibilityToolbar position="right" />
  </body>
</html>
Lo que obtienes con 6 imports:

- Tags <title> y <meta description>
- Meta tags Open Graph y Twitter Card
- Navegación skip-to-content (accesibilidad)
- Header responsive con navegación
- Breadcrumbs con JSON-LD BreadcrumbList
- Región semántica <main>
- Footer responsive
- Toolbar de accesibilidad (tamaño de fuente, contraste, foco)

Seis imports y tienes: meta tags, skip navigation, header, footer, breadcrumbs con JSON-LD y un toolbar de accesibilidad con tamaño de fuente, contraste y opciones de foco.

Paso 4: Construir páginas

Con el layout listo, agrega secciones de página de la categoría sections:

---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro';
import { Hero, Features, FAQ, CTA } from '@wendermedia/astro-components/sections';
import { Testimonials } from '@wendermedia/astro-components/sections';
---

<BaseLayout title="Inicio" description="Descripción">
  <Hero
    title="Título"
    subtitle="Subtítulo"
    ctaText="Empezar ahora"
    ctaHref="/contacto"
  />

  <Features features={[
    { title: 'Rápido', description: 'Astro envía cero JS por defecto.' },
    { title: 'Accesible', description: 'Cumple WCAG 2.2 AA.' },
    { title: 'SEO optimizado', description: 'Datos estructurados automáticamente.' },
  ]} />

  <Testimonials testimonials={[
    { quote: 'Por fin una librería sin overhead.', author: 'Max M.', role: 'Frontend Dev' },
  ]} />

  <FAQ items={[
    { question: '¿Necesito React?', answer: 'No. Todo es Astro puro.' },
    { question: '¿Funciona con Tailwind?', answer: 'Sí. CSS custom properties se combinan con Tailwind.' },
  ]} />

  <CTA title="¿Listo?" description="Empieza ahora." buttonText="Instalar vía npm" buttonHref="https://www.npmjs.com/package/@wendermedia/astro-components" />
</BaseLayout>

Paso 5: Personalizar el diseño

Los componentes vienen con tokens neutrales por defecto. Para branding personalizado hay dos opciones:

---
// Opción A: DesignSystemProvider
import { DesignSystemProvider } from '@wendermedia/astro-components/design-system';
---

<DesignSystemProvider
  primaryColor="#059669"
  secondaryColor="#0284c7"
  fontFamily="'DM Sans', sans-serif"
  borderRadius="0.75rem"
/>
/* Opción B: CSS custom properties directamente en global.css */
:root {
  --color-primary-500: #059669;
  --color-secondary-500: #0284c7;
  --font-family-body: 'DM Sans', sans-serif;
  --radius-md: 0.75rem;
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --space-section-md: 4rem;
}

Ambos enfoques son equivalentes. El provider es más cómodo, las custom properties dan más control.

Paths de importación de las 17 categorías

Categoría Path de importación Cantidad
Accessibility @wendermedia/astro-components/accessibility 12
Content @wendermedia/astro-components/content 4
Design System @wendermedia/astro-components/design-system 1
E-Commerce @wendermedia/astro-components/ecommerce 5
Forms @wendermedia/astro-components/forms 6
Gallery @wendermedia/astro-components/gallery 3
Images @wendermedia/astro-components/images 4
Layout @wendermedia/astro-components/layout 3
Layouts @wendermedia/astro-components/layouts 15
Maps @wendermedia/astro-components/maps 2
Media @wendermedia/astro-components/media 3
Navigation @wendermedia/astro-components/navigation 4
Products @wendermedia/astro-components/products 2
SEO @wendermedia/astro-components/seo 8
Sections @wendermedia/astro-components/sections 68
Social @wendermedia/astro-components/social 3
UI @wendermedia/astro-components/ui 19

Herramienta CLI para proyectos nuevos

Si quieres iniciar un proyecto completamente nuevo, usa la herramienta CLI:

npx create-wm-component

Ocho templates disponibles: Blog, E-Commerce, Landing Page, Portfolio, Corporate, Docs, SaaS y Affiliate. Cada template configura los componentes, layouts y design tokens correctos.

Preguntas comunes de configuración

FAQ de configuración

Siguiente paso

Abre el Storybook, elige un componente e intégralo. Cada página Docs muestra el path de importación, los props y un preview en vivo.