Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-neon
bunx cap sync

Neon Setup

1. Aktivieren Neon Auth in deinem Branch (Console > Auth oder neon neon-auth enable).
2. Aktiviere API Daten im selben Branch, falls du die Database-Helper nutzen möchtest (Console > Data API, mit Neon Auth als Provider).
3. Kopiere den Auth-URL und API Daten-URL aus der Console.

Neon Auth akzeptiert Anfragen nur von vertrauenswürdigen Origins. Localhost ist standardmäßig vertrauenswürdig, und das Plugin sendet Origin: https://localhost, sodass ein neuer Branch ohne Änderungen funktioniert. Wenn du Localhost deaktivierst, füge eine deiner Domains als vertrauenswürdige Domain hinzu und übergib sie als origin zu initialize().

iOS-Setup

Für die Anmeldung per E-Mail und OTP ist kein weiteres Setup erforderlich. Das Plugin nutzt URLSession und den Keychain, ohne Drittanbieter-Abhängigkeiten.

Für OAuth setzen Sie redirectTo auf einen vertrauenswürdigen https Universal Link, der Ihre App öffnet. Neon Auth lehnt Custom URL Schemes als redirectToab. Wenn Sie ein Custom Scheme in der App nutzen, hosten Sie eine vertrauenswürdige HTTPS-Callback-Seite, die den neon_auth_session_verifier Query-Parameter an dieses Scheme weiterleitet.

Android-Setup

Für die Anmeldung per E-Mail und OTP ist kein weiteres Setup erforderlich. Das Plugin funktioniert mit dem Capacitor 8 Standard-Minimum von SDK 24 (Android 7.0).

Für OAuth setzen Sie redirectTo zu einem vertrauenswürdigen https App Link, der deine App öffnet. Neon Auth lehnt benutzerdefinierte URL-Schemes als redirectToab. Wenn du ein benutzerdefiniertes Scheme in der App nutzt, hoste eine vertrauenswürdige HTTPS-Callback-Seite, die den neon_auth_session_verifier Query-Parameter an dieses Scheme weiterleitet.

Häufige Stolperfallen

• Listener: Handles beim Unmounten von Screens entfernen.
• Einmalige Initialisierung: Setup beim App-Bootstrap ausführen.
• OAuth-Redirects: Neon Auth akzeptiert nur vertrauenswürdige https URLs für redirectTo (nur für http lokale Tests auf vertrauenswürdigem localhost). Eigene URL-Schemes werden abgelehnt. Nutze einen Universal Link, App Link oder eine vertrauenswürdige HTTPS-Seite, die den neon_auth_session_verifier Query-Parameter an das URL-Scheme deiner App weiterleitet.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

Client initialisieren

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

Anmelden und JWT abrufen

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

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

Registrieren

Wenn E-Mail-Verifizierung bei der Anmeldung ist für deinen Branch aktiviert, signUp() gibt keine Session zurück, bis der Nutzer die per E-Mail gesendete code bestätigt hat.

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

Auth-Änderungen abonnieren

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.

Native Auth mit neon-js koppeln

Installiere den JavaScript-Client, wenn du dieses Pattern nutzt:

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

Native Datenbank-Helfer

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

Wenn niemand angemeldet ist, nutzen die Database Helpers einen anonymen Data API Token, damit die Row-Level-Security-Policies für die anonymous Rolle greifen.

Empfohlene Nutzung

• Nutze dieses Plugin für Authentifizierung und Session-Management.
• Fortgeschrittene Abfragen gehören in @neondatabase/neon-js.
• Behalten Object Storage und AI Gateway Aufrufe in einer Neon Function oder deiner eigenen API. Beide nutzen Branch-Credentials, die nicht im App-Bundle landen dürfen. Authentifiziere Anfragen an Neon Functions, bevor du auf diese Services zugreifst; ihre URLs sind öffentlich.
• Übergib das native JWT an den JavaScript-Client, Neon Functions oder deine eigene API, wann immer du es brauchst.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails unter „Plugins hinzufügen oder aktualisieren“, Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow in Ionic Enterprise Plugin-Alternativen und Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds.