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

```tsx title="frontend/src/app/app.tsx"
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" },
});
```

```tsx title="frontend/src/main.tsx"
import { startOonApp } from "@oondemand/oon-core-front";
import { app } from "./app/app";

startOonApp(app);
```

> [!IMPORTANT]
> `main.tsx` precisa iniciar o Core com `startOonApp`. A conformance reprova bootstraps que montam React, Chakra, QueryClient ou providers manualmente.

## O que `startOonApp` monta

```txt
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](/docs/frontend/rotas-e-navegacao) |
| `navigation` | Itens de menu ou `{ mode, items }` |
| `shell` | Configuração do shell — veja [Shell e layouts](/docs/frontend/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](/docs/frontend/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.

Fonte: https://sdk.oonapps.com/docs/frontend/bootstrap