Diretrizes de Desenvolvimento Frontend
Propósito
Guia abrangente para o desenvolvimento moderno com Next.js 15 e React 19, enfatizando Server Components, Client Components, padrões do App Router, componentes Shadcn/ui, organização adequada de arquivos e otimização de desempenho.
Quando Usar Este Skill
- Criar novos componentes ou páginas
- Construir novas funcionalidades
- Buscar dados (Server Components, Server Actions)
- Configurar roteamento com Next.js App Router
- Estilizar componentes com Tailwind CSS e Shadcn/ui
- Otimização de desempenho
- Organizar código frontend
- Boas práticas TypeScript
Início Rápido
Lista de Verificação para Novo Componente
Criando um componente? Siga esta lista:
- Determinar Server vs Client Component (padrão: Server Component)
- Adicionar diretiva
"use client"somente se necessário (interatividade, hooks, APIs do navegador) - Usar TypeScript com tipos de props explícitos
- Importar componentes Shadcn/ui de
@/components/ui - Usar classes Tailwind CSS para estilização
- Usar aliases de importação:
@/components,@/lib,@/hooks - Usar utilitário
cn()para classes condicionais - Exportação padrão no final
- Usar Server Components para busca de dados quando possível
Lista de Verificação para Nova Página
Criando uma página? Configure esta estrutura:
- Criar
app/{nome-da-rota}/page.tsxpara a rota - Usar Server Component por padrão
- Buscar dados diretamente no Server Component
- Criar diretório
components/para componentes específicos da página - Usar
loading.tsxpara estados de carregamento - Usar
error.tsxpara limites de erro - Exportar metadados para SEO
Referência Rápida de Aliases de Importação
| Alias | Resolve Para | Exemplo |
|---|---|---|
@/ | Raiz do projeto | 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 em: configuração de paths em tsconfig.json
Folha de Dicas de Importações Comuns
// Next.js
import { Metadata } from 'next'
import { Suspense } from 'react'
import { notFound, redirect } from 'next/navigation'
// React (apenas 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'
// Utilitários
import { cn } from '@/lib/utils'
// Hooks (apenas Client Components)
import { useMobile } from '@/hooks/use-mobile'
// Tipos
import type { ComponentProps } from 'react'
Guias por Tópico
🎨 Padrões de Componentes
Server Components vs Client Components:
- Server Components (padrão): Sem
"use client", podem buscar dados diretamente, bundle menor - Client Components: Adicione
"use client"para interatividade, hooks, APIs do navegador
Conceitos-chave:
- Padrão: Server Components
- Use Client Components apenas quando necessário
- Use componentes Shadcn/ui (já são Client Components)
- Estrutura do componente: Props → Busca de Dados → Renderização → Exportação
Exemplo 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>
)
}
Exemplo 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>
)
}
📊 Busca de Dados
PADRÃO PRIMÁRIO: Server Components
- Busque dados diretamente em Server Components
- Use
async/awaitem Server Components - Não precisa de
useEffectou bibliotecas de busca de dados - Deduplicação automática de requisições
Server Actions:
- Use para mutações (formulários, atualizações)
- Crie diretório
app/actions/ - Marque com diretiva
"use server"
Exemplo de Server Component com Busca de Dados:
// app/posts/page.tsx
import { PostList } from '@/components/PostList'
async function getPosts() {
const res = await fetch('https://api.example.com/posts', {
cache: 'no-store', // ou 'force-cache', 'revalidate'
})
return res.json()
}
export default async function PostsPage() {
const posts = await getPosts()
return <PostList posts={posts} />
}
Exemplo de Server Action:
// app/actions/posts.ts
'use server'
export async function createPost(formData: FormData) {
const title = formData.get('title')
// ... lógica de validação e criação
redirect('/posts')
}
📁 Organização de Arquivos
Estrutura do App Router:
app/
(routes)/
page.tsx # Página da rota
layout.tsx # Layout da rota
loading.tsx # UI de carregamento
error.tsx # UI de erro
components/ # Componentes compartilhados
ui/ # Componentes Shadcn/ui
features/ # Código específico de funcionalidades
posts/
components/ # Componentes da funcionalidade
actions/ # Server Actions
types/ # Tipos TypeScript
lib/
utils.ts # Utilitários (cn, etc.)
hooks/
use-mobile.ts # Hooks customizados (apenas Client)
Organização por Funcionalidade:
app/features/{funcionalidade}/: Páginas/rotas específicas da funcionalidadecomponents/: Componentes verdadeiramente reutilizáveiscomponents/ui/: Componentes Shadcn/ui (não modifique diretamente)
🎨 Estilização
Tailwind CSS + Shadcn/ui:
- Use classes utilitárias do Tailwind
- Use utilitário
cn()para classes condicionais - Componentes Shadcn/ui usam variáveis CSS para temas
- Personalize tema em
app/globals.css
Padrões de Estilização:
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,
)}
>
Clique aqui
</button>
)
}
Componentes Shadcn/ui:
- Importe de
@/components/ui/{nome-do-componente} - Componentes já são estilizados e acessíveis
- Personalize via prop
classNameou variáveis CSS
🛣️ Roteamento
Next.js App Router - Baseado em Arquivos:
- Diretório:
app/{nome-da-rota}/page.tsx - Rotas aninhadas:
app/{pai}/{filho}/page.tsx - Rotas dinâmicas:
app/posts/[id]/page.tsx - Grupos de rotas:
app/(marketing)/about/page.tsx
Exemplo de Rota:
// app/posts/page.tsx
import { Metadata } from 'next'
import { PostList } from '@/components/PostList'
export const metadata: Metadata = {
title: 'Posts',
description: 'Lista de todos os 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>
)
}
Rota 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 Carregamento e Erro
Estados de Carregamento:
- Crie
loading.tsxno diretório da rota - Automaticamente encapsula a página em Suspense
- Use para carregamento no nível da rota
Limites de Erro:
- Crie
error.tsxno diretório da rota - Automaticamente captura erros na rota
- Pode redefinir o estado de erro
Exemplo de UI de Carregamento:
// 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>
)
}
Exemplo de UI de Erro:
// 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 deu errado!</h2>
<Button onClick={reset}>Tentar novamente</Button>
</div>
)
}
⚡ Desempenho
Padrões de Otimização:
- Use Server Components (bundle menor)
- Use
next/imagepara imagens - Use
next/fontpara fontes - Carregue Client Components de forma lazy quando possível
- Use
useMemoeuseCallbackem Client Components - Transmita dados com limites de Suspense
Otimização de Imagens:
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'
/>
)
}
Streaming com 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
Padrões:
- Modo estrito ativado
- Sem tipo
any - Tipos de retorno explícitos em funções
- Importações de tipos:
import type { Post } from '@/types/post' - Interfaces de props de componentes com JSDoc
Exemplo:
import type { ComponentProps } from 'react'
import { Button } from '@/components/ui/button'
/**
* Componente de botão personalizado com estado de carregamento
*/
interface CustomButtonProps extends ComponentProps<typeof Button> {
isLoading?: boolean
}
export function CustomButton({
isLoading,
children,
...props
}: CustomButtonProps) {
return (
<Button disabled={isLoading} {...props}>
{isLoading ? 'Carregando...' : children}
</Button>
)
}
🔧 Padrões Comuns
Manipulação de Formulários:
- Use Server Actions para envios de formulários
- Use
react-hook-formcomzodpara validação (Client Components) - Use componentes de Formulário Shadcn/ui
Exemplo de Formulário com 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 criação do post
redirect('/posts')
}
Metadados:
import { Metadata } from 'next'
export const metadata: Metadata = {
title: 'Posts',
description: 'Lista de todos os posts',
openGraph: {
title: 'Posts',
description: 'Lista de todos os posts',
},
}
Princípios Fundamentais
- Server Components Primeiro: Padrão: Server Components, use Client Components apenas quando necessário
- Estrutura do App Router: Use roteamento baseado em arquivos com diretório
app/ - Componentes Shadcn/ui: Use componentes pré-construídos e acessíveis
- Tailwind CSS: Estilização utilitária com auxiliar
cn() - TypeScript Estrito: Sem
any, tipos explícitos - Desempenho: Use Server Components, otimize imagens, carregue de forma lazy quando necessário
- Organização de Arquivos: Funcionalidades em
app/features/, compartilhados emcomponents/ - Aliases de Importação: Use prefixo
@/para importações limpas
Referência Rápida: Estrutura de Arquivos
app/
layout.tsx # Layout raiz
page.tsx # Página inicial
globals.css # Estilos globais
(routes)/
posts/
page.tsx # Página de lista de posts
[id]/
page.tsx # Página de detalhes do post
loading.tsx # UI de carregamento
error.tsx # UI de erro
features/
posts/
components/
PostList.tsx # Componentes da funcionalidade
actions/
posts.ts # Server Actions
components/
ui/ # Componentes Shadcn/ui
button.tsx
card.tsx
lib/
utils.ts # Utilitários (cn, etc.)
hooks/
use-mobile.ts # Hooks customizados
Template de Componente Moderno (Cópia 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>
)
}