#Estrutura do projeto e stack técnica

A maior parte do desenvolvimento diário pode ficar por conta da IA. Ainda assim, conhecer a estrutura do template permite saber se a IA colocou o código no lugar certo e facilita localizar problemas.

#Stack técnica

O template de Portal é baseado em @nocobase/portal-template-default, com código-fonte em nocobase/portal-template-default.

Essa combinação é a stack de frontend que a IA melhor conhece hoje, o que torna mais preciso o que ela escreve.

O Portal é por enquanto um projeto puramente de frontend, com a lógica de negócio resolvida pela API do NocoBase, pelos componentes padrão e assim por diante. O suporte para o AI Agent também escrever o backend do Portal está a caminho.

#Estrutura de diretórios

src/
├── app/            Rotas e carregamento de extensões
├── pages/          Login, cadastro, esqueci a senha e afins
├── components/     Componentes
│   ├── ui/         Base de componentes shadcn/ui
│   ├── app-shell/  Layout, navegação, estados de carregamento
│   ├── auth/       Componentes de autenticação
│   └── ...
├── extensions/     Extensões, ativas assim que instaladas
├── lib/            Wrapper do cliente NocoBase e lógica de ACL
├── providers/      Providers do Refine
├── hooks/          Hooks customizados
└── locales/        Textos localizados

Alguns pontos importantes:

• src/app/routes.tsx — Estrutura de rotas. As rotas autenticadas e não autenticadas ficam separadas, e as rotas fornecidas por extensões são montadas automaticamente
• src/app/extensions.tsx — Carregamento de extensões, usando import.meta.glob para varrer src/extensions/*/extension.tsx
• src/providers/data.ts — O data provider do Refine, que traduz a sintaxe de consulta do Refine em parâmetros da API do NocoBase
• src/lib/nocobase/client.ts — NocoBaseClient, o wrapper de baixo nível por trás de toda requisição
• src/components/ui/ — Mais de 60 componentes shadcn/ui, prontos para uso

As páginas de negócio normalmente ficam em src/extensions/, um diretório por módulo funcional. Veja Componentes padrão e extensões.

#Arquivos importantes

#Variáveis de ambiente

O nb portal dev e o nb portal deploy escrevem essas variáveis para você, então normalmente não é preciso mexer nelas. As três últimas só precisam ser alinhadas quando o servidor customizou a forma de armazenar os tokens de autenticação.

Durante o desenvolvimento, se NOCOBASE_API_URL for um endereço absoluto, o Vite monta um proxy para encaminhar as requisições, então você não precisa lidar com CORS.

#Comandos mais usados

São estes os comandos do dia a dia. Instalação de dependências, atualização das variáveis de ambiente e builds ficam todos por conta da CLI nos bastidores:

Para os parâmetros completos de cada comando, veja a Referência do comando nb portal.

#Onde fica o workspace de desenvolvimento

O workspace de desenvolvimento de um Portal vai para o diretório em que você estava quando executou nb portal create ou nb portal pull:

./<portal>

Você pode apontar para outro lugar com --path na criação ou no pull. Os artefatos de deploy compilados vão para outro lugar — sob o storage da aplicação de destino, mantidos em sincronia pelo nb portal deploy, e não são algo com que você lide normalmente.

Se você não tem certeza de onde fica o workspace de desenvolvimento de um Portal, basta consultar:

nb portal info main

#Links relacionados

• Início rápido do AI Portal — Coloque no ar a sua primeira entrada de frontend escrita pela IA
• Componentes padrão e extensões — A base de componentes shadcn/ui e o mecanismo de extensão
• Deploy e gerenciamento de código-fonte — O fluxo de build e deploy, e o source storage
• Construção com AI Agent — Conduza a IA em linguagem natural para escrever páginas
• nb portal info — Veja onde fica o workspace de desenvolvimento de um Portal