404 Not Found

404 Not Found


nginx

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


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:

TEXT
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

BASH
# 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

BASH
# 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:

TEXT
# Comando executado com sucesso

(2) ▶Exemplo: Scripts core no package.json

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:

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"
  }
}

4. Convenções de Diretório Core

(1) Visão Geral da Estrutura de Diretórios

100%
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

TEXT
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:

TEXT
Execução Bem-sucedida
⚠️ Nota: ① O prefixo padrão para 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

TYPESCRIPT
// 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:

TEXT
// Execução Bem-sucedida

(2) ▶Exemplo: Estratégia de Renderização routeRules

TYPESCRIPT
// 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:

TEXT
// Execução Bem-sucedida

6. Como Funciona o Mecanismo de Auto-imports

(1) Processo de Registro Automático

100%
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

TYPESCRIPT
// 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:

TEXT
// Execução Bem-sucedida

(2) ▶Exemplo: Validação de Importação Automática de Componentes

VUE
<!-- 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:

TEXT
// Execução Bem-sucedida

7. Exemplo Completo: Inicializando o Projeto MegaShop

BASH
# ============================================
# 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

P Por que os nomes dos componentes no subdiretório components têm um prefixo?
R Por padrão, o Nuxt 3 usa o caminho do diretório como prefixo, então components/product/Card.vue se torna <ProductCard />. Você pode desabilitar isso configurando components: [{ path: '~/components', pathPrefix: false }] no nuxt.config.ts.
P Qual é a diferença entre campos public e private no runtimeConfig?
R Campos privados estão disponíveis apenas no lado do servidor (chave API/senha do banco), enquanto campos públicos são expostos ao cliente. Nunca armazene chaves na seção public.
P O app.vue e o pages/ podem coexistir?
R Sim, mas app.vue deve incluir <NuxtPage /> para renderizar a página. Se não houver diretório pages/, app.vue é a única página.
P Qual é a diferença entre assets e public?
R Arquivos em 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.
P O diretório .nuxt deve ser adicionado ao Git?
R Não. O diretório .nuxt é um diretório temporário gerado automaticamente pelo Nuxt e já está incluído no .gitignore. Executar nuxi prepare ou npm run dev irá regenerá-lo automaticamente.
P O Nuxt 3 suporta a estrutura de diretório src?
R Sim, suporta. Você pode colocar diretórios como pages/ e components/ sob src/, e o Nuxt 3 os reconhecerá automaticamente. Você também pode personalizar isso usando a opção dir no nuxt.config.ts.

📖Resumo


📝Exercícios

  1. Problema Básico (Dificuldade ⭐): Crie um projeto usando nuxi init e desenhe a árvore de diretórios do seu projeto.
  2. 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 para components/shop/product/Card.vue?).
  3. Desafio (Dificuldade: ⭐⭐⭐): Configure o routeRules no nuxt.config.ts para 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.

---|

Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%