> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domsoftware.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup do Projeto — Frontend

> Como configurar e rodar o frontend OmniDom localmente do zero.

<Info>
  **Pré-requisitos:**

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

## 1. Clonar o repositório

```bash theme={null}
git clone <url-do-repositorio>
cd hub-marketplace
```

## 2. Instalar dependências

```bash theme={null}
npm install
```

## 3. Configurar variáveis de ambiente

Copie o arquivo de exemplo e preencha os valores:

```bash theme={null}
cp .env.example .env.local
```

Edite `.env.local`:

```env theme={null}
# 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
```

<Warning>
  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.
</Warning>

## 4. Rodar em desenvolvimento

```bash theme={null}
npm run dev
```

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

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

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

1. Abra [http://localhost:3001](http://localhost:3001)
2. Você deve ser redirecionado para `/login`
3. Faça login com as credenciais do backend
4. 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Erro 401 em todas as requisições após login">
    O cookie de `refreshToken` não está sendo enviado. Verifique se o backend está configurado com `CORS` permitindo `credentials: true` para a origem do frontend.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Tela branca ou loop de redirect">
    Limpe o cache do Next.js e reinicie:

    ```bash theme={null}
    rm -rf .next
    npm run dev
    ```
  </Accordion>
</AccordionGroup>