Tu frontend

Instala y configura el widget de Block-Auth en tu app de React, Vue o Angular.

Instala el widget

npm install @block-auth.io/react

Los estilos se inyectan automáticamente; no hay ningún fichero CSS que importar.

Angular: el widget trae librerías de wallets con módulos CommonJS y dependencias opcionales que el builder de Angular no resuelve. Añádelas a las opciones de build de angular.json, o el build avisa y falla:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "allowedCommonJsDependencies": ["crypto-js", "qrcode", "bs58", "socket.io-client"],
            "externalDependencies": [
              "@base-org/account",
              "@coinbase/wallet-sdk",
              "@metamask/connect-evm",
              "porto",
              "porto/internal",
              "@safe-global/safe-apps-provider",
              "@safe-global/safe-apps-sdk",
              "@walletconnect/ethereum-provider"
            ]
          }
        }
      }
    }
  }
}

Configura el widget

Registra el provider una sola vez, en la raíz de tu app, con tu apiKey pública. El widget llama a las rutas de backend que añadirás después bajo /auth/blockauth.

import { BlockAuthProvider } from '@block-auth.io/react'
import { Header } from './Header'

const config = {
  apiKey: import.meta.env.VITE_BLOCKAUTH_API_KEY,
  locale: 'en',
}

export default function App() {
  return (
    <BlockAuthProvider config={config}>
      <Header />
    </BlockAuthProvider>
  )
}

Opciones de config

• apiKey (string, obligatoria): la API key de tu app. Es pública: solo dice qué app llama.
• authEndpoint (string | false): ruta base de las rutas de tu backend. Por defecto /auth/blockauth: cámbiala solo si tus rutas están bajo otra ruta. Sírvela desde el mismo origen que tu frontend, para que la cookie de sesión viaje en cada petición. Si falta una ruta o no responde, la consola del navegador te dice qué arreglar. Ponla a false solo si tu app no tiene backend: el widget hace el login por sí mismo, y tu página conoce la dirección del usuario pero tu servidor no tiene una sesión de la que fiarse.
• locale (string): idioma del widget, "en" o "es". Por defecto, el del navegador.
• sessionCheckSeconds (number): cada cuánto pregunta el widget a /me si la sesión sigue abierta, además de cada vez que vuelves a la pestaña. Por defecto 60; 0 lo desactiva.
• onSessionEnded (function): se llama cuando tu backend ha cerrado la sesión, por ejemplo después de que el usuario cerrase sesión desde Block-Auth Identity o la extensión. El widget ya muestra al usuario sin sesión: úsalo para salir de las páginas privadas.
• wsUrl (string): el servidor de Block-Auth con el que habla el widget. Por defecto producción (wss://wss.block-auth.io): cámbialo solo si Block-Auth te da otro entorno para hacer pruebas.

El login ocurre en la página de login de Block-Auth (auth.block-auth.io), así que en tu app no configuras Google, Microsoft, wallets ni WalletConnect.

Añade el botón de login

Coloca FlowBlockAuth donde quieras el botón de inicio de sesión. Tras el login se convierte en el menú de perfil y, al recargar, recupera la sesión preguntando a tu backend.

import { FlowBlockAuth } from '@block-auth.io/react'

export function Header() {
  return (
    <header>
      <FlowBlockAuth
        onSuccess={(address) => console.log('Signed in as', address)}
        onError={() => alert('Sign-in failed, try again.')}
        onLogout={() => window.location.assign('/')}
      />
    </header>
  )
}

Leer la sesión (roles, perfil del usuario)

Dentro del provider puedes leer el usuario autenticado (useBlockAuthUser como hook de React o composable de Vue, o las signals de BlockAuthService en Angular) con utilidades como roleNames, hasRoleBySlug(slug) e isLoadingUser:

import { useBlockAuthUser } from "@block-auth.io/react";

function RolesPanel() {
  const { roleNames, hasRole, isLoadingUser } = useBlockAuthUser();
  if (isLoadingUser) return <p>Loading roles…</p>;
  return <p>Your roles: {roleNames.join(", ") || "none"}</p>;
}

Personaliza el widget

Tu apiKey, y el authEndpoint si lo cambias, van en config (Configura el widget). Los componentes solo reciben props de comportamiento, callbacks y estilos.

Las props se documentan con sus nombres de React; la misma interfaz existe en cada binding con el estilo propio del framework:

• Vue: las mismas props en kebab-case (:on-success, :dropdown-btn-size, :show-dropdown-when-connected, …).
• Angular: las props de estilo y comportamiento son inputs ([dropdownBtnSize], [showDropdownWhenConnected], …) y los callbacks son outputs: (success), (errored) y (loggedOut) en FlowBlockAuth, (linked) y (errored) en LinkBlockAuth.

FlowBlockAuth: callbacks

• onSuccess (function): se llama tras un login correcto, con la address del usuario.
• onError (function): se llama cuando el login falla o el usuario cierra la ventana de login.
• onLogout (function): se llama cuando el usuario cierra sesión desde el menú de perfil.

FlowBlockAuth: comportamiento

• showDropdownWhenConnected (boolean): muestra el menú de perfil cuando el usuario tiene sesión (por defecto: true).
• isInsideModal (boolean): ponlo a true cuando el botón esté dentro de un modal propio (por defecto: false).
• containerRef (ref): el contenedor del modal, que se usa con isInsideModal para detectar clics fuera.
• buttonText (string): texto del botón de login.

FlowBlockAuth: cuando tu backend gestiona el login

Con las rutas del backend no necesitas estas props. Úsalas solo si tu página ya conoce al usuario o tu backend canjea el código a su manera. En Angular las dos son inputs: [user] y [onAuthCode].

• user (object | null): el usuario con sesión tal como lo conoce tu backend ({ address, did, roles }), o null si no hay nadie. Con ella, el widget muestra ese usuario y no pregunta a /me al cargar la página, por ejemplo cuando tu servidor ya pinta el usuario.
• onAuthCode (function): recibe { code, codeVerifier, redirectUri } tras el login en lugar de enviarlo a /code. Envíalo a tu backend, canjéalo allí y devuelve el usuario. Salvo que pongas también authEndpoint, el widget no llama entonces a /me ni a /logout ni vigila la sesión: cierra tu sesión en onLogout.

FlowBlockAuth: estilos

• btnClassNames
• btnTextClassNames
• dropdownBtnSize (string): "xs", "small", "base" o "large" (por defecto: "small").
• dropdownBtnBgClassNames
• dropdownBtnTextColorClassNames
• dropdownBtnBorderClassNames
• dropdownHeight (number)
• additionalDropdownItems (array): opciones extra del menú de perfil. Cada elemento es { onClick, text, firstIcon?, disabled? }, donde text es un string o un mapa por idioma ({ es, en }).

LinkBlockAuth

El botón de vinculación de cuentas. Se oculta cuando el usuario ya está vinculado.

• onLinked (function): se llama cuando la cuenta queda vinculada.
• onError (function): se llama con el motivo: already_linked, not_signed_in o failed.
• buttonText (string): texto del botón.
• btnClassNames, btnTextClassNames: igual que en FlowBlockAuth.