Mitra Feature Flags SDK React

SDK para carregar feature flags em aplicações React da Mitra e avaliá-las localmente. Cada frontend informa seu serviceName, recebe somente flags cujo serviceNames contém explicitamente esse frontend e mantém o último snapshot válido em memória e no localStorage.

Instalação

npm install @mitralab.io/feature-flags-sdk-react

Provider

import { FeatureFlagsProvider } from "@mitralab.io/feature-flags-sdk-react"
import { useCallback } from "react"

export function AppProviders({ children }: { children: React.ReactNode }) {
  const { getAccessToken } = useAuth()
  const tokenProvider = useCallback(() => getAccessToken(), [getAccessToken])

  return (
    <FeatureFlagsProvider
      serviceName="mitra-web"
      tokenProvider={tokenProvider}
      baseUrl={import.meta.env.VITE_API_URL}
    >
      {children}
    </FeatureFlagsProvider>
  )
}

O tokenProvider pode retornar o JWT atual de forma síncrona ou assíncrona. Mantenha a função estável com useCallback, pois uma nova referência recria o client e reinicia o polling. O endpoint de snapshot é autenticado e o ambiente é definido pelo backend, então o frontend não envia environment nem secret interno. O serviceName usa lower kebab case e aceita até 100 caracteres.

Flags e Hooks

import {
  booleanFlag,
  stringListFlag,
  useBooleanFlag,
  useStringListFlag,
} from "@mitralab.io/feature-flags-sdk-react"

const EMBEDDED_IDE = booleanFlag("EMBEDDED_IDE", false)
const TENANTS_IN_ROLLOUT = stringListFlag("TENANTS_IN_ROLLOUT")

function Editor({ tenantId }: { tenantId: string }) {
  const embeddedIde = useBooleanFlag(EMBEDDED_IDE)
  const rollout = useStringListFlag(TENANTS_IN_ROLLOUT)

  if (!embeddedIde || !rollout.includes(tenantId)) return null
  return <EmbeddedIde />
}

Use um serviceName diferente para cada aplicação, como mitra-web e mitra-backoffice. O endpoint de browser devolve apenas flags cujo serviceNames contém esse nome. Flags com serviceNames: null são globais para consumidores internos e não entram no snapshot entregue ao browser.

Nomes de flags usam UPPER_SNAKE_CASE e aceitam até 100 caracteres.

Cache e Falhas

• Avaliação acontece somente em memória, sem I/O durante render.
• O SDK atualiza o snapshot em segundo plano a cada 60 segundos por padrão.
• refreshJitterMs adiciona de 0 até 10 segundos de variação por padrão depois de cada atualização, evitando que várias abas sincronizem as chamadas. Use 0 para desativar.
• Requests que excedem 3 segundos são abortados por padrão; requestTimeoutMs permite ajustar esse limite.
• ETag evita baixar payload sem alteração.
• Payload inválido, falha HTTP ou token ausente preserva o último snapshot válido.
• O cache do localStorage é validado antes do uso e pode ser desativado com storage={null}.
• O polling e requests pendentes são limpos quando o provider desmonta.

Feature flag no browser controla experiência visual, nunca autorização. APIs continuam responsáveis por validar permissões e regras de negócio no servidor.

Desenvolvimento

npm run lint
npm run format:check
npm run typecheck
npm test
npm run build