Setup do Projeto — Frontend

Pré-requisitos:

Node.js v20 ou superior
npm v10+ (ou pnpm v9+)
Acesso à API backend rodando (local ou remota)

1. Clonar o repositório

git clone <url-do-repositorio>
cd hub-marketplace

2. Instalar dependências

npm install

3. Configurar variáveis de ambiente

Copie o arquivo de exemplo e preencha os valores:

cp .env.example .env.local

Edite .env.local:

# URL da API backend — obrigatória
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# Nome da aplicação (opcional)
NEXT_PUBLIC_APP_NAME=Hub Marketplace

O prefixo NEXT_PUBLIC_ é obrigatório para que a variável seja acessível no browser. Variáveis sem esse prefixo só ficam disponíveis no servidor.

4. Rodar em desenvolvimento

npm run dev

Acesse em http://localhost:3001 (ou a porta disponível).

O backend por padrão sobe na porta 3000. O Next.js tentará a porta 3000 e, se ocupada, usará 3001 automaticamente.

5. Outros comandos

Comando	O que faz
`npm run dev`	Servidor de desenvolvimento com hot reload
`npm run build`	Build de produção
`npm run start`	Serve o build de produção localmente
`npm run lint`	Executa ESLint no projeto

Verificar se está funcionando

Abra http://localhost:3001
Você deve ser redirecionado para /login
Faça login com as credenciais do backend
O dashboard deve carregar sem erros no console

Estrutura de rotas

Rota	Tipo	Descrição
`/login`	Pública	Tela de autenticação
`/dashboard`	Protegida	Painel principal
`/products`	Protegida	Catálogo de produtos
`/inventory`	Protegida	Controle de estoque
`/orders`	Protegida	Gestão de pedidos
`/listings`	Protegida	Anúncios dos marketplaces
`/integrations`	Protegida	Conexões com marketplaces
`/imports`	Protegida	Importação de NF-e

Rotas protegidas redirecionam automaticamente para /login caso o usuário não esteja autenticado.

Dependências principais

Pacote	Versão	Uso
`next`	16.0.7	Framework principal
`react`	19.2.0	Biblioteca de UI
`typescript`	^5	Tipagem estática
`tailwindcss`	^4.1	Estilização utilitária
`@tanstack/react-query`	^5	Cache e fetching de dados
`zustand`	^5	Estado global
`axios`	^1.13	HTTP client
`react-hook-form`	^7	Gerenciamento de formulários
`zod`	^4	Validação de schemas
`@radix-ui/*`	variado	Componentes UI acessíveis
`framer-motion`	^12	Animações
`recharts`	^3	Gráficos
`sonner`	^2	Toast notifications
`lucide-react`	^0.554	Ícones

Troubleshooting

Erro: Failed to fetch / Network Error ao logar

A variável NEXT_PUBLIC_API_URL está incorreta ou o backend não está rodando. Verifique se o backend está acessível na URL configurada.

Porta 3000 já em uso

O Next.js usa automaticamente a próxima porta disponível (ex: 3001). Verifique o terminal — a URL correta é exibida na inicialização. Alternativamente, configure NEXT_PUBLIC_API_URL para apontar para a porta correta do backend.

Tela branca ou loop de redirect

Limpe o cache do Next.js e reinicie:

rm -rf .next
npm run dev

Introdução

Guias Práticos (Manuais)

Para Desenvolvedores

Sistema

Funcional

Setup do Projeto — Frontend

1. Clonar o repositório

2. Instalar dependências

3. Configurar variáveis de ambiente

4. Rodar em desenvolvimento

5. Outros comandos

Verificar se está funcionando

Estrutura de rotas

Dependências principais

Troubleshooting

​1. Clonar o repositório

​2. Instalar dependências

​3. Configurar variáveis de ambiente

​4. Rodar em desenvolvimento

​5. Outros comandos

​Verificar se está funcionando

​Estrutura de rotas

​Dependências principais

​Troubleshooting

1. Clonar o repositório

2. Instalar dependências

3. Configurar variáveis de ambiente

4. Rodar em desenvolvimento

5. Outros comandos

Verificar se está funcionando

Estrutura de rotas

Dependências principais

Troubleshooting