Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

bun add @capgo/capacitor-neon
bunx cap sync

Neon Setup

1. Abilita Neon Auth sul tuo branch (Console > Auth, o neon neon-auth enable).
2. Abilita il Dati API sullo stesso branch se desideri gli helper del database (Console > Data API, con Neon Auth come provider).
3. Copia il URL Auth e URL Data API dalla Console.

Neon Auth accetta solo richieste da origini fidate. Localhost è fidato di default e il plugin invia Origin: https://localhost, quindi un nuovo branch funziona senza modifiche. Se disattivi localhost, aggiungi uno dei tuoi domini come dominio fidato e passalo come origin a initialize().

Setup iOS

Non è richiesta alcuna configurazione aggiuntiva per l'accesso tramite email e OTP. Il plugin utilizza URLSession e Keychain, senza dipendenze di terze parti.

Per OAuth, imposta redirectTo a un ambiente https Universal Link affidabile che apre la tua app. Neon Auth rifiuta i custom URL scheme come redirectTo. Se utilizzi uno scheme personalizzato nell'app, ospita una pagina di callback HTTPS affidabile che inoltri il neon_auth_session_verifier parametro query a quello scheme.

Configurazione Android

Non è richiesta alcuna configurazione aggiuntiva per l'accesso tramite email e OTP. Il plugin funziona con il minimo predefinito di SDK 24 (Android 7.0) per Capacitor 8.

Per OAuth, imposta redirectTo a un ambiente fidato https App Link che apre la tua app. Neon Auth rifiuta gli URL scheme personalizzati come redirectTo. Se utilizzi uno scheme personalizzato nell'app, ospita una pagina di callback HTTPS affidabile che inoltri il neon_auth_session_verifier parametro query a quello scheme.

Errori comuni

• Listener: rimuovi gli handle quando gli schermi vengono smontati.
• Inizializza una volta: esegui il setup durante il bootstrap dell'app.
• redirect OAuth: Neon Auth accetta solo https URL per redirectTo (in chiaro http solo per test locali su localhost affidabili). Gli schemi URL personalizzati vengono rifiutati. Usa un Universal Link o un App Link, o una pagina HTTPS affidabile che inoltri il neon_auth_session_verifier parametro query allo schema URL della tua app.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Inizializza il client

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',
});

Accedi e ottieni il 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));

Registrati

Se Verifica l'email alla registrazione è abilitata per il tuo branch, signUp() non restituisce alcuna sessione finché l'utente non conferma il code inviato via 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',
  });
}

Ascolta i cambiamenti di Auth

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.

Abbina Native Auth con neon-js

Installa il client JavaScript quando usi questo pattern:

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);

Helper per il Native Build

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);
}

Quando nessuno è loggato, i database helper usano un token API anonimo, così le policy di row-level security per il anonymous ruolo applicato.

Utilizzo consigliato

• Usa questo plugin per l'autenticazione e la gestione delle sessioni.
• Mantieni le query avanzate in @neondatabase/neon-js.
• Mantieni Object Storage e AI Gateway chiamate in una Neon Function o nel tuo API. Entrambi usano credenziali di branch che devono restare fuori dal bundle dell'app. Autentica le richieste alle Neon Functions prima di accedere a questi servizi; i loro URL sono pubblici.
• Passa il JWT nativo al client JavaScript, alle Neon Functions o al tuo API ogni volta che ti serve.

Continua da Getting Started

Se stai usando Per iniziare per pianificare il lavoro sui plugin nativi, collegalo a Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli sull'implementazione in Adding or Updating Plugins, Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Ionic Enterprise Plugin Alternatives, e Capgo Native Build per il workflow di prodotto in Capgo Native Builds.