Instalação e Estrutura do Projeto
Alice quer executar a MegaShop localmente, mas está confusa com as convenções de diretório do Nuxt 3—se os arquivos forem colocados no local errado, os componentes não serão importados automaticamente. O projeto do Bob tem uma configuração bagunçada, causando problemas a cada build. Charlie precisa de uma estrutura de diretório clara para padronizar o desenvolvimento da equipe.
1. O Que Você Vai Aprender
- npx nuxi@latest init: Criar um projeto e selecionar um gerenciador de pacotes
- Convenções de diretório core: pages/components/composables/server, etc.
- Explicação Detalhada do nuxt.config.ts
- Como Funciona o Auto-imports
- Guia Prático de Inicialização do Projeto MegaShop
2. Uma História Real de um Desenvolvedor
(1) Dor: Uma estrutura de diretório desorganizada faz componentes "desaparecerem"
Alice colocou ProductCard.vue sob src/components/shop/, o que resultou em um erro na página: "Component ProductCard is not found." Ela não conhecia as convenções de diretório do Nuxt 3—o caminho do componente determina o nome do componente. components/shop/ProductCard.vue deveria ser referenciado como `<ShopProductCard />`. Essa regra implícita frequentemente confunde iniciantes.
(2) Solução com a Convenção de Diretório do Nuxt 3
O Nuxt 3 usa convenções de diretório em vez de configuração manual—os arquivos ficam automaticamente disponíveis quando colocados no diretório correto, sem necessidade de declarações import. Uma vez que ela entende as convenções, Alice só precisa organizar seus arquivos de acordo com as regras:
components/
ProductCard.vue → <ProductCard />
shop/
ProductList.vue → <ShopProductList />
(3) Benefícios: Duplicando a Eficiência de Desenvolvimento
Após a equipe entender as convenções de diretório, os componentes da Alice não "desapareceram" mais, e o tempo para novos membros da equipe se adaptarem caiu de 2 dias para 4 horas.
3. Criando um Projeto Nuxt 3
(1) Comando de Inicialização
# Criar novo projeto Nuxt 3
npx nuxi@latest init megashop
# Ou com gerenciador de pacotes específico
npx nuxi@latest init megashop --packageManager pnpm
(2) Comparação de Gerenciadores de Pacotes
| Dimensão | npm | pnpm | yarn |
|---|---|---|---|
| Velocidade de Instalação | 🐢 Lento | ⚡ Mais Rápido | ⚡ Rápido |
| Uso de Disco | 🔴 Alto | 🟢 Baixo (hard links) | 🟡 Médio |
| Monorepo | ⚠️ Requer workspaces | ✅ Suporte nativo | ✅ Suportado |
| Avaliação | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
(1) ▶Exemplo: Inicialização e Inicialização
# Passo 1: Criar projeto
npx nuxi@latest init megashop
# Passo 2: Entrar no diretório do projeto
cd megashop
# Passo 3: Instalar dependências
npm install
# Passo 4: Iniciar servidor de desenvolvimento
npm run dev
# → Servidor dev do Nuxt rodando em http://localhost:3000
Saída:
# Comando executado com sucesso
(2) ▶Exemplo: Scripts core no package.json
{
"name": "megashop",
"private": true,
"scripts": {
"build": "nuxi build",
"dev": "nuxi dev",
"generate": "nuxi generate",
"preview": "nuxi preview",
"postinstall": "nuxi prepare"
},
"dependencies": {
"nuxt": "^3.12.0"
},
"devDependencies": {
"@nuxt/devtools": "latest"
}
}
Saída:
{
"name": "megashop",
"private": true,
"scripts": {
"build": "nuxi build",
"dev": "nuxi dev",
"generate": "nuxi generate",
"preview": "nuxi preview",
"postinstall": "nuxi prepare"
},
"dependencies": {
"nuxt": "^3.12.0"
},
"devDependencies": {
"@nuxt/devtools": "latest"
}
}
4. Convenções de Diretório Core
(1) Visão Geral da Estrutura de Diretórios
graph TB
A[megashop/] --> B[pages/ → Rotas]
A --> C[components/ → Auto-import Componentes]
A --> D[composables/ → Auto-import Funções]
A --> E[server/ → Rotas API]
A --> F[layouts/ → Layouts de Página]
A --> G[plugins/ → Auto-registro de Plugins]
A --> H[middleware/ → Guardas de Rota]
A --> I[assets/ → Processado pelo Build]
A --> J[public/ → Arquivos Estáticos]
A --> K[nuxt.config.ts → Config do Projeto]
A --> L[app.vue → Componente Raiz]
(2) Responsabilidades e Regras de Cada Diretório
| Diretório | Responsabilidades | Registro Automático | Usos na MegaShop |
|---|---|---|---|
| pages/ | Páginas de Rotas | ✅ Auto-Gerar Rotas | Páginas de Produtos/Páginas de Categorias/Home |
| components/ | Componente Vue | ✅ Auto-import | ProductCard/Header/Footer |
| composables/ | Funções composable | ✅ Auto-import | useCart/useProduct |
| server/api/ | Rotas API | ✅ Auto-registro | /api/products /api/cart |
| server/middleware/ | Middleware do lado do servidor | ✅ Aplica globalmente | auth/CORS |
| layouts/ | Layout de Página | ✅ Auto-Registro | default/sidebar |
| plugins/ | Plugins | ✅ Automatizado | stripe/payment |
| middleware/ | Middleware de roteamento | ✅ Pode ser referenciado | auth/admin |
| assets/ | Recursos de build e processamento | ❌ Requer referência | CSS/Fontes/SCSS |
| public/ | Arquivos estáticos | ❌ Acesso direto | favicon/robots.txt |
(1) ▶Exemplo: Estrutura de Diretório da MegaShop
megashop/
├── app.vue # Componente raiz
├── nuxt.config.ts # Config do projeto
├── pages/
│ ├── index.vue # Homepage
│ ├── products/
│ │ ├── index.vue # Lista de produtos
│ │ └── [id].vue # Detalhe do produto
│ ├── categories/
│ │ └── [slug].vue # Página de categoria
│ ├── cart.vue # Carrinho de compras
│ └── about.vue # Página Sobre
├── components/
│ ├── AppHeader.vue # → <AppHeader />
│ ├── AppFooter.vue # → <AppFooter />
│ └── product/
│ ├── ProductCard.vue # → <ProductProductCard /> ①
│ └── ProductList.vue # → <ProductProductList /> ①
├── composables/
│ ├── useCart.ts # → auto-importado
│ └── usePriceFormat.ts # → auto-importado
├── server/
│ └── api/
│ ├── products/
│ │ └── index.get.ts # GET /api/products
│ └── cart/
│ └── index.post.ts # POST /api/cart
├── layouts/
│ ├── default.vue # Layout padrão
│ └── sidebar.vue # Layout com sidebar
├── middleware/
│ └── auth.ts # Middleware nomeado
├── plugins/
│ └── stripe.client.ts # Plugin apenas no cliente
├── assets/
│ └── css/
│ └── main.css # Estilos globais
└── public/
├── favicon.ico
└── robots.txt
Saída:
Execução Bem-sucedida
components/product/ProductCard.vue é Product, ou seja, <ProductProductCard />. Você pode desabilitar o prefixo configurando pathPrefix no nuxt.config.ts.
5. Explicação Detalhada do nuxt.config.ts
(1) Opções de Configuração Core
| Opção | Tipo | Descrição | Exemplo MegaShop |
|---|---|---|---|
| ssr | boolean | Toggle SSR Global | true |
| modules | array | Lista de Módulos | @pinia/nuxt |
| runtimeConfig | object | Configuração de Runtime | Chave API/URL do Banco |
| app | object | Metadados do app | head/title/templateId |
| vite | object | Configuração do Vite | Proxies/Plugins |
| routeRules | object | Política de renderização por rota | ISR/CSR/Cache |
| components | object | Configuração de Import de Componentes | Prefixo/Caminho de Scan |
(1) ▶Exemplo: Configuração Básica da MegaShop
// nuxt.config.ts
export default defineNuxtConfig({
// Configuração SSR global
ssr: true,
// Metadados do app
app: {
head: {
title: 'MegaShop - E-Commerce Premium',
meta: [
{ name: 'description', content: 'Milhões de produtos, entregues mundialmente' }
]
}
},
// Config de runtime (segredos apenas no servidor)
runtimeConfig: {
// Privado - apenas servidor
databaseUrl: process.env.DATABASE_URL,
stripeSecretKey: process.env.STRIPE_SECRET_KEY,
// Público - exposto ao cliente
public: {
apiBase: process.env.API_BASE || 'http://localhost:3000/api',
stripePublishableKey: process.env.STRIPE_PUBLISHABLE_KEY
}
},
// Módulos
modules: [
'@pinia/nuxt',
'@nuxtjs/tailwindcss'
],
// Configuração de prefixo de caminho de componentes
components: [
{ path: '~/components', pathPrefix: false }
]
})
Saída:
// Execução Bem-sucedida
(2) ▶Exemplo: Estratégia de Renderização routeRules
// nuxt.config.ts - regras de renderização por rota
export default defineNuxtConfig({
routeRules: {
// Homepage: pré-renderizar no momento do build
'/': { prerender: true },
// Lista de produtos: ISR com revalidação de 60s
'/products': { swr: 60 },
// Detalhe do produto: ISR com revalidação de 3600s
'/products/**': { swr: 3600 },
// Painel admin: apenas no cliente
'/admin/**': { ssr: false },
// API: headers CORS
'/api/**': { cors: true }
}
})
Saída:
// Execução Bem-sucedida
6. Como Funciona o Mecanismo de Auto-imports
(1) Processo de Registro Automático
flowchart LR
A[Nuxt Escaneia Diretórios] --> B[Gera .nuxt/imports.d.ts]
B --> C[Gera .nuxt/components.d.ts]
C --> D[Auto-complete TypeScript]
A --> E[Gera .nuxt/routes.ts]
E --> F[Config do Vue Router]
(2) Escopo de Importação Automática
| Tipo | Diretório | Regra de Prefixo | Exemplo |
|---|---|---|---|
| Componente | components/ | Prefixo do caminho do diretório | ProductCard → <ProductCard /> |
| Composable | composables/ | Prefixo use | useCart() → auto-importado |
| Funções Utilitárias | utils/ | Sem prefixo | formatPrice() → auto-importado |
| APIs Integradas | Nuxt 3 Core | Prefixo "use" | useFetch/useState/useRouter |
(1) ▶Exemplo: Importação Automática de Composables
// composables/usePriceFormat.ts
// Não é necessário importar - auto-importado pelo Nuxt
export function usePriceFormat(price: number, currency: string = 'USD'): string {
return new Intl.NumberFormat('en-US', {
style: 'currency',
currency
}).format(price)
}
// Em qualquer componente - usar diretamente
// const formatted = usePriceFormat(2999.99) → "$2,999.99"
Saída:
// Execução Bem-sucedida
(2) ▶Exemplo: Validação de Importação Automática de Componentes
<!-- pages/index.vue -->
<template>
<!-- Todos os componentes auto-importados, sem necessidade de declaração import -->
<div>
<AppHeader />
<ProductCard :product="featured" />
<AppFooter />
</div>
</template>
<script setup lang="ts">
// Todos os composables auto-importados
const { data: featured } = await useFetch('/api/products/featured')
const price = usePriceFormat(featured.value?.price || 0)
</script>
Saída:
// Execução Bem-sucedida
7. Exemplo Completo: Inicializando o Projeto MegaShop
# ============================================
# Inicialização do Projeto MegaShop
# Configuração completa do zero até o servidor dev rodando
# ============================================
# 1. Criar projeto
npx nuxi@latest init megashop
cd megashop
# 2. Instalar dependências core
npm install @pinia/nuxt @nuxtjs/tailwindcss
# 3. Criar estrutura de diretórios
mkdir -p pages/products pages/categories
mkdir -p components/product
mkdir -p composables
mkdir -p server/api/products server/api/cart
mkdir -p layouts
mkdir -p middleware
mkdir -p plugins
mkdir -p assets/css
mkdir -p public
# 4. Inicializar repositório Git
git init
git add .
git commit -m "feat: initialize MegaShop with Nuxt 3"
# 5. Iniciar servidor de desenvolvimento
npm run dev
❓Perguntas Frequentes
components têm um prefixo?components/product/Card.vue se torna <ProductCard />. Você pode desabilitar isso configurando components: [{ path: '~/components', pathPrefix: false }] no nuxt.config.ts.runtimeConfig?public.app.vue e o pages/ podem coexistir?app.vue deve incluir <NuxtPage /> para renderizar a página. Se não houver diretório pages/, app.vue é a única página.assets e public?assets/ são processados pelo Vite (podem ser referenciados, otimizados e hasheados), enquanto arquivos em public/ são copiados como estão para o diretório de saída e podem ser acessados diretamente via URL.nuxi prepare ou npm run dev irá regenerá-lo automaticamente.📖Resumo
- Use
npx nuxi@latest initpara criar um projeto; pnpm é recomendado como gerenciador de pacotes - Diretórios core do Nuxt 3: pages (rotas), components (componentes), composables (funções), server (API), layouts (layouts)
nuxt.config.tsé a configuração core do projeto:runtimeConfiggerencia segredos, erouteRulesgerencia estratégias de renderização- auto-imports elimina a necessidade de importar manualmente componentes, Composables e funções utilitárias
- A estrutura de diretório da MegaShop deve seguir as convenções para garantir que todos os arquivos estejam nos locais corretos.
📝Exercícios
- Problema Básico (Dificuldade ⭐): Crie um projeto usando
nuxi inite desenhe a árvore de diretórios do seu projeto. - Exercício Avançado (Dificuldade: ⭐⭐): Crie um componente com dois níveis de subdiretórios sob
components/para verificar as convenções de nomenclatura usadas durante a importação automática (ex.: qual é o nome da tag paracomponents/shop/product/Card.vue?). - Desafio (Dificuldade: ⭐⭐⭐): Configure o
routeRulesnonuxt.config.tspara que a homepage seja pré-renderizada, a página de produtos use ISR por 60 segundos, e a página admin use CSR, depois verifique se funciona como esperado.
---|



