Docs › Frontend

defineOonApp e bootstrap

O contrato code-first do frontend — defineOonApp valida identidade, API, rotas, navegação e segurança; startOonApp monta providers, autenticação, tenant, shell e router.

O frontend de todo App Oon é composto em TypeScript/React. O appKind não limita páginas, componentes, layouts ou temas locais.

import { defineOonApp, type OonAppKind, type OonTenancyModel } from "@oondemand/oon-core-front";
import manifest from "../../../central.app.json";
import { navigation } from "./navigation";
import { routes } from "./routes";
import { theme } from "./theme";

export const app = defineOonApp({
  app: {
    id: manifest.id,
    name: manifest.name,
    title: manifest.name,
    kind: manifest.appKind as OonAppKind,
    tenancyModel: manifest.tenancyModel as OonTenancyModel,
    capabilities: manifest.capabilities,
  },
  api: {
    baseUrl: import.meta.env.VITE_API_URL ?? "/api",
    meusAppsUrl: import.meta.env.DEV ? undefined : import.meta.env.VITE_MEUS_APPS_URL, // endereço do Meus Apps (não é login)
  },
  runtimeMode: import.meta.env.DEV ? "local" : "platform",
  routes: [...routes],
  navigation: [...navigation],
  theme,
  shell: { shell: "default" },
});

import { startOonApp } from "@oondemand/oon-core-front";
import { app } from "./app/app";

startOonApp(app);

O que startOonApp monta

QueryClient → OonThemeProvider (Chakra) → ApiProvider → ActivationProvider
  → TenantProvider (se tenancyModel ≠ none) → AuthProvider
    → [LocalRuntimeBanner no modo local] → Router

Além disso aplica document.title/favicon, endurece o console em produção (disableConsoleInProduction) e cria o cliente HTTP autenticado.

Referência de defineOonApp

Chave Descrição
app Obrigatório. id, name, title?, logo?, favicon?, version?, kind?, tenancyModel?, capabilities?, capabilitySettings?
api Obrigatório. baseUrl, meusAppsUrl? (endereço do Meus Apps; desde a 0.7.37 não é usado como login), assistantBaseUrl?, onboardingBaseUrl?, versionPrefix?, timeout?
runtimeMode "local" ou "platform"
auth mode?, loginUrl? (login externo; sem ele o App usa a própria tela /login), tokenParam? (padrão code)
routes Rotas da aplicação — veja Rotas e navegação
navigation Itens de menu ou { mode, items }
shell Configuração do shell — veja Shell e layouts
layouts Componentes de slots de layout (ex.: topbarEnd, organization)
components Registry: fieldRenderers, cellRenderers, cardRenderers, actionRenderers, pageComponents, menuRenderers, menuConditions
pages Páginas por blocos declarativos
modules Módulos com rotas, menus e views
ui Composição declarativa opcional (views collection, document, pipeline, dashboard)
theme, themes, defaultThemeId Temas — veja Temas
security Opções de segurança (guards não podem ser desligados)
systemPages login? e usersAccess? (componente ou false)
rootElementId Elemento de montagem (padrão root)

Validações

defineOonApp preserva a inferência de tipos e lança erro quando:

  • app.id, app.name ou api.baseUrl estão ausentes;
  • security.enableRouteGuard ou security.enablePermissionGate são false — guards obrigatórios não podem ser desabilitados;
  • rotas duplicadas, reservadas ou com mais de uma fonte de renderização;
  • itens de navegação sem label ou sem destino.

Subpaths públicos

Import Conteúdo
@oondemand/oon-core-front Tudo: bootstrap, componentes, hooks, tipos
@oondemand/oon-core-front/ui Primitives, kit Core*, componentes de domínio
@oondemand/oon-core-front/routing defineOonRoutes, defineOonNavigation, OON_RESERVED_ROUTES
@oondemand/oon-core-front/theme createOonTheme, oonDefaultTheme, createOonSystem, useOonTheme
@oondemand/oon-core-front/hooks useOonAuth, useOonTenant, useOonApi, useOonResource, useCoreMetadata, useModelSchema, useOonTheme
@oondemand/oon-core-front/testing createOonTestConfig

Limites de segurança

  • nunca desative guards do Core;
  • não carregue código remoto, eval ou Function no bundle;
  • não inclua tokens, chaves ou segredos (import.meta.env.*_TOKEN, *_SECRET…);
  • não importe caminhos internos do pacote;
  • mantenha dependências dentro da árvore de frontend/;
  • use o backend como autoridade de autorização.

Execute npm run ooncore:conformance antes do build e da publicação.