@be-enlighten/enspace-sdk-nuxt

Módulo Nuxt 4 para o @be-enlighten/enspace-sdk-vue + @be-enlighten/enspace-sdk-core. Lê a config de nuxt.config.ts e:

1. Instala o EnspacePlugin no client runtime (plugin.client.ts).
2. Expõe a config via useRuntimeConfig().public.enspace (sem expor no server).
3. Auto-importa os composables: useEnspace, useEnspaceQuery, useEnspaceMutation, useEnspaceScoped.

SSR-safety: o módulo não instala nada no server runtime. Auth secret (API key, Keycloak credentials) não deve aparecer em SSR. Para SSR seguro (e.g. mapear sessão Keycloak → Bearer), use um módulo en-auth-server dedicado (futuro).

Instalação

pnpm add @be-enlighten/enspace-sdk-nuxt

Peer dependencies: nuxt@^4.0, vue@^3.5.

Setup

1. Registre o módulo

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@be-enlighten/enspace-sdk-nuxt'],
  enspace: {
    baseUrl: process.env.ENSPACE_BASE_URL ?? 'http://localhost:1337',
    auth: {
      type: 'api-key',
      key: process.env.ENSPACE_API_KEY ?? 'replace-me',
    },
  },
})

2. Use os composables auto-importados

<!-- app.vue — sem `import` necessário -->
<script setup lang="ts">
const client = useEnspace()
const profile = await client.account.getProfile()
</script>

<template>
  <main>
    <p>Olá, {{ profile.fullName }}</p>
    <p>auth: <code>{{ client.auth.type }}</code></p>
  </main>
</template>

Configuração

EnspaceModuleOptions (em nuxt.config.ts)

Espelha a EnspaceConfig do core:

interface EnspaceModuleOptions extends EnspaceConfig {
  baseUrl: string
  auth: AuthConfig                    // { type: 'api-key' | 'bearer' | 'keycloak', ... }
  workspace?: string
  retry?: RetryConfig
  timeoutMs?: number
}

O módulo declara defaults: { baseUrl: '', auth: { type: 'api-key', key: '' } } internamente, então defu mescla com sua config antes de expor em runtimeConfig.public.enspace.

Keycloak

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@be-enlighten/enspace-sdk-nuxt'],
  enspace: {
    baseUrl: process.env.ENSPACE_BASE_URL!,
    auth: {
      type: 'keycloak',
      url: process.env.KEYCLOAK_URL!,
      realm: process.env.KEYCLOAK_REALM!,
      clientId: process.env.KEYCLOAK_CLIENT_ID!,
      // credentials opcionais — login lazy no primeiro request
      credentials: {
        username: process.env.KEYCLOAK_USER!,
        password: process.env.KEYCLOAK_PASS!,
      },
    },
  },
})

Aviso: credenciais em nuxt.config.ts viram parte de runtimeConfig.public e ficam visíveis no bundle do client. Para produção, prefira login explícito via useEnspace().login({ username, password }) em resposta a um form, e armazene o token no client store (não em config).

Auto-imports

Os composables são auto-importados via addImportsDir(runtime/composables). Não precisa de import explícito:

| Composable | Source | Descrição | |---|---|---| | useEnspace() | @be-enlighten/enspace-sdk-vue | Retorna o EnspaceClient. | | useEnspaceScoped({ workspace }) | @be-enlighten/enspace-sdk-vue | Reage a mudanças de workspace. | | useEnspaceQuery(key, fn) | @be-enlighten/enspace-sdk-vue | Wrapper sobre Pinia Colada useQuery. | | useEnspaceMutation(fn) | @be-enlighten/enspace-sdk-vue | Wrapper sobre Pinia Colada useMutation. |

Para usar fora de auto-import (e.g. em arquivos .ts que não são Vue SFCs), importe explicitamente:

import { useEnspace } from '@be-enlighten/enspace-sdk-nuxt'

Runtime config

O módulo empurra a config mesclada para useRuntimeConfig().public.enspace. O plugin client (runtime/plugin.client.ts) lê esse objeto e instancia o EnspaceClient.

Você pode ler a config em qualquer lugar do client:

const config = useRuntimeConfig().public.enspace
console.log(config.baseUrl, config.auth.type)

Server-side: runtimeConfig.public é acessível no server também, mas o módulo não usa isso no SSR. Não exponha credenciais server-side via runtimeConfig.private aqui — use variáveis de ambiente direto.

Exemplo completo

<!-- pages/dashboard.vue -->
<script setup lang="ts">
import { useEnspaceQuery, useEnspaceMutation } from '#imports' // opcional, auto-import já cobre

const client = useEnspace()

const { state: profile, asyncStatus } = useEnspaceQuery(
  ['profile'],
  c => c.account.getProfile(),
)

const { mutate: createTask } = useEnspaceMutation(
  (c, input: { title: string }) =>
    c.workspaces.workspace('ws_abc').items.create({
      slug: 'contratos',
      data: { title: input.title, done: false },
    }),
)

async function onAdd(title: string) {
  await createTask(title)
}
</script>

<template>
  <section>
    <h1 v-if="profile">Olá, {{ profile.fullName }}</h1>
    <p v-else-if="asyncStatus === 'loading'">Carregando…</p>

    <form @submit.prevent="onAdd(($event.target as HTMLFormElement).title.value)">
      <input name="title" placeholder="Novo Contrato" />
      <button type="submit">Adicionar</button>
    </form>
  </section>
</template>

TypeScript

Os tipos do módulo são expostos via export type { EnspaceModuleOptions } from '@be-enlighten/enspace-sdk-nuxt'. Em projetos Nuxt, nuxt prepare regenera o .nuxt/tsconfig.json com as referências de tipo — se faltar, rode pnpm exec nuxt prepare.

Aliases internos do @be-enlighten/api: a SDK re-exporta Zod schemas do backend que usam aliases internos (@schemas/*, @plugins/*). O Nuxt não conhece esses aliases por padrão. Se aparecerem erros de import em nuxt typecheck, adicione o seguinte no seu nuxt.config.ts (já está no exemplo de examples/nuxt-app):

typescript: {
  tsConfig: {
    compilerOptions: {
      paths: {
        '@schemas/*': ['../../enlighten-api/schemas/*'],
        '@plugins/*': ['../../enlighten-api/plugins/*'],
      },
    },
  },
},

Estrutura interna

packages/nuxt/
├── src/
│   ├── module.ts                       # defineNuxtModule + addPlugin + addImportsDir
│   ├── index.ts                        # public surface (default = module, re-exports)
│   └── runtime/
│       ├── plugin.client.ts            # instala EnspacePlugin no client
│       ├── composables/                # re-exports (auto-importados)
│       ├── nuxt-globals.d.mts          # ambient types p/ tsc standalone
│       └── imports.d.mts               # stub de #imports
├── scripts/copy-runtime.mjs            # postbuild: copia src/runtime → dist/runtime
├── tsup.config.ts                      # build do module.ts + index.ts
└── package.json                        # peer nuxt@^4, vue@^3.5

Licença

MIT.