@oondemand/create-ooncore-front

Scaffold oficial do frontend da fábrica de software oondemand: uma SPA em React 18 + Vite 6 + Chakra UI 3, com TanStack Query/Table, React Hook Form + Zod, roteamento (React Router), data grid, formulários dinâmicos e integração com o backend ooncore.

Este pacote é um gerador de projeto (estilo create-*): ele cria, na sua máquina, um novo frontend já renomeado e pronto para configurar.

Índice

• Pré-requisitos
• Início rápido
• Uso passo a passo
• Regras do slug
• O que o gerador faz
• Estrutura do projeto gerado
• Configuração (.env)
• Executando o projeto
• Conectando ao backend
• Customização para o cliente
• Build e deploy
• Solução de problemas

Pré-requisitos

| Ferramenta | Versão | Observação | |---|---|---| | Node.js | ≥ 16.7 | necessário para o gerador. O Vite 6 recomenda Node 18/20/22. | | npm | ≥ 7 | já vem com o Node. | | Backend ooncore | — | a SPA consome a API do @oondemand/create-ooncore-back. |

Início rápido

# 1. Gerar o projeto (pergunta o slug, ex: unimed)
npm create @oondemand/ooncore-front@latest

# 2. Entrar e instalar
cd projeto-unimed-frontend
npm install

# 3. Configurar ambiente
cp .env.exemple .env      # aponte VITE_API_URL para o backend

# 4. Rodar em desenvolvimento
npm run dev               # abre http://localhost:3001

Uso passo a passo

1. Executar o gerador

De dentro da pasta onde você quer criar o projeto, rode:

npm create @oondemand/ooncore-front@latest

O comando pergunta:

Slug do projeto: unimed

Você também pode passar o slug direto, pulando a pergunta:

npm create @oondemand/ooncore-front@latest unimed

O resultado é uma pasta projeto-unimed-frontend/ no diretório atual.

O gerador aborta se já existir uma pasta com esse nome — ele nunca sobrescreve algo existente.

2. Instalar dependências

cd projeto-unimed-frontend
npm install

3. Criar o .env

cp .env.exemple .env

Ajuste principalmente o VITE_API_URL para a URL do seu backend (veja a tabela de variáveis).

4. Rodar

npm run dev

O Vite sobe o dev server em http://localhost:3001 e abre o navegador automaticamente.

Regras do slug

• Informe apenas o slug (ex: unimed) — sem projeto- e sem -frontend. O gerador monta o nome completo (projeto-unimed-frontend).
• Formato aceito: kebab-case — letras minúsculas, números e hífens. Regex: ^[a-z0-9]+(-[a-z0-9]+)*$.
• Exemplos válidos: unimed, acme, acme-cotacoes.
• Inválidos: Unimed (maiúscula), acme_cotacoes (underscore), acme cotacoes (espaço).

O que o gerador faz

1. Valida o slug e checa se a pasta de destino já existe (aborta se existir).
2. Copia o template do frontend para projeto-<slug>-frontend/.
3. Restaura o .gitignore (publicado como gitignore por uma limitação do npm).
4. Ajusta o package.json → campo name para projeto-<slug>-frontend.
5. Remove o campo "private": true do package.json.
6. Mostra os próximos passos.

O gerador não roda npm install nem cria o .env automaticamente.

Estrutura do projeto gerado

projeto-<slug>-frontend/
├── .env.exemple            # modelo de variáveis (prefixo VITE_)
├── .gitignore
├── .github/workflows/      # pipelines de deploy (homolog/prod)
├── index.html              # ponto de entrada do Vite
├── vite.config.js          # plugins (react, string), porta 3001, build → build/
├── infra/
│   ├── docker/             # Dockerfile.prod
│   └── kubernetes/         # deployment/ingress/service (homolog e prod)
├── public/                 # estáticos (logos, ícones)
├── docs/                   # documentação interna
├── src/
│   ├── main.jsx            # bootstrap React
│   ├── App.jsx             # providers (Chakra, React Query, Router)
│   ├── router.jsx          # definição de rotas
│   ├── config/             # api (axios), env (Zod), react-query
│   ├── pages/              # telas
│   ├── components/         # UI: dataGrid, buildForm, layouts, ui/...
│   ├── hooks/              # hooks (inclui hooks de API com React Query)
│   ├── service/            # chamadas à API por domínio
│   ├── constants/          # constantes
│   ├── styles/             # temas e CSS
│   └── utils/              # formatação, currency, zodHelpers
└── package.json

Configuração (.env)

As variáveis usam o prefixo VITE_ (exigência do Vite para expor ao client). Os defaults são validados via Zod em src/config/env.js.

| Variável | Obrigatória | Padrão | Descrição | |---|---|---|---| | VITE_API_URL | sim | http://localhost:4000 | URL base do backend ooncore. | | VITE_MEUS_APPS_URL | não | https://oondemand.online | Portal/ecossistema oondemand. | | VITE_API_INTEGRACAO_GPT_URL | não | https://api.assistentes-gpt.oondemand.online | Endpoint de integração com assistentes GPT. | | VITE_DOC_CUSTOM_URL | não | https://api.assistentes-gpt.oondemand.online | Base de documentação custom. | | VITE_SERVICE_VERSION | não | 1.0.0 | Versão exibida na aplicação. |

O .env.exemple traz VITE_API_URL, VITE_MEUS_APPS_URL e VITE_API_INTEGRACAO_GPT_URL. As demais têm default no env.js.

Executando o projeto

| Comando | O que faz | |---|---| | npm run dev | Dev server do Vite em http://localhost:3001 (abre o navegador). | | npm run build | Build de produção em build/. | | npm run preview | Servidor local para inspecionar o build de produção. | | npm run release | Bump de versão + changelog (release-it). |

Conectando ao backend

1. Suba o backend (@oondemand/create-ooncore-back) — por padrão em http://localhost:4000.
2. No frontend, ajuste VITE_API_URL no .env para essa URL.
3. Rode npm run dev.

As chamadas HTTP ficam centralizadas em src/config/api.js (instância axios) e organizadas por domínio em src/service/.

Customização para o cliente

O gerador faz apenas o scaffold mínimo (renomear o pacote). O rebrand (título do navegador em index.html, texto da sidebar em src/components/_layouts/auth/index.jsx, logo em public/) e a configuração de menus/módulos (src/components/_layouts/auth/menu.jsx + src/router.jsx) são feitos depois, dentro do projeto gerado, seguindo o documento config_default.md da fábrica oondemand.

Build e deploy

npm run build      # gera a pasta build/
npm run preview    # confere o resultado localmente

O projeto inclui:

• infra/docker/Dockerfile.prod — imagem de produção (serve o build).
• infra/kubernetes/ — manifests de deployment, ingress e service (homolog e prod).
• .github/workflows/deploy.yml e deploy-homolog.yml — pipelines de CI/CD.

Esses arquivos vêm do boilerplate e devem ser ajustados (nomes de imagem, hosts, secrets) para a infraestrutura do cliente.

A pasta de saída do build é build/ (definido em vite.config.js), e não a dist/ padrão do Vite.

Solução de problemas

| Sintoma | Causa provável | Solução | |---|---|---| | The directory ... já existe. Abortando. | Já existe projeto-<slug>-frontend | Use outro slug ou remova/renomeie a pasta. | | Tela em branco / erros de rede | VITE_API_URL errado ou backend fora do ar | Ajuste o .env e suba o backend. | | Erro de validação de env na inicialização | URL inválida no .env (o env.js valida com Zod) | Garanta URLs completas (http://...). | | Porta 3001 ocupada | Outro processo usando a porta | Libere a porta ou ajuste server.port em vite.config.js. | | npm create baixa versão antiga | Cache do npm | Use @latest ou fixe a versão. |

Versão e manutenção

Pacote escopado público na org oondemand. Para publicar novas versões deste gerador, consulte o runbook em project-scopes/npm_core.md (inclui o passo de OTP/2FA do npm).

Licença

Veja template/LICENSE-ODR-NC-v1.0.md.