Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-neon` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/capacitor-neon
bunx cap sync

Neon Setup

1. Activar Neon Auth en tu rama (Console > Auth, o neon neon-auth enable).
2. Habilita el Datos de API en la misma rama si quieres los helpers de la base de datos (Console > Data API, con Neon Auth como proveedor).
3. Copia el Auth URL y URL de datos de API desde la Console.

Neon Auth solo acepta peticiones de orígenes de confianza. Localhost es de confianza por defecto, y el plugin envía Origin: https://localhost, así que una nueva rama funciona sin cambios. Si desactivas localhost, añade uno de tus dominios como dominio de confianza y pásalo como origin a initialize().

Configurar iOS

No se requiere configuración adicional para el inicio de sesión con email y OTP. El plugin utiliza URLSession y Keychain, sin dependencias de terceros.

Para OAuth, establece redirectTo a uno de confianza https Universal Link de confianza que abra tu app. Neon Auth rechaza los custom URL schemes como redirectTo. Si usas un custom scheme en la app, aloja una página de callback HTTPS de confianza que redirija el neon_auth_session_verifier parámetro de consulta a ese scheme.

Configuración de Android

No se requiere configuración adicional para el inicio de sesión con email y OTP. El plugin funciona con un Capacitor mínimo de 8 y un SDK de 24 (Android 7.0).

Para OAuth, establece redirectTo a uno de confianza https App Link que abre tu app. Neon Auth rechaza esquemas de URL personalizados como redirectTo. Si usas un esquema personalizado en la app, aloja una página de callback HTTPS de confianza que redirija el neon_auth_session_verifier parámetro de consulta a ese esquema.

Errores comunes

• Listeners: elimina los handles cuando se desmonten las pantallas.
• Inicializa una vez: run setup during app bootstrap.
• Redirecciones OAuth: Neon Auth solo acepta https URLs para redirectTo (texto plano http solo para pruebas locales en un localhost de confianza). Los esquemas de URL personalizados se rechazan. Usa un Universal Link o un App Link, o una página HTTPS de confianza que reenvíe el neon_auth_session_verifier parámetro de consulta al esquema de URL de tu app.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Inicializa el cliente

import { CapacitorNeon } from '@capgo/capacitor-neon';

await CapacitorNeon.initialize({
  authUrl: 'https://ep-xxx.neonauth.us-east-2.aws.neon.tech/neondb/auth',
  dataApiUrl: 'https://ep-xxx.apirest.us-east-2.aws.neon.tech/neondb/rest/v1',
});

Inicia sesión y accede al JWT

const { session, user } = await CapacitorNeon.signInWithPassword({
  email: 'user@example.com',
  password: 'password123',
});

console.log('User', user?.id);
console.log('JWT available', Boolean(session?.accessToken));

Registrarse

Si Verificación de email al registrarse está habilitada para tu rama, signUp() no devuelve ninguna sesión hasta que el usuario confirme el code enviado por email.

import { CapacitorNeon } from '@capgo/capacitor-neon';

const { session } = await CapacitorNeon.signUp({
  email: 'newuser@example.com',
  password: 'password123',
  name: 'John Doe',
});

if (!session) {
  await CapacitorNeon.verifyOtp({
    email: 'newuser@example.com',
    token: '123456',
    type: 'signup',
  });
}

Escuchar cambios de autenticación

const listener = await CapacitorNeon.addListener('authStateChange', ({ event, session }) => {
  console.log('Auth event', event);
  console.log('Current JWT available', Boolean(session?.accessToken));
});

// Call listener.remove() when the screen unmounts.

Vincula Native Auth con neon-js

Instala el cliente de JavaScript si usas este patrón:

bun add @neondatabase/neon-js

import { CapacitorNeon } from '@capgo/capacitor-neon';
import { createClient } from '@neondatabase/neon-js';

const neon = createClient({
  dataApi: {
    url: 'https://ep-xxx.apirest.us-east-2.aws.neon.tech/neondb/rest/v1',
    getToken: async () => (await CapacitorNeon.getSession()).session?.accessToken ?? null,
  },
});

const { data } = await neon.from('table').select('*');
console.log('Row count', data?.length ?? 0);

Helpers de base de datos nativa

const { data, error } = await CapacitorNeon.select({
  table: 'users',
  columns: 'id, name, email',
  filter: { active: true },
  limit: 10,
  orderBy: 'created_at',
  ascending: false,
});

if (error) {
  console.error('Select failed', error);
} else {
  console.log('Rows returned', data?.length ?? 0);
}

Cuando nadie ha iniciado sesión, los helpers de la base de datos usan un token de datos API anónimo, por lo que las políticas de seguridad a nivel de fila para el anonymous rol.

Uso recomendado

• Usa este plugin para la autenticación y gestión de sesiones.
• Mantén las consultas avanzadas en @neondatabase/neon-js.
• Mantén Almacenamiento de objetos y AI Gateway llamadas en una Neon Function o en tu propio API. Ambos usan credenciales de rama que deben estar fuera del app bundle. Autentica las peticiones a Neon Functions antes de acceder a estos servicios; sus URLs son públicas.
• Pasa el JWT nativo al cliente de JavaScript, a Neon Functions o a tu propio API cuando lo necesites.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo en Alternativas a plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds.