Guía de Desarrollo Frontend
Propósito
Guía completa para el desarrollo moderno con Next.js 15 y React 19, que enfatiza Server Components, Client Components, patrones de App Router, componentes Shadcn/ui, organización de archivos adecuada y optimización del rendimiento.
Cuándo Usar Este Skill
- Crear nuevos componentes o páginas
- Construir nuevas funcionalidades
- Obtener datos (Server Components, Server Actions)
- Configurar rutas con Next.js App Router
- Dar estilo a componentes con Tailwind CSS y Shadcn/ui
- Optimizar el rendimiento
- Organizar código frontend
- Mejores prácticas de TypeScript
Inicio Rápido
Lista de Verificación para Nuevo Componente
¿Creando un componente? Sigue esta lista:
- Determinar si es Server vs Client Component (por defecto: Server Component)
- Añadir directiva
"use client"solo si es necesario (interactividad, hooks, APIs del navegador) - Usar TypeScript con tipos explícitos en props
- Importar componentes Shadcn/ui desde
@/components/ui - Usar clases de Tailwind CSS para estilos
- Usar alias de importación:
@/components,@/lib,@/hooks - Usar la utilidad
cn()para clases condicionales - Exportar por defecto al final
- Usar Server Components para la obtención de datos siempre que sea posible
Lista de Verificación para Nueva Página
¿Creando una página? Configura esta estructura:
- Crear
app/{nombre-de-ruta}/page.tsxpara la ruta - Usar Server Component por defecto
- Obtener datos directamente en el Server Component
- Crear directorio
components/para componentes específicos de la página - Usar
loading.tsxpara estados de carga - Usar
error.tsxpara límites de error - Exportar metadatos para SEO
Referencia Rápida de Alias de Importación
| Alias | Resuelve a | Ejemplo |
|---|---|---|
@/ | Raíz del proyecto | import { cn } from '@/lib/utils' |
@/components | components/ | import { Button } from '@/components/ui/button' |
@/lib | lib/ | import { cn } from '@/lib/utils' |
@/hooks | hooks/ | import { useMobile } from '@/hooks/use-mobile' |
@/app | app/ | import { Metadata } from 'next' |
Definido en: configuración de paths en tsconfig.json
Chuleta de Importaciones Comunes
// Next.js
import { Metadata } from 'next'
import { Suspense } from 'react'
import { notFound, redirect } from 'next/navigation'
// React (solo Client Components)
;('use client')
import { useState, useCallback, useMemo } from 'react'
// Componentes Shadcn/ui
import { Button } from '@/components/ui/button'
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import { Input } from '@/components/ui/input'
// Utilidades
import { cn } from '@/lib/utils'
// Hooks (solo Client Components)
import { useMobile } from '@/hooks/use-mobile'
// Tipos
import type { ComponentProps } from 'react'
Guías por Tema
🎨 Patrones de Componentes
Server Components vs Client Components:
- Server Components (por defecto): Sin
"use client", pueden obtener datos directamente, bundle más pequeño - Client Components: Añadir
"use client"para interactividad, hooks, APIs del navegador
Conceptos Clave:
- Por defecto usar Server Components
- Solo usar Client Components cuando sea necesario
- Usar componentes Shadcn/ui (ya son Client Components)
- Estructura del componente: Props → Obtención de datos → Renderizado → Exportación
Ejemplo de Server Component:
// app/features/posts/components/PostList.tsx
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
interface PostListProps {
posts: Post[]
}
export function PostList({ posts }: PostListProps) {
return (
<div className='grid gap-4'>
{posts.map((post) => (
<Card key={post.id}>
<CardHeader>
<CardTitle>{post.title}</CardTitle>
</CardHeader>
<CardContent>{post.content}</CardContent>
</Card>
))}
</div>
)
}
Ejemplo de Client Component:
// app/features/posts/components/PostForm.tsx
'use client'
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
export function PostForm() {
const [title, setTitle] = useState('')
return (
<form>
<Input value={title} onChange={(e) => setTitle(e.target.value)} />
<Button type='submit'>Enviar</Button>
</form>
)
}
📊 Obtención de Datos
PATRÓN PRINCIPAL: Server Components
- Obtener datos directamente en Server Components
- Usar
async/awaiten Server Components - No es necesario usar
useEffectni bibliotecas de obtención de datos - Deduplicación automática de solicitudes
Server Actions:
- Usar para mutaciones (formularios, actualizaciones)
- Crear directorio
app/actions/ - Marcar con directiva
"use server"
Ejemplo de Server Component con Obtención de Datos:
// app/posts/page.tsx
import { PostList } from '@/components/PostList'
async function getPosts() {
const res = await fetch('https://api.example.com/posts', {
cache: 'no-store', // o 'force-cache', 'revalidate'
})
return res.json()
}
export default async function PostsPage() {
const posts = await getPosts()
return <PostList posts={posts} />
}
Ejemplo de Server Action:
// app/actions/posts.ts
'use server'
export async function createPost(formData: FormData) {
const title = formData.get('title')
// ... lógica de validación y creación
redirect('/posts')
}
📁 Organización de Archivos
Estructura de App Router:
app/
(rutas)/
page.tsx # Página de ruta
layout.tsx # Layout de ruta
loading.tsx # UI de carga
error.tsx # UI de error
components/ # Componentes compartidos
ui/ # Componentes Shadcn/ui
features/ # Código específico de funcionalidad
posts/
components/ # Componentes de funcionalidad
actions/ # Server Actions
types/ # Tipos TypeScript
lib/
utils.ts # Utilidades (cn, etc.)
hooks/
use-mobile.ts # Hooks personalizados (solo cliente)
Organización por Funcionalidad:
app/features/{funcionalidad}/: Páginas/rutas específicas de funcionalidadcomponents/: Componentes verdaderamente reutilizablescomponents/ui/: Componentes Shadcn/ui (no modificar directamente)
🎨 Estilos
Tailwind CSS + Shadcn/ui:
- Usar clases utilitarias de Tailwind
- Usar la utilidad
cn()para clases condicionales - Los componentes Shadcn/ui usan variables CSS para temas
- Personalizar tema en
app/globals.css
Patrones de Estilo:
import { cn } from '@/lib/utils'
interface ButtonProps {
variant?: 'primary' | 'secondary'
className?: string
}
export function Button({ variant = 'primary', className }: ButtonProps) {
return (
<button
className={cn(
'rounded-md px-4 py-2',
variant === 'primary' && 'bg-primary text-primary-foreground',
variant === 'secondary' && 'bg-secondary text-secondary-foreground',
className,
)}
>
Click me
</button>
)
}
Componentes Shadcn/ui:
- Importar desde
@/components/ui/{nombre-del-componente} - Los componentes ya están estilizados y son accesibles
- Personalizar mediante la prop
classNameo variables CSS
🛣️ Rutas
Next.js App Router - Basado en Archivos:
- Directorio:
app/{nombre-de-ruta}/page.tsx - Rutas anidadas:
app/{padre}/{hijo}/page.tsx - Rutas dinámicas:
app/posts/[id]/page.tsx - Grupos de rutas:
app/(marketing)/about/page.tsx
Ejemplo de Ruta:
// app/posts/page.tsx
import { Metadata } from 'next'
import { PostList } from '@/components/PostList'
export const metadata: Metadata = {
title: 'Posts',
description: 'Lista de todos los posts',
}
export default async function PostsPage() {
const posts = await getPosts()
return (
<div className='container mx-auto py-8'>
<h1 className='text-3xl font-bold mb-6'>Posts</h1>
<PostList posts={posts} />
</div>
)
}
Ruta Dinámica:
// app/posts/[id]/page.tsx
interface PostPageProps {
params: Promise<{ id: string }>
}
export default async function PostPage({ params }: PostPageProps) {
const { id } = await params
const post = await getPost(id)
if (!post) {
notFound()
}
return <PostDetail post={post} />
}
⏳ Estados de Carga y Error
Estados de Carga:
- Crear
loading.tsxen el directorio de la ruta - Automáticamente envuelve la página en Suspense
- Usar para carga a nivel de ruta
Límites de Error:
- Crear
error.tsxen el directorio de la ruta - Captura automáticamente errores en la ruta
- Puede restablecer el estado de error
Ejemplo de UI de Carga:
// app/posts/loading.tsx
export default function Loading() {
return (
<div className='flex items-center justify-center min-h-screen'>
<div className='animate-spin rounded-full h-8 w-8 border-b-2 border-primary' />
</div>
)
}
Ejemplo de UI de Error:
// app/posts/error.tsx
'use client'
import { useEffect } from 'react'
import { Button } from '@/components/ui/button'
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
useEffect(() => {
console.error(error)
}, [error])
return (
<div className='flex flex-col items-center justify-center min-h-screen'>
<h2 className='text-2xl font-bold mb-4'>¡Algo salió mal!</h2>
<Button onClick={reset}>Intentar de nuevo</Button>
</div>
)
}
⚡ Rendimiento
Patrones de Optimización:
- Usar Server Components (bundle más pequeño)
- Usar
next/imagepara imágenes - Usar
next/fontpara fuentes - Cargar Client Components de forma diferida cuando sea posible
- Usar
useMemoyuseCallbacken Client Components - Transmitir datos con límites de Suspense
Optimización de Imágenes:
import Image from 'next/image'
export function Avatar({ src, alt }: { src: string; alt: string }) {
return (
<Image
src={src}
alt={alt}
width={40}
height={40}
className='rounded-full'
/>
)
}
Transmisión con Suspense:
import { Suspense } from 'react'
import { PostList } from '@/components/PostList'
import { Loading } from '@/components/Loading'
export default function Page() {
return (
<div>
<Suspense fallback={<Loading />}>
<PostList />
</Suspense>
</div>
)
}
📘 TypeScript
Estándares:
- Modo estricto activado
- Sin tipo
any - Tipos de retorno explícitos en funciones
- Importaciones de tipos:
import type { Post } from '@/types/post' - Interfaces de props de componentes con JSDoc
Ejemplo:
import type { ComponentProps } from 'react'
import { Button } from '@/components/ui/button'
/**
* Componente de botón personalizado con estado de carga
*/
interface CustomButtonProps extends ComponentProps<typeof Button> {
isLoading?: boolean
}
export function CustomButton({
isLoading,
children,
...props
}: CustomButtonProps) {
return (
<Button disabled={isLoading} {...props}>
{isLoading ? 'Cargando...' : children}
</Button>
)
}
🔧 Patrones Comunes
Manejo de Formularios:
- Usar Server Actions para envíos de formularios
- Usar
react-hook-formconzodpara validación (Client Components) - Usar componentes de formulario de Shadcn/ui
Ejemplo de Formulario con Server Action:
// app/actions/posts.ts
'use server'
import { z } from 'zod'
const createPostSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
})
export async function createPost(formData: FormData) {
const rawData = {
title: formData.get('title'),
content: formData.get('content'),
}
const validated = createPostSchema.parse(rawData)
// ... lógica de creación del post
redirect('/posts')
}
Metadatos:
import { Metadata } from 'next'
export const metadata: Metadata = {
title: 'Posts',
description: 'Lista de todos los posts',
openGraph: {
title: 'Posts',
description: 'Lista de todos los posts',
},
}
Principios Fundamentales
- Server Components Primero: Por defecto usar Server Components, usar Client Components solo cuando sea necesario
- Estructura de App Router: Usar enrutamiento basado en archivos con el directorio
app/ - Componentes Shadcn/ui: Usar componentes preconstruidos y accesibles
- Tailwind CSS: Estilo utilitario con el helper
cn() - TypeScript Estricto: Sin
any, tipos explícitos - Rendimiento: Usar Server Components, optimizar imágenes, cargar de forma diferida cuando sea necesario
- Organización de Archivos: Funcionalidades en
app/features/, compartidos encomponents/ - Alias de Importación: Usar el prefijo
@/para importaciones limpias
Referencia Rápida: Estructura de Archivos
app/
layout.tsx # Layout raíz
page.tsx # Página de inicio
globals.css # Estilos globales
(rutas)/
posts/
page.tsx # Página de lista de posts
[id]/
page.tsx # Página de detalle de post
loading.tsx # UI de carga
error.tsx # UI de error
features/
posts/
components/
PostList.tsx # Componentes de funcionalidad
actions/
posts.ts # Server Actions
components/
ui/ # Componentes Shadcn/ui
button.tsx
card.tsx
lib/
utils.ts # Utilidades (cn, etc.)
hooks/
use-mobile.ts # Hooks personalizados
Plantilla de Componente Moderno (Copia Rápida)
Server Component:
// app/components/PostCard.tsx
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import type { Post } from '@/types/post'
interface PostCardProps {
post: Post
}
export function PostCard({ post }: PostCardProps) {
return (
<Card>
<CardHeader>
<CardTitle>{post.title}</CardTitle>
</CardHeader>
<CardContent>
<p>{post.content}</p>
</CardContent>
</Card>
)
}
Client Component:
// app/components/PostForm.tsx
'use client'
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
export function PostForm() {
const [title, setTitle] = useState('')
return (
<form>
<Input value={title} onChange={(e) => setTitle(e.target.value)} />
<Button type='submit'>Enviar</Button>
</form>
)
}
Mejores Prácticas Generales
- Priorizar Server Components para reducir el tamaño del bundle del lado del cliente.
- Usar Server Actions para la lógica de mutación en lugar de manejadores de eventos del lado del cliente.
- Organizar por funcionalidad (
app/features/) en lugar de por tipo técnico. - Mantener los componentes pequeños y enfocados en una única responsabilidad.
- Usar los componentes Shadcn/ui como base y personalizar con la prop
classNameo variables CSS. - Añadir estados de carga y error a cada página usando
loading.tsxyerror.tsx. - Exportar metadatos para cada página para mejorar SEO.
- Usar TypeScript con tipos estrictos y sin tipo
any. - Usar la utilidad
cn()para combinar clases de Tailwind CSS condicionalmente. - Aprovechar
next/imagepara la optimización automática de imágenes.