DEV Community: Joaquín Gutiérrez

Diseño e Implementación de Cards en Desarrollo Web Moderno

Joaquín Gutiérrez — Fri, 06 Dec 2024 13:19:14 +0000

Las cards (tarjetas) son uno de los componentes más versátiles en el diseño web moderno. Se utilizan para presentar información de manera concisa y visualmente atractiva, desde productos en tiendas online hasta artículos en blogs. En esta guía, exploraremos diferentes implementaciones y mejores prácticas.

Anatomía de una Card

Una card típica consta de varios elementos:

<div class="card">
  <!-- Imagen -->
  <img src="imagen.jpg" alt="Descripción" class="card-image">

  <!-- Contenido -->
  <div class="card-content">
    <h2 class="card-title">Título de la Card</h2>
    <p class="card-description">Descripción o contenido principal</p>

    <!-- Pie de Card -->
    <div class="card-footer">
      <button class="card-button">Acción Principal</button>
      <span class="card-meta">Info adicional</span>
    </div>
  </div>
</div>

Implementaciones

1. Card Básica con CSS

.card {
  width: 300px;
  border-radius: 8px;
  overflow: hidden;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s ease;
}

.card:hover {
  transform: translateY(-4px);
}

.card-image {
  width: 100%;
  height: 200px;
  object-fit: cover;
}

.card-content {
  padding: 16px;
}

.card-title {
  margin: 0 0 8px;
  font-size: 1.25rem;
}

.card-description {
  color: #666;
  line-height: 1.5;
}

.card-footer {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding-top: 16px;
  margin-top: 16px;
  border-top: 1px solid #eee;
}

2. Card con Tailwind CSS

<div class="max-w-sm rounded overflow-hidden shadow-lg hover:-translate-y-1 transition-transform">
  <img class="w-full h-48 object-cover" src="imagen.jpg" alt="Descripción">
  <div class="px-6 py-4">
    <h2 class="font-bold text-xl mb-2">Título de la Card</h2>
    <p class="text-gray-700 text-base">
      Descripción o contenido principal
    </p>
  </div>
  <div class="px-6 py-4 border-t border-gray-200">
    <button class="bg-blue-500 text-white px-4 py-2 rounded">
      Acción
    </button>
    <span class="text-gray-500 text-sm">Meta info</span>
  </div>
</div>

3. Componente React con TypeScript

interface CardProps {
  image: string;
  title: string;
  description: string;
  action?: () => void;
  meta?: string;
}

const Card: React.FC<CardProps> = ({
  image,
  title,
  description,
  action,
  meta
}) => {
  return (
    <div className="card">
      <img
        src={image}
        alt={title}
        className="card-image"
        loading="lazy"
      />
      <div className="card-content">
        <h2 className="card-title">{title}</h2>
        <p className="card-description">{description}</p>

        <div className="card-footer">
          {action && (
            <button
              onClick={action}
              className="card-button"
            >
              Ver más
            </button>
          )}
          {meta && <span className="card-meta">{meta}</span>}
        </div>
      </div>
    </div>
  );
};

4. Componente Vue 3

<template>
  <div class="card">
    <img :src="image" :alt="title" class="card-image">
    <div class="card-content">
      <h2 class="card-title">{{ title }}</h2>
      <p class="card-description">{{ description }}</p>

      <div class="card-footer">
        <button
          v-if="action"
          @click="action"
          class="card-button"
        >
          Ver más
        </button>
        <span v-if="meta" class="card-meta">{{ meta }}</span>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
defineProps<{
  image: string;
  title: string;
  description: string;
  action?: () => void;
  meta?: string;
}>();
</script>

Patrones de Diseño

1. Card Grid Responsiva

.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 24px;
  padding: 24px;
}

2. Cards con Aspect Ratio

.card-image-container {
  position: relative;
  padding-top: 56.25%; /* 16:9 Aspect Ratio */
}

.card-image {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

3. Skeleton Loading

.card-skeleton {
  animation: pulse 1.5s infinite;
}

@keyframes pulse {
  0% { opacity: 0.6; }
  50% { opacity: 1; }
  100% { opacity: 0.6; }
}

Accesibilidad

<div 
  class="card" 
  role="article"
  tabindex="0"
>
  <img 
    src="imagen.jpg" 
    alt="Descripción detallada"
    aria-describedby="card-desc"
  >
  <div class="card-content">
    <h2 id="card-title">Título</h2>
    <p id="card-desc">Descripción</p>
    <button 
      class="card-button"
      aria-labelledby="card-title"
    >
      Ver más
    </button>
  </div>
</div>

Mejores Prácticas

Optimización de Imágenes

import Image from 'next/image';

<Image
  src={imageUrl}
  alt={title}
  width={300}
  height={200}
  placeholder="blur"
  blurDataURL={thumbnailUrl}
/>

Manejo de Errores de Imagen

const handleImageError = (e: React.SyntheticEvent<HTMLImageElement>) => {
  e.currentTarget.src = '/placeholder.jpg';
};

<img
  src={imageUrl}
  onError={handleImageError}
  alt={title}
/>

Truncado de Texto

.card-title {
  overflow: hidden;
  text-overflow: ellipsis;
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
}

Animaciones

/* Hover Effects */
.card {
  transition: all 0.3s ease;
}

.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15);
}

/* Click Effect */
.card:active {
  transform: translateY(-2px);
  box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);
}

Consideraciones de Rendimiento

Lazy Loading

<img 
  loading="lazy"
  src="imagen.jpg"
  alt="Descripción"
>

Intersection Observer

useEffect(() => {
  const observer = new IntersectionObserver(
    (entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          // Cargar contenido
        }
      });
    },
    { threshold: 0.1 }
  );

  observer.observe(cardRef.current);
  return () => observer.disconnect();
}, []);

Conclusión

Las cards son componentes fundamentales en el diseño web moderno. Una buena implementación debe considerar:

Diseño responsivo
Accesibilidad
Rendimiento
Experiencia de usuario
Mantenibilidad del código

Recursos Adicionales

Next.js: La Guía Definitiva del Framework React más Popular

Joaquín Gutiérrez — Fri, 06 Dec 2024 13:06:29 +0000

Next.js se ha convertido en el framework de React más popular para construir aplicaciones web modernas. Con su enfoque en la renderización del lado del servidor (SSR), generación estática, y una excelente experiencia de desarrollo, Next.js ofrece todo lo necesario para construir aplicaciones web escalables y de alto rendimiento.

¿Por qué Next.js?

Características Principales

Renderizado Híbrido
- Server-Side Rendering (SSR)
- Static Site Generation (SSG)
- Client-Side Rendering (CSR)
- Incremental Static Regeneration (ISR)
Optimizaciones Automáticas
- Optimización de imágenes
- Font optimization
- Script optimization
- Zero config
Developer Experience
- Fast Refresh
- TypeScript Support
- File-system routing
- API Routes

Primeros Pasos

Creación de un Proyecto

npx create-next-app@latest mi-proyecto
cd mi-proyecto
npm run dev

Estructura del Proyecto

├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
├── public/
│   └── images/
├── components/
│   └── ui/
├── lib/
├── next.config.js
└── package.json

Routing en Next.js 14

Páginas Básicas

// app/page.tsx
export default function Home() {
  return (
    <main>
      <h1>Bienvenidos a Next.js</h1>
    </main>
  );
}

Rutas Dinámicas

// app/blog/[slug]/page.tsx
export default function BlogPost({ params }: { params: { slug: string } }) {
  return (
    <article>
      <h1>Post: {params.slug}</h1>
    </article>
  );
}

Layout Compartido

// app/layout.tsx
import { Inter } from 'next/font/google';
const inter = Inter({ subsets: ['latin'] });

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <nav>
          {/* Navegación común */}
        </nav>
        {children}
      </body>
    </html>
  );
}

Data Fetching

Server Components

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.ejemplo.com/posts', {
    next: { revalidate: 3600 } // Revalidar cada hora
  });
  return res.json();
}

export default async function Posts() {
  const posts = await getPosts();

  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  );
}

Static Generation

// app/posts/[id]/page.tsx
export async function generateStaticParams() {
  const posts = await getPosts();

  return posts.map((post) => ({
    id: post.id.toString(),
  }));
}

export default async function Post({ params }: { params: { id: string } }) {
  const post = await getPost(params.id);

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  );
}

API Routes

// app/api/posts/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    const posts = await getPosts();
    return NextResponse.json(posts);
  } catch (error) {
    return NextResponse.json(
      { error: 'Error al obtener posts' },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    const data = await request.json();
    const newPost = await createPost(data);
    return NextResponse.json(newPost, { status: 201 });
  } catch (error) {
    return NextResponse.json(
      { error: 'Error al crear post' },
      { status: 500 }
    );
  }
}

Optimizaciones

Imágenes

import Image from 'next/image';

export default function Profile() {
  return (
    <Image
      src="/perfil.jpg"
      alt="Foto de perfil"
      width={500}
      height={300}
      priority
    />
  );
}

Fonts

import { Roboto } from 'next/font/google';

const roboto = Roboto({
  weight: ['400', '700'],
  subsets: ['latin'],
  display: 'swap',
});

export default function Layout({ children }) {
  return (
    <div className={roboto.className}>
      {children}
    </div>
  );
}

Manejo de Estado

Client Components

'use client';

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Contador: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        Incrementar
      </button>
    </div>
  );
}

Estilización

CSS Modules

// components/Button.tsx
import styles from './Button.module.css';

export default function Button({ children }) {
  return (
    <button className={styles.button}>
      {children}
    </button>
  );
}

Tailwind CSS

export default function Card({ title, content }) {
  return (
    <div className="p-6 max-w-sm mx-auto bg-white rounded-xl shadow-lg flex items-center space-x-4">
      <div>
        <div className="text-xl font-medium text-black">{title}</div>
        <p className="text-gray-500">{content}</p>
      </div>
    </div>
  );
}

Middleware

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Verificar autenticación
  const token = request.cookies.get('token');

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/dashboard/:path*',
};

Testing

// __tests__/Home.test.tsx
import { render, screen } from '@testing-library/react';
import Home from '@/app/page';

describe('Home', () => {
  it('renders a heading', () => {
    render(<Home />);
    const heading = screen.getByRole('heading', { level: 1 });
    expect(heading).toBeInTheDocument();
  });
});

Deployment

Configuración de Producción

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['tu-dominio.com'],
  },
  async redirects() {
    return [
      {
        source: '/old-page',
        destination: '/new-page',
        permanent: true,
      },
    ];
  },
};

module.exports = nextConfig;

Mejores Prácticas

Organización del Código

   app/
   ├── (auth)/
   │   ├── login/
   │   └── register/
   ├── (dashboard)/
   │   ├── profile/
   │   └── settings/
   └── (marketing)/
       ├── about/
       └── contact/

Error Handling

   // app/error.tsx
   'use client';

   export default function Error({
     error,
     reset,
   }: {
     error: Error & { digest?: string };
     reset: () => void;
   }) {
     return (
       <div>
         <h2>¡Algo salió mal!</h2>
         <button onClick={() => reset()}>Intentar de nuevo</button>
       </div>
     );
   }

Loading States

   // app/loading.tsx
   export default function Loading() {
     return (
       <div className="flex items-center justify-center">
         <div className="animate-spin rounded-full h-32 w-32 border-b-2 border-gray-900" />
       </div>
     );
   }

Conclusión

Next.js 14 ofrece:

Rendimiento excepcional
Excelente DX (Developer Experience)
Escalabilidad
Flexibilidad en el renderizado
Integración perfecta con React

Es la elección ideal para:

Aplicaciones web empresariales
Sitios de e-commerce
Aplicaciones SaaS
Sitios de contenido dinámico

Recursos Adicionales

¿Estás usando Next.js en tus proyectos? ¿Qué características te parecen más útiles? ¡Comparte tu experiencia en los comentarios! 🚀

nextjs #react #webdev #javascript

Astro: El Framework Todo en Uno para el Desarrollo Web Moderno

Joaquín Gutiérrez — Fri, 06 Dec 2024 12:54:41 +0000

¿Qué es Astro?

Astro es un framework web todo en uno diseñado para crear sitios web rápidos y orientados al contenido. Combina lo mejor de los frameworks modernos con un enfoque único: enviar cero JavaScript por defecto al navegador.

¿Por qué Astro?

Características Principales

Zero JavaScript por defecto
- Mejor rendimiento inicial
- Menor consumo de recursos
- Mayor SEO
Islands Architecture
- Hidratación parcial
- Componentes interactivos aislados
- Mejor rendimiento en producción
Soporte Multi-Framework
- React
- Vue
- Svelte
- Preact
- SolidJS
- Alpine.js
- Lit

Primeros Pasos

Instalación

# Crear nuevo proyecto
npm create astro@latest

# O con PNPM
pnpm create astro@latest

# O con Yarn
yarn create astro

Estructura de Proyecto

├── src/
│   ├── components/
│   │   └── Header.astro
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       └── index.astro
├── public/
│   └── favicon.svg
├── astro.config.mjs
└── package.json

Componentes en Astro

Componentes Básicos

---
// Script de componente (JavaScript/TypeScript)
const title = "Mi Primer Componente";
---

<!-- Template (HTML + Directivas especiales) -->
<div>
  <h1>{title}</h1>
  <slot /> <!-- Similar a children en React -->
</div>

<style>
  /* Estilos con scope automático */
  h1 {
    color: blue;
  }
</style>

Componentes Dinámicos

---
const posts = await getPosts();
---

<ul>
  {posts.map(post => (
    <li>
      <h2>{post.title}</h2>
      <p>{post.excerpt}</p>
    </li>
  ))}
</ul>

Layouts

Layout Base

---
// src/layouts/Layout.astro
const { title } = Astro.props;
---

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>{title}</title>
  </head>
  <body>
    <nav>
      <a href="/">Inicio</a>
      <a href="/blog">Blog</a>
    </nav>

    <main>
      <slot />
    </main>

    <footer>
      <p>© 2024 Mi Sitio</p>
    </footer>
  </body>
</html>

Uso del Layout

---
import Layout from '../layouts/Layout.astro';
---

<Layout title="Página de Inicio">
  <h1>Bienvenidos a mi sitio</h1>
  <p>Este es un ejemplo de contenido.</p>
</Layout>

Routing

Páginas Estáticas

// src/pages/index.astro -> /
// src/pages/about.astro -> /about
// src/pages/blog.astro -> /blog

Rutas Dinámicas

---
// src/pages/posts/[slug].astro
export async function getStaticPaths() {
  const posts = await getPosts();

  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
---

<Layout title={post.title}>
  <h1>{post.title}</h1>
  <article>{post.content}</article>
</Layout>

Integración con Frameworks

React en Astro

---
import { Counter } from '../components/Counter.jsx';
---

<div>
  <Counter client:load />
</div>

Directivas de Cliente

client:load: Carga e hidrata inmediatamente
client:idle: Hidrata cuando el navegador está inactivo
client:visible: Hidrata cuando el componente es visible
client:media: Hidrata basado en media queries
client:only: Solo renderiza en el cliente

Data Fetching

Server-side

---
const response = await fetch('https://api.ejemplo.com/data');
const data = await response.json();
---

<ul>
  {data.map(item => <li>{item.name}</li>)}
</ul>

API Endpoints

// src/pages/api/posts.json.ts
export async function GET() {
  const posts = await getPosts();

  return new Response(JSON.stringify(posts), {
    headers: {
      'Content-Type': 'application/json'
    }
  });
}

Optimizaciones

Imágenes

---
import { Image } from 'astro:assets';
import imagen from '../assets/imagen.jpg';
---

<Image 
  src={imagen} 
  alt="Mi imagen"
  width={800}
  height={600}
/>

Estilos

---
// Global styles
import '../styles/global.css';
---

<style>
  /* Estilos con scope */
  .container {
    max-width: 1200px;
    margin: 0 auto;
  }
</style>

Despliegue

Build Estático

npm run build

SSR con Adaptadores

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

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Mejores Prácticas

Organización de Código

   src/
   ├── components/
   │   ├── common/
   │   ├── layout/
   │   └── features/
   ├── layouts/
   ├── pages/
   └── utils/

Manejo de Datos

   // src/utils/api.ts
   export async function getPosts() {
     try {
       const response = await fetch('...');
       return await response.json();
     } catch (error) {
       console.error('Error fetching posts:', error);
       return [];
     }
   }

SEO

   ---
   import { SEO } from '../components/SEO.astro';
   ---

   <head>
     <SEO 
       title="Mi Página"
       description="Descripción para SEO"
       image="https://mi-sitio.com/imagen.jpg"
     />
   </head>

Astro es una excelente opción para:

Sitios orientados al contenido
Blogs y portfolios
Sitios de documentación
Marketing y landing pages
Aplicaciones con bajo JavaScript

Su enfoque en el rendimiento, junto con su flexibilidad y facilidad de uso, lo hace una opción atractiva para el desarrollo web moderno.

Recursos Adicionales

Optimizando la Integración de APIs de Blog: Lecciones Aprendidas con Dev.to y Hashnode

Joaquín Gutiérrez — Fri, 06 Dec 2024 12:49:09 +0000

Durante el desarrollo de mi portfolio personal con Astro, me encontré con un desafío interesante: ¿cómo integrar de manera eficiente mis posts de Dev.to y Hashnode sin tener que reconstruir el sitio cada vez que publico nuevo contenido?

El Problema

El problema parecía simple al principio: mostrar todos mis posts de ambas plataformas en una sola página. Sin embargo, me encontré con varios desafíos:

Límites de Paginación: Inicialmente, estaba obteniendo solo los primeros 20-30 posts
Posts Perdidos: Cada vez que publicaba un nuevo post, tenía que modificar el código para que apareciera
Caché Agresivo: Los posts nuevos no aparecían inmediatamente debido al caché

La Solución

1. Endpoint Serverless

Creé un endpoint serverless en Astro que combina los posts de ambas plataformas:

export const GET: APIRoute = async () => {
  const [hashnodePosts, devtoPosts] = await Promise.all([
    getHashnodePosts(),
    getDevToPosts()
  ]);

  const allPosts = [...hashnodePosts, ...devtoPosts]
    .sort((a, b) => 
      new Date(b.rawDate).getTime() - new Date(a.rawDate).getTime()
    );

  return new Response(JSON.stringify(allPosts), {
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-store, no-cache, must-revalidate'
    }
  });
};

2. Maximizando la Obtención de Posts

La clave está en solicitar el máximo número de posts posible:

// Para Dev.to
const params = new URLSearchParams({
  username: 'goaqidev',
  per_page: '1000', // Máximo número de posts
  state: 'published'
});

// Para Hashnode
const query = `
  query {
    publication(host: "goaqidev.hashnode.dev") {
      posts(first: 1000) { // Máximo número de posts
        edges {
          node {
            title
            brief
            // ...otros campos
          }
        }
      }
    }
  }
`;

3. Evitando el Caché

Para asegurar contenido fresco, implementé una estrategia anti-caché:

const timestamp = new Date().getTime();
const response = await fetch(`/api/posts.json?_=${timestamp}`, {
  headers: {
    'Cache-Control': 'no-cache',
    'Pragma': 'no-cache'
  }
});

4. Implementación de Cliente

Para mantener la interfaz actualizada, creé un componente React que maneja la carga y actualización de posts:

import { useState, useEffect } from 'react';

function BlogPosts() {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchPosts = async () => {
      try {
        const timestamp = new Date().getTime();
        const response = await fetch(`/api/posts.json?_=${timestamp}`);
        const data = await response.json();
        setPosts(data);
      } catch (error) {
        console.error('Error fetching posts:', error);
      } finally {
        setLoading(false);
      }
    };

    fetchPosts();
    // Actualizar cada 5 minutos
    const interval = setInterval(fetchPosts, 5 * 60 * 1000);
    return () => clearInterval(interval);
  }, []);

  if (loading) return <div>Cargando posts...</div>;

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
      {posts.map(post => (
        <article key={post.id} className="card">
          <h2>{post.title}</h2>
          <p>{post.brief}</p>
          <a href={post.url}>Leer más</a>
        </article>
      ))}
    </div>
  );
}

Beneficios Obtenidos

Actualización Automática: Los posts nuevos aparecen sin necesidad de reconstruir el sitio
Mejor Rendimiento: La carga inicial es más rápida gracias al endpoint serverless
Sin Pérdida de Contenido: Todos los posts son accesibles, sin importar cuándo fueron publicados
Mantenimiento Reducido: No se requiere intervención manual para mostrar nuevos posts

Manejo de Errores

Implementé un sistema robusto de manejo de errores:

async function fetchPosts() {
  try {
    const response = await fetch('/api/posts.json');
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const posts = await response.json();
    return posts;
  } catch (error) {
    console.error('Error fetching posts:', error);
    // Intentar cargar desde caché local si está disponible
    const cachedPosts = localStorage.getItem('blog_posts');
    return cachedPosts ? JSON.parse(cachedPosts) : [];
  }
}

Optimización de Rendimiento

Para mejorar aún más el rendimiento, implementé:

Caché Local:

// Guardar posts en localStorage
localStorage.setItem('blog_posts', JSON.stringify(posts));

// Cargar posts desde localStorage mientras se actualiza
const cachedPosts = localStorage.getItem('blog_posts');
if (cachedPosts) {
  setPosts(JSON.parse(cachedPosts));
}

Lazy Loading de Imágenes:

function PostImage({ src, alt }) {
  return (
    <img 
      loading="lazy"
      src={src} 
      alt={alt}
      className="w-full h-48 object-cover"
    />
  );
}

Esta solución ha demostrado ser robusta y eficiente, permitiéndome:

Mantener mi portfolio actualizado automáticamente
Mejorar la experiencia del usuario con carga rápida
Reducir la necesidad de mantenimiento manual
Asegurar que todo mi contenido esté disponible y actualizado

Próximos Pasos

Planeo implementar:

Sistema de búsqueda y filtrado de posts
Previsualización de contenido
Métricas de engagement
Sistema de comentarios unificado

API Keys y Variables de Entorno en Astro: Guía Completa de Seguridad

Joaquín Gutiérrez — Fri, 06 Dec 2024 12:38:25 +0000

Cuando desarrollamos aplicaciones web con Astro, frecuentemente necesitamos interactuar con APIs y servicios externos. Manejar las credenciales y claves de API de forma segura es crucial para proteger nuestras aplicaciones. En esta guía, exploraremos las mejores prácticas para gestionar API keys y variables de entorno en proyectos Astro.

Variables de Entorno en Astro

Configuración Básica

En Astro, las variables de entorno se manejan de forma similar a otros frameworks modernos. Primero, creamos un archivo .env en la raíz de nuestro proyecto:

# .env
PUBLIC_API_URL=https://api.ejemplo.com
PRIVATE_API_KEY=tu_clave_secreta
DATABASE_URL=postgresql://usuario:password@localhost:5432/db

Para TypeScript, es recomendable crear un archivo env.d.ts para tipar nuestras variables:

/// <reference types="astro/client" />
interface ImportMetaEnv {
  readonly DATABASE_URL: string;
  readonly PRIVATE_API_KEY: string;
  readonly PUBLIC_API_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Accediendo a las Variables

En Astro, podemos acceder a las variables de entorno de diferentes formas según el contexto:

---
// En archivos .astro
const apiKey = import.meta.env.PRIVATE_API_KEY;
const publicUrl = import.meta.env.PUBLIC_API_URL;
---

// En archivos .ts o .js
const apiKey = import.meta.env.PRIVATE_API_KEY;

Seguridad en el Frontend

Variables Públicas vs Privadas

Astro sigue una convención importante para las variables de entorno:

PUBLIC_*: Accesibles en el cliente y el servidor
Sin prefijo PUBLIC_: Solo accesibles en el servidor

# .env
PUBLIC_API_URL=https://api.publica.com    # ✅ Visible en el cliente
PRIVATE_API_KEY=secreto123                # ⛔ Solo servidor

Protegiendo Claves Sensibles

Para manejar APIs que requieren autenticación, debemos crear endpoints serverless:

// src/pages/api/data.ts
export async function GET() {
  try {
    const response = await fetch('https://api.externa.com/data', {
      headers: {
        'Authorization': `Bearer ${import.meta.env.PRIVATE_API_KEY}`
      }
    });

    const data = await response.json();
    return new Response(JSON.stringify(data), {
      status: 200,
      headers: {
        'Content-Type': 'application/json'
      }
    });
  } catch (error) {
    return new Response(JSON.stringify({ error: 'Error al obtener datos' }), {
      status: 500
    });
  }
}

Mejores Prácticas

1. Validación de Variables de Entorno

Implementa una función de validación al inicio de tu aplicación:

// src/utils/validateEnv.ts
export function validateEnv() {
  const requiredEnvVars = [
    'DATABASE_URL',
    'PRIVATE_API_KEY',
    'PUBLIC_API_URL'
  ];

  for (const envVar of requiredEnvVars) {
    if (!import.meta.env[envVar]) {
      throw new Error(`La variable de entorno ${envVar} es requerida`);
    }
  }
}

// src/pages/index.astro
---
import { validateEnv } from '../utils/validateEnv';

if (import.meta.env.MODE === 'development') {
  validateEnv();
}
---

2. Gestión de Múltiples Entornos

Crea diferentes archivos para cada entorno:

.env                # Variables por defecto
.env.development    # Variables de desarrollo
.env.production     # Variables de producción
.env.local          # Variables locales (ignoradas en git)

3. Template de Variables de Entorno

Proporciona un archivo .env.example:

# .env.example
PUBLIC_API_URL=https://api.ejemplo.com
PRIVATE_API_KEY=tu_clave_aqui
DATABASE_URL=postgresql://usuario:password@localhost:5432/db

4. Configuración de Git

Asegúrate de incluir los archivos sensibles en .gitignore:

# .gitignore
.env
.env.local
.env.*.local

Integración con Servicios Externos

Ejemplo con Stripe

// src/pages/api/create-payment.ts
import Stripe from 'stripe';

export async function POST({ request }) {
  const stripe = new Stripe(import.meta.env.STRIPE_SECRET_KEY);

  try {
    const { amount, currency } = await request.json();

    const paymentIntent = await stripe.paymentIntents.create({
      amount,
      currency
    });

    return new Response(JSON.stringify({ clientSecret: paymentIntent.client_secret }), {
      status: 200
    });
  } catch (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 400
    });
  }
}

Ejemplo con Firebase

// src/lib/firebase.ts
import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';

const firebaseConfig = {
  apiKey: import.meta.env.PUBLIC_FIREBASE_API_KEY,
  authDomain: import.meta.env.PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.PUBLIC_FIREBASE_PROJECT_ID,
};

export const app = initializeApp(firebaseConfig);
export const db = getFirestore(app);

Despliegue y CI/CD

Configuración en Vercel

# Configurar variables en Vercel CLI
vercel env add PRIVATE_API_KEY
vercel env add DATABASE_URL

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to Vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
          PRIVATE_API_KEY: ${{ secrets.PRIVATE_API_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: vercel deploy --prod --token=$VERCEL_TOKEN

Consejos de Seguridad Adicionales

Rotación de Claves: Implementa un sistema para rotar periódicamente las claves API

// src/utils/rotateApiKey.ts
async function rotateApiKey() {
  const currentKey = import.meta.env.PRIVATE_API_KEY;
  const expirationDays = 30;

  // Lógica para verificar la edad de la clave
  // Implementar rotación si es necesario
}

Monitoreo de Uso: Implementa logging para detectar uso indebido

// src/middleware/apiLogger.ts
export async function apiLogger(request, apiName) {
  console.log(`[${new Date().toISOString()}] API Call: ${apiName}`);
  // Implementar logging más detallado según necesidades
}

El manejo seguro de API keys y variables de entorno es crucial para cualquier aplicación web moderna. Siguiendo estas mejores prácticas en Astro, podemos:

Mantener nuestras credenciales seguras
Separar configuraciones por entorno
Implementar validaciones robustas
Integrar servicios externos de forma segura

Integrando Múltiples APIs de Blog en un Sitio Astro: Dev.to y Hashnode

Joaquín Gutiérrez — Fri, 06 Dec 2024 12:24:31 +0000

Si eres como yo, probablemente escribas en varias plataformas de blogging. En mi caso, uso tanto Dev.to como Hashnode para llegar a diferentes audiencias. Pero, ¿qué pasa cuando quieres mostrar todos tus posts en tu sitio personal? Hoy te mostraré cómo integré ambas APIs en mi portfolio construido con Astro.

El Desafío

El principal reto era:

Obtener posts de dos APIs diferentes
Unificar el formato de los datos
Ordenarlos cronológicamente
Manejar errores y rate limiting
Tipado seguro con TypeScript

Configuración Inicial

Primero, definimos las interfaces para tipar nuestros datos:

interface BlogPost {
  title: string;
  brief: string;
  slug: string;
  dateAdded: string;
  rawDate: string;
  coverImage: string;
  url: string;
  source: string;
}

interface HashnodeEdge {
  node: {
    title: string;
    brief: string;
    slug: string;
    dateAdded: string;
    coverImage?: {
      url: string;
    };
    url: string;
  };
}

Integrando Dev.to

La API de Dev.to es RESTful y bastante directa. Aquí está cómo la implementé:

async function getDevToPosts() {
  try {
    const params = new URLSearchParams({
      username: 'tuUsuario',
      per_page: '20',
      state: 'all',
      sort: 'published_at',
      order: 'desc'
    });

    const headers = {
      'Accept': 'application/vnd.forem.api-v1+json'
    };

    // Agregar API key si está disponible
    if (import.meta.env.DEV_TO_API_KEY) {
      headers['api-key'] = import.meta.env.DEV_TO_API_KEY;
    }

    const response = await fetch(`https://dev.to/api/articles?${params}`, { headers });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const posts = await response.json();

    return posts.map((post: any) => ({
      title: post.title,
      brief: post.description,
      slug: post.slug,
      dateAdded: formatDate(post.published_timestamp),
      rawDate: post.published_timestamp,
      coverImage: post.cover_image || '/images/default-post.png',
      url: post.url,
      source: 'devto'
    }));
  } catch (error) {
    console.error('Error al obtener posts de Dev.to:', error);
    return [];
  }
}

Integrando Hashnode

Hashnode usa GraphQL, lo que requiere un enfoque ligeramente diferente:

async function getHashnodePosts() {
  try {
    const query = `
      query {
        publication(host: "tuBlog.hashnode.dev") {
          posts(first: 20) {
            edges {
              node {
                title
                brief
                slug
                dateAdded: publishedAt
                coverImage {
                  url
                }
                url
              }
            }
          }
        }
      }
    `;

    const response = await fetch('https://gql.hashnode.com', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query })
    });

    const { data } = await response.json();

    return data.publication.posts.edges.map((edge: HashnodeEdge) => ({
      title: edge.node.title,
      brief: edge.node.brief,
      slug: edge.node.slug,
      dateAdded: formatDate(edge.node.dateAdded),
      rawDate: edge.node.dateAdded,
      coverImage: edge.node.coverImage?.url || '/images/default-post.png',
      url: edge.node.url,
      source: 'hashnode'
    }));
  } catch (error) {
    console.error('Error al obtener posts de Hashnode:', error);
    return [];
  }
}

Combinando los Resultados

La magia ocurre al combinar y ordenar los posts:

const hashnodePosts = await getHashnodePosts();
const devtoPosts = await getDevToPosts();

const allBlogPosts = [...hashnodePosts, ...devtoPosts]
  .sort((a, b) => new Date(b.rawDate).getTime() - new Date(a.rawDate).getTime());

Manejo de Errores y Rate Limiting

Para manejar el rate limiting y errores, implementé estas estrategias:

Caché del lado del cliente:

const CACHE_DURATION = 5 * 60 * 1000; // 5 minutos
let postsCache = {
  data: null,
  timestamp: 0
};

async function getAllPosts() {
  const now = Date.now();
  if (postsCache.data && (now - postsCache.timestamp) < CACHE_DURATION) {
    return postsCache.data;
  }

  // Obtener y combinar posts...

  postsCache = {
    data: allBlogPosts,
    timestamp: now
  };
  return allBlogPosts;
}

Reintentos con backoff exponencial:

async function fetchWithRetry(url: string, options: any, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) { // Rate limit
        const retryAfter = response.headers.get('Retry-After') || '60';
        await new Promise(resolve => setTimeout(resolve, parseInt(retryAfter) * 1000));
        continue;
      }
      return response;
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

Renderizado en Astro

Finalmente, renderizamos los posts en nuestro componente Astro:

---
const allBlogPosts = await getAllPosts();
---

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {allBlogPosts.map((post) => (
    <article class="card">
      <img src={post.coverImage} alt={post.title} />
      <div class="p-4">
        <span class={`badge ${post.source}`}>
          {post.source === 'devto' ? 'Dev.to' : 'Hashnode'}
        </span>
        <h2>{post.title}</h2>
        <p>{post.brief}</p>
        <a href={post.url}>Leer más</a>
      </div>
    </article>
  ))}
</div>

Esta integración nos permite:

Mantener una única fuente de verdad para nuestros posts
Mostrar contenido de múltiples plataformas
Manejar errores de manera elegante
Mantener un código tipado y seguro

El código completo está disponible en mi GitHub.

¿Has integrado otras plataformas de blogging en tu sitio? ¡Comparte tus experiencias en los comentarios! 👇

webdev #astro #typescript #api

JSDoc: La Guía Definitiva para Documentar tu Código JavaScript

Joaquín Gutiérrez — Fri, 06 Dec 2024 12:14:03 +0000

JSDoc es una herramienta de documentación para JavaScript que permite agregar comentarios tipados y estructurados a tu código. Similar a JavaDoc para Java, JSDoc no solo ayuda a documentar tu código, sino que también mejora la experiencia de desarrollo con autocompletado e información de tipos en editores modernos como Visual Studio Code.

¿Por qué usar JSDoc?

Mejora la mantenibilidad: Facilita entender el código meses después
Autocompletado inteligente: Los IDEs pueden proporcionar sugerencias más precisas
Documentación automática: Genera documentación HTML a partir de comentarios
Validación de tipos: Proporciona verificación de tipos sin necesidad de TypeScript
Compatibilidad: Funciona con JavaScript vanilla y con frameworks modernos

Sintaxis Básica

Estructura de un Comentario JSDoc

Los comentarios JSDoc comienzan con /** y terminan con */:

/**
 * Calcula el área de un rectángulo.
 * @param {number} ancho - El ancho del rectángulo
 * @param {number} alto - El alto del rectángulo
 * @returns {number} El área del rectángulo
 */
function calcularArea(ancho, alto) {
    return ancho * alto;
}

Tags Principales

@param

Documenta los parámetros de una función:

/**
 * @param {string} nombre - Nombre del usuario
 * @param {number} [edad] - Edad del usuario (opcional)
 * @param {Object} opciones - Opciones de configuración
 * @param {boolean} opciones.activo - Estado del usuario
 * @param {string} opciones.rol - Rol del usuario
 */
function crearUsuario(nombre, edad, opciones) {
    // Implementación
}

@returns

Especifica el valor de retorno:

/**
 * @returns {Promise<User>} Promesa que resuelve con los datos del usuario
 */
async function obtenerUsuario() {
    // Implementación
}

@typedef

Define tipos personalizados:

/**
 * @typedef {Object} Usuario
 * @property {string} id - ID único del usuario
 * @property {string} nombre - Nombre completo
 * @property {number} edad - Edad del usuario
 * @property {string[]} roles - Lista de roles asignados
 */

/**
 * @param {Usuario} usuario
 * @returns {boolean}
 */
function validarUsuario(usuario) {
    // Implementación
}

@callback

Define tipos para funciones callback:

/**
 * @callback ValidatorCallback
 * @param {string} valor - Valor a validar
 * @returns {boolean} Resultado de la validación
 */

/**
 * @param {string} dato
 * @param {ValidatorCallback} validador
 */
function procesarDato(dato, validador) {
    if (validador(dato)) {
        // Procesar dato
    }
}

Tipos Complejos

Arrays y Objetos

/**
 * @param {Array<string>} nombres - Lista de nombres
 * @param {Object.<string, number>} edades - Mapa de nombres a edades
 */
function procesarDatos(nombres, edades) {
    // Implementación
}

Uniones y Tipos Nullable

/**
 * @param {string|number} id - ID que puede ser string o número
 * @param {?string} descripcion - Descripción opcional (puede ser null)
 */
function buscarElemento(id, descripcion) {
    // Implementación
}

Documentación de Clases

/**
 * Representa un vehículo genérico.
 * @class
 */
class Vehiculo {
    /**
     * Crea una instancia de Vehiculo.
     * @param {string} marca - Marca del vehículo
     * @param {string} modelo - Modelo del vehículo
     * @param {number} año - Año de fabricación
     */
    constructor(marca, modelo, año) {
        this.marca = marca;
        this.modelo = modelo;
        this.año = año;
    }

    /**
     * Calcula la edad del vehículo.
     * @returns {number} Edad en años
     */
    obtenerEdad() {
        return new Date().getFullYear() - this.año;
    }
}

Integración con VS Code

Configuración del proyecto

Crea un archivo jsconfig.json en la raíz de tu proyecto:

{
    "compilerOptions": {
        "checkJs": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true
    },
    "exclude": ["node_modules", "dist"]
}

Generación de Documentación

Instalación de JSDoc

npm install -g jsdoc

Configuración de JSDoc

Crea un archivo jsdoc.json:

{
    "source": {
        "include": ["src"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": ["plugins/markdown"],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": true
    },
    "opts": {
        "recurse": true,
        "destination": "./docs"
    }
}

Generación de documentación HTML

jsdoc -c jsdoc.json

Mejores Prácticas

Sé consistente: Mantén un estilo de documentación uniforme en todo el proyecto

/**
 * ✅ Buena documentación
 * @param {string} nombre
 * @returns {boolean}
 */
function validar(nombre) {}

/**
 * ❌ Documentación inconsistente
 * @param nombre: string
 * @return boolean
 */
function validar(nombre) {}

Documenta los efectos secundarios:

/**
 * Guarda el usuario en la base de datos.
 * @param {Usuario} usuario
 * @throws {Error} Si la conexión falla
 * @fires {evento:usuarios:creado} Cuando el usuario es creado
 */
function guardarUsuario(usuario) {}

Usa ejemplos para casos complejos:

/**
 * Formatea una fecha según el locale especificado.
 * @param {Date} fecha
 * @param {string} [locale=es-ES]
 * @returns {string}
 * @example
 * // Retorna "1 de enero de 2024"
 * formatearFecha(new Date(2024, 0, 1), 'es-ES')
 */
function formatearFecha(fecha, locale = 'es-ES') {}

Herramientas y Plugins

ESLint: Configura reglas para validar la documentación
DocumentThis: Extension de VS Code para generar JSDoc automáticamente
better-docs: Plantilla mejorada para la documentación generada

JSDoc es una herramienta poderosa que mejora significativamente la calidad y mantenibilidad de tu código JavaScript. Con el soporte adecuado del IDE y las herramientas de generación de documentación, puedes crear una base de código más robusta y fácil de mantener.

Próximos pasos recomendados:

Configura JSDoc en tu proyecto actual
Empieza documentando las funciones públicas
Configura tu editor para aprovechar el autocompletado
Implementa la generación automática de documentación en tu pipeline de CI/CD

Recursos Adicionales

React y Next.js: Desenredando el Ecosistema de Desarrollo Web Moderno

Joaquín Gutiérrez — Fri, 06 Dec 2024 11:24:27 +0000

Si estás empezando en el desarrollo web moderno, específicamente con JavaScript, probablemente te hayas encontrado con términos como React y Next.js, y te preguntes cuál es la relación entre ellos y por dónde deberías empezar. En este artículo, vamos a aclarar estos conceptos y establecer una ruta de aprendizaje clara.

¿Qué es React?

React es una biblioteca de JavaScript desarrollada por Facebook (ahora Meta) que se utiliza para construir interfaces de usuario (UI) interactivas. Es la base sobre la que se construyen muchas aplicaciones web modernas.

Fundamentos de React

Componentes
- Son bloques de construcción reutilizables
- Pueden ser tan pequeños como un botón o tan grandes como una página completa
- Ejemplo básico de un componente:

function Welcome({ name }) {
  return <h1>Hola, {name}</h1>;
}

Estado y Props
- El estado (state) maneja datos que pueden cambiar
- Las props son datos que se pasan de un componente padre a un hijo
- Ejemplo de uso de estado:

import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Has hecho clic {count} veces</p>
      <button onClick={() => setCount(count + 1)}>
        Incrementar
      </button>
    </div>
  );
}

Virtual DOM
- React utiliza una representación virtual del DOM para optimizar las actualizaciones
- Compara los cambios y actualiza solo lo necesario en el DOM real

¿Por qué usar React?

Reusabilidad: Los componentes pueden reutilizarse en diferentes partes de tu aplicación
Mantenibilidad: El código es más fácil de mantener y debuggear
Gran ecosistema: Enorme cantidad de bibliotecas y herramientas disponibles
Comunidad activa: Fácil encontrar soluciones a problemas comunes

¿Qué es Next.js?

Next.js es un framework construido sobre React que añade funcionalidades adicionales para crear aplicaciones web completas. Podríamos decir que Next.js es a React lo que un coche completo es a un motor: React es el motor (fundamental), y Next.js es el vehículo completo con todas sus características adicionales.

Características principales de Next.js

Renderizado Híbrido
- Renderizado del lado del servidor (SSR)
- Generación estática (SSG)
- Renderizado del lado del cliente (CSR)
- Ejemplo de página con SSR:

// pages/users.js
export async function getServerSideProps() {
  const res = await fetch('https://api.example.com/users');
  const users = await res.json();

  return {
    props: { users }
  };
}

export default function Users({ users }) {
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Sistema de Routing Basado en Archivos
- Las rutas se crean automáticamente basadas en la estructura de archivos
- No necesitas configurar un router manualmente
Optimización de Imágenes
- Optimización automática de imágenes
- Carga diferida (lazy loading)
- Ejemplo:

import Image from 'next/image';

function Profile() {
  return (
    <Image
      src="/profile.jpg"
      alt="Foto de perfil"
      width={500}
      height={300}
    />
  );
}

Zero Config
- Configuración automática de Babel
- Soporte incorporado para TypeScript
- Hot Reloading incluido

¿Por dónde empezar?

Ruta de aprendizaje recomendada

JavaScript Fundamentals
- Variables, funciones, objetos
- Promesas y async/await
- ES6+ features (arrow functions, destructuring, etc.)
React Basics
- Componentes y JSX
- Estado y props
- Hooks básicos (useState, useEffect)
- Ejemplo de aplicación básica:

import { useState, useEffect } from 'react';

function App() {
  const [data, setData] = useState([]);

  useEffect(() => {
    fetch('https://api.example.com/data')
      .then(response => response.json())
      .then(data => setData(data));
  }, []);

  return (
    <div>
      {data.map(item => (
        <div key={item.id}>{item.name}</div>
      ))}
    </div>
  );
}

Next.js
- Configuración inicial
- Routing
- Data fetching
- Deployment

Proyectos prácticos recomendados

React: Todo List
- Practicar manejo de estado
- Eventos y formularios
- Componentes reutilizables
React: Blog simple
- Routing con React Router
- Comunicación entre componentes
- Gestión de estado más compleja
Next.js: Blog completo
- SSR y SSG
- API Routes
- Optimización de imágenes
- SEO

La relación entre React y Next.js no debe ser intimidante. React es la biblioteca fundamental que necesitas aprender primero, ya que Next.js se construye sobre ella. La documentación de React te menciona Next.js porque es una herramienta muy popular para construir aplicaciones React completas, pero no es necesaria para empezar.

Orden de aprendizaje sugerido:

Domina los fundamentos de JavaScript
Aprende React y construye algunas aplicaciones simples
Cuando te sientas cómodo con React, introduce Next.js para aprovechar sus características adicionales

Recuerda que el aprendizaje es un proceso gradual. No te sientas abrumado por todas las herramientas y conceptos disponibles. Comienza con los fundamentos y ve construyendo sobre ellos paso a paso.

Recursos adicionales

Documentación oficial de React
Documentación oficial de Next.js
JavaScript.info - Excelente recurso para JavaScript
MDN Web Docs - Documentación completa de web development

Dominando el Testing y la Documentación en React: Una Guía Completa

Joaquín Gutiérrez — Fri, 06 Dec 2024 02:34:30 +0000

En el desarrollo moderno de aplicaciones React, la implementación de pruebas robustas y una documentación clara son fundamentales para mantener la calidad del código y la eficiencia del equipo. En esta guía exhaustiva, exploraremos las herramientas y prácticas esenciales que todo desarrollador de React debería conocer.

Jest y React Testing Library: El Dúo Dinámico del Testing

El testing en React ha evolucionado significativamente en los últimos años, y la combinación de Jest con React Testing Library se ha convertido en el estándar de la industria. Jest, desarrollado por Facebook, proporciona un framework de testing completo que se integra perfectamente con aplicaciones React. Su configuración inicial es mínima, especialmente si utilizas Create React App, y viene con todas las herramientas necesarias para escribir pruebas efectivas.

React Testing Library complementa a Jest añadiendo una capa de utilidades específicamente diseñadas para probar componentes React. La filosofía detrás de React Testing Library es simple pero poderosa: las pruebas deberían imitar cómo los usuarios interactúan con tu aplicación. Esto significa que, en lugar de probar detalles de implementación, nos enfocamos en probar el comportamiento visible para el usuario.

Ejemplo Práctico de Testing

import { render, screen, fireEvent } from '@testing-library/react';
import Counter from './Counter';

describe('Counter Component', () => {
  test('renderiza el contador inicial y responde a clicks', () => {
    render(<Counter initialValue={0} />);

    // Verificamos el valor inicial
    expect(screen.getByText('Contador: 0')).toBeInTheDocument();

    // Simulamos un click en el botón de incremento
    fireEvent.click(screen.getByText('Incrementar'));

    // Verificamos que el valor se actualizó
    expect(screen.getByText('Contador: 1')).toBeInTheDocument();
  });
});

Tests Unitarios en Profundidad

Los tests unitarios son la base de una estrategia de testing efectiva. Para componentes React y hooks personalizados, estos tests son cruciales por varias razones:

Testing de Componentes

Verificación del renderizado inicial
Pruebas de interacciones del usuario
Validación de props y su efecto en el componente
Comprobación de estados de error y casos límite

Testing de Hooks

Los hooks personalizados requieren un enfoque especial. React Testing Library proporciona renderHook, una utilidad específica para probar hooks:

import { renderHook, act } from '@testing-library/react-hooks';
import useCounter from './useCounter';

test('useCounter incrementa y decrementa correctamente', () => {
  const { result } = renderHook(() => useCounter(0));

  act(() => {
    result.current.increment();
  });

  expect(result.current.count).toBe(1);
});

Documentación con JSDoc: Manteniendo el Código Claro

La documentación es crucial para el mantenimiento a largo plazo de cualquier proyecto. JSDoc ofrece una forma estructurada de documentar nuestro código directamente en el source code. Esto no solo ayuda a otros desarrolladores a entender nuestro código, sino que también mejora la experiencia de desarrollo con autocompletado e información contextual en el IDE.

Ejemplo de Documentación con JSDoc

/**
 * Componente que muestra un contador interactivo.
 * @component
 * @param {Object} props - Propiedades del componente
 * @param {number} props.initialValue - Valor inicial del contador
 * @param {function} props.onChange - Callback llamado cuando el valor cambia
 * @returns {React.ReactElement} Componente Counter
 */
function Counter({ initialValue = 0, onChange }) {
  // Implementación del componente...
}

Storybook: Tu Catálogo de Componentes UI

Storybook ha revolucionado la forma en que desarrollamos y documentamos componentes UI. Esta herramienta permite desarrollar componentes de forma aislada, lo que facilita la creación y prueba de componentes individuales sin necesidad de ejecutar toda la aplicación.

Beneficios Clave de Storybook

Desarrollo Aislado: Permite trabajar en componentes sin las distracciones del resto de la aplicación.
Documentación Viva: Cada story sirve como ejemplo vivo de cómo usar el componente.
Testing Visual: Facilita la detección de problemas visuales y de diseño.
Colaboración Mejorada: Diseñadores y desarrolladores pueden trabajar juntos más eficientemente.

Ejemplo de Story

import { Button } from './Button';

export default {
  title: 'Componentes/Button',
  component: Button,
  argTypes: {
    variant: {
      options: ['primary', 'secondary'],
      control: { type: 'select' }
    }
  }
};

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Botón Primario'
  }
};

Conclusión

La implementación de estas herramientas y prácticas puede parecer abrumadora al principio, pero los beneficios a largo plazo son innegables. Un código bien probado y documentado no solo es más mantenible, sino que también facilita la incorporación de nuevos miembros al equipo y reduce el tiempo dedicado a depurar problemas.

La clave está en comenzar poco a poco, quizás implementando primero los tests más críticos, y luego ir expandiendo la cobertura gradualmente. La documentación puede crecer orgánicamente mientras desarrollas nuevas características, y Storybook puede implementarse componente por componente.

Recuerda: la calidad del código no es un destino, sino un viaje continuo. Cada pequeño paso en la dirección correcta cuenta.

¿Tienes experiencia implementando alguna de estas herramientas en tus proyectos? ¡Comparte tus experiencias en los comentarios!

Patrones de Arquitectura: Guía de inicio

Joaquín Gutiérrez — Tue, 03 Dec 2024 22:59:41 +0000

Cuando empezamos en el desarrollo de software, nos centramos principalmente en aprender lenguajes de programación, frameworks y herramientas. Sin embargo, llega un momento en el que nos enfrentamos a decisiones más grandes: ¿Cómo organizamos nuestra aplicación? ¿cómo aseguramos que pueda crecer sin problemas? Es aquí donde entran en juego los patrones de arquitectura.

Los patrones de arquitectura son soluciones probadas a problemas comunes en el diseño de software. Si alguna vez has usado aplicaciones como Netflix, WhatsApp o incluso un simple blog en WordPress, has interactuado con diferentes patrones arquitectónicos sin saberlo. Cada uno de estos servicios utiliza patrones específicos que les permiten funcionar de manera eficiente según sus necesidades particulares.

La belleza de los patrones arquitectónicos radica en que no son reglas estrictas, sino guías que nos ayudan a tomar decisiones informadas. Cuando diseñamos software, estos patrones nos proporcionan un lenguaje común y una estructura base sobre la cual construir nuestras aplicaciones.

Entendiendo los Patrones Fundamentales

El patrón monolítico es quizás el más intuitivo y con el que la mayoría comenzamos. Imagina una aplicación como un gran bloque donde todas las funcionalidades están integradas. Es como tener toda tu casa en un único espacio: dormitorio, cocina y sala de estar en una sola habitación. Puede funcionar perfectamente para espacios pequeños, pero conforme creces, podrías necesitar una distribución diferente.

Por otro lado, los microservicios son como tener un complejo de apartamentos donde cada unidad es independiente pero forma parte del mismo edificio. Netflix, por ejemplo, utiliza este patrón para manejar sus diferentes servicios: uno para recomendaciones, otro para streaming, otro para gestión de usuarios. Cada servicio puede evolucionar y escalarse de manera independiente.

El patrón cliente-servidor es algo que usamos a diario sin darnos cuenta. Cada vez que abres WhatsApp en tu teléfono (cliente) y envías un mensaje, este viaja a través de servidores que procesan y entregan la información. Es un patrón tan fundamental que forma la base de gran parte de las comunicaciones en internet.

La Evolución de tu Arquitectura

Una de las lecciones más valiosas que he aprendido es que la arquitectura de una aplicación no es estática. Twitter, por ejemplo, comenzó como un monolito y evolucionó hacia microservicios conforme creció su base de usuarios. No hay nada malo en empezar con una arquitectura simple y permitir que evolucione con las necesidades de tu proyecto.

La arquitectura en capas es otro patrón que merece atención especial. En lugar de dividir tu aplicación en servicios independientes, la organizas en capas con responsabilidades específicas. La capa de presentación maneja la interfaz de usuario, la capa de lógica de negocio procesa las reglas y cálculos, y la capa de datos gestiona el almacenamiento. Es como un pastel de bodas donde cada nivel tiene su propósito pero todos trabajan en conjunto para crear algo cohesivo.

Eligiendo tu Camino

La elección del patrón adecuado depende de múltiples factores. ¿Estás construyendo una aplicación que necesita manejar millones de usuarios concurrentes? Los microservicios podrían ser tu mejor opción. ¿Un blog personal o una aplicación empresarial pequeña? Un monolito bien diseñado podría ser más que suficiente.

Lo importante es entender que no existe un patrón "perfecto". Cada uno tiene sus compensaciones. Los microservicios ofrecen excelente escalabilidad pero añaden complejidad en la comunicación entre servicios. Los monolitos son más sencillos de desarrollar inicialmente pero pueden volverse difíciles de mantener si crecen demasiado.

Recursos para Profundizar

El viaje para entender los patrones de arquitectura es continuo. Libros como "Clean Architecture" de Robert C. Martin o "Patterns of Enterprise Application Architecture" de Martin Fowler son excelentes recursos para profundizar en el tema. También recomiendo explorar casos de estudio de empresas reales: muchas compañías tecnológicas comparten sus experiencias y decisiones arquitectónicas en sus blogs técnicos.

Si estás comenzando, mi consejo es empezar con proyectos pequeños y experimentar. Construye un monolito simple, luego intenta dividirlo en servicios. Aprende sobre los diferentes patrones probándolos en la práctica. La experiencia práctica es invaluable en este campo.

Patrones Arquitectónicos en Detalle

Vamos a profundizar en algunos de los patrones más relevantes en la actualidad:

Arquitectura por Eventos (Event-Driven Architecture)

Este patrón se centra en la producción, detección y reacción a eventos. Imagina un sistema de comercio electrónico: cuando un usuario realiza una compra (evento), esto desencadena múltiples acciones: actualización del inventario, notificación al cliente, generación de factura, etc.

Mejor aplicado en:

Sistemas de tiempo real
Aplicaciones IoT
Plataformas de trading
Sistemas de monitorización

Componentes clave:

Productores de eventos
Canales de eventos
Consumidores de eventos
Event broker (como Kafka o RabbitMQ)

Arquitectura Hexagonal (Ports and Adapters)

También conocida como "Ports and Adapters", esta arquitectura busca crear aplicaciones que sean igualmente accesibles para usuarios, programas, pruebas automatizadas o scripts por lotes, y que puedan ser desarrolladas y probadas de forma aislada.

Ideal para:

Aplicaciones empresariales complejas
Sistemas que requieren alta mantenibilidad
Aplicaciones con múltiples interfaces de usuario
Sistemas que necesitan ser agnósticos a la tecnología de entrada/salida

Elementos principales:

Núcleo de aplicación (lógica de negocio)
Puertos (interfaces)
Adaptadores (implementaciones específicas)

Arquitectura CQRS (Command Query Responsibility Segregation)

Separa las operaciones de lectura y escritura en modelos diferentes. Es especialmente útil en sistemas con desbalance significativo entre operaciones de lectura y escritura.

Óptimo para:

Aplicaciones de alto rendimiento
Sistemas con complejas reglas de negocio
Aplicaciones con diferentes requisitos de escalado para lecturas y escrituras

Componentes:

Modelo de comando (escrituras)
Modelo de consulta (lecturas)
Event store
Sincronización entre modelos

Arquitectura Serverless

No significa realmente "sin servidor", sino que el proveedor de la nube gestiona la infraestructura. Las funciones se ejecutan en respuesta a eventos.

Perfecta para:

Startups que buscan rápido tiempo de salida al mercado
Aplicaciones con carga variable
Procesamiento de datos por lotes
APIs con bajo tráfico continuo pero picos ocasionales

Características:

Funciones como unidad de despliegue
Escalado automático
Pago por uso
Sin gestión de infraestructura

Arquitectura Basada en Espacio (Space-Based Architecture)

Diseñada para evitar problemas de concurrencia y limitaciones de bases de datos. Los datos se mantienen en memoria distribuida.

Ideal para:

Aplicaciones web con alta concurrencia
Sistemas de juegos en línea
Plataformas de subastas en tiempo real
Sistemas de reservas

Componentes:

Unidades de procesamiento
Virtualización de memoria
Router de mensajes
Gestor de despliegue

arquitectura #software #development #beginners

Construyendo un Portfolio Moderno con Astro y Tailwind CSS

Joaquín Gutiérrez — Sun, 01 Dec 2024 22:29:59 +0000

Introducción

¡Hola comunidad dev! 👋 Hoy quiero compartir mi experiencia construyendo mi portfolio personal usando Astro, un generador de sitios estáticos moderno, junto con Tailwind CSS para el diseño. Os contaré sobre el stack tecnológico, los desafíos encontrados y las lecciones aprendidas durante el proceso de desarrollo.

Stack Tecnológico

Astro (v4.16): El framework principal que impulsa el portfolio
Tailwind CSS (v3.4): Para el diseño y la responsividad
React (v18.3): Para componentes interactivos
TypeScript: Para seguridad de tipos y mejor experiencia de desarrollo

¿Por qué Astro?

Elegí Astro por varias razones convincentes:

Rendimiento: El enfoque "Zero JavaScript por defecto" de Astro asegura cargas de página ultrarrápidas
Islas de Componentes: Capacidad de usar componentes React solo donde sea necesario
Soporte Nativo para Markdown: Perfecto para posts de blog y gestión de contenido
Experiencia de Desarrollo Sencilla: Recarga en caliente de módulos y excelentes herramientas de desarrollo

Estructura del Proyecto

El portfolio sigue una estructura limpia y mantenible, básicamente es la creada por Astro:

/src/pages: Páginas basadas en rutas usando el enrutamiento basado en archivos de Astro
/src/components: Componentes UI reutilizables
/public: Activos estáticos como imágenes y fuentes
/src/layouts: Layouts y plantillas de página

Características Principales

Diseño Responsive: Enfoque mobile-first usando Tailwind CSS
Integración de Blog: Funcionalidad de blog incorporada con soporte Markdown
Arquitectura Basada en Componentes: Componentes modulares y reutilizables
Seguridad de Tipos: Integración completa con TypeScript para mejor calidad de código

Desafíos y Soluciones

1. Curva de Aprendizaje

Viniendo de frameworks tradicionales, el enfoque de Astro sobre hidratación parcial e islas de componentes fue nuevo. La solución fue profundizar en la documentación y experimentar con diferentes aproximaciones. Si eres nuevo, empieza por la documentación oficial y su tutorial, lo agradecerás.

2. Estrategia de Estilos

Decidir entre módulos CSS, styled-components y Tailwind CSS fue desafiante, básicamente porque nunca había tocado Tailwind. Finalmente elegí Tailwind por su enfoque utility-first y excelente integración con Astro.

3. Integración de TypeScript

Configurar TypeScript y sus definiciones de tipos requirió bastante tiempo inicial, pero los beneficios a largo plazo en calidad de código y experiencia de desarrollo lo hicieron valer la pena.

Despliegue

El portfolio está desplegado en Netlify, aprovechando sus ventajas:

Despliegue continuo desde Git
HTTPS automático
CDN global

Lecciones Aprendidas

Empezar Simple: Comenzar con funcionalidades core y añadir complejidad gradualmente
La Documentación es Clave: La documentación de Astro es excelente y fue crucial para el desarrollo
Diseño de Componentes: Pensar cuidadosamente en los límites y reusabilidad de componentes
Rendimiento Primero: Las optimizaciones de rendimiento por defecto de Astro son fantásticas

Mejoras Futuras

Implementar soporte para modo oscuro
Añadir más características interactivas usando islas de React
Integrar un CMS headless para mejor gestión de contenido
Mejorar la optimización SEO

Conclusión

Construir este portfolio con Astro y Tailwind CSS ha sido una excelente experiencia de aprendizaje. La combinación de herramientas y frameworks modernos hizo posible crear un sitio web rápido, mantenible y amigable para el desarrollador.

Preguntas y feedback son siempre bienvenidos en los comentarios.