@wekivo/next
v0.1.1
Published
SDK Next.js pour Kivo — Provider RSC-safe + helper serveur Edge-compatible.
Maintainers
mic11042024Readme
@wekivo/next
SDK Next.js officiel pour Kivo. Couvre App Router (RSC, Server Actions, Route Handlers, middlewares, Edge) et Pages Router.
Installation
npm install @wekivo/nextCôté client
Le provider est RSC-safe — pose-le dans app/layout.tsx (un Server
Component), il monte son client en interne sans contaminer ton arbre.
import { KivoProvider } from '@wekivo/next';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="fr">
<body>
<KivoProvider apiKey={process.env.NEXT_PUBLIC_KIVO_KEY!}>
{children}
</KivoProvider>
</body>
</html>
);
}Dans un Client Component :
'use client';
import { useKivo } from '@wekivo/next';
export function UpgradeButton({ plan }: { plan: string }) {
const kivo = useKivo();
return (
<button onClick={() => kivo.track('upgrade_clicked', { plan })}>
Passer en {plan}
</button>
);
}L'API useKivo() est identique à celle de @wekivo/react — voir sa
documentation pour les détails (buffer pré-ready, gestion des erreurs).
Côté serveur
@wekivo/next/server expose un helper getKivo() utilisable depuis
toute Server Action, Route Handler, middleware ou job background.
Aucune dépendance Node — compatible Edge Runtime.
'use server';
import { getKivo } from '@wekivo/next/server';
export async function upgradePlan(plan: string) {
const session = await getSession();
const kivo = getKivo({ apiKey: process.env.KIVO_API_KEY! });
await kivo.event({
endUserId: session.user.id,
name: 'plan_upgraded',
payload: { plan, from: session.user.plan },
});
}Edge Runtime
import { getKivo } from '@wekivo/next/server';
export const runtime = 'edge';
export async function POST(req: Request) {
const body = await req.json();
const kivo = getKivo({ apiKey: process.env.KIVO_API_KEY! });
await kivo.identify({
externalId: body.email,
email: body.email,
});
await kivo.event({
endUserId: body.email,
name: 'lead_captured',
payload: { source: 'landing', utm: body.utm },
});
return Response.json({ ok: true });
}Erreurs
Les réponses non-2xx lèvent une KivoServerError avec le status HTTP :
import { getKivo, KivoServerError } from '@wekivo/next/server';
try {
await kivo.event({ endUserId, name: 'checkout_completed' });
} catch (err) {
if (err instanceof KivoServerError && err.status === 429) {
// throttle — re-essayer plus tard
} else {
throw err;
}
}Variables d'environnement
NEXT_PUBLIC_KIVO_KEY=kv_xxxxxxxxxxxxxxxxxxxxxxxx
KIVO_API_KEY=kv_xxxxxxxxxxxxxxxxxxxxxxxxPour l'instant, la même clé sert côté client et côté serveur (clé
tenant unique). Une distinction clé publique / clé secrète arrivera
dans une version future — getKivo({ apiKey }) restera le bon nom.
API
<KivoProvider> — re-exporté de @wekivo/react
| Prop | Type | Défaut | Description |
| --------- | --------------------------------- | --------- | ----------- |
| apiKey | string | — | Clé tenant. Requis. |
| host | string | https://api.wekivo.com | Override de l'host API. |
| cdnUrl | string | jsDelivr | Override de l'URL CDN du widget. |
| endUser | IdentifyPayload | — | Identifie l'utilisateur au mount. |
| options | Partial<KivoConfig> | — | Options widget avancées. |
useKivo() — re-exporté de @wekivo/react
Retourne { identify, track, open, close, reset, ready, instance, error }.
getKivo({ apiKey, host?, fetch? })
Retourne { identify, track, event } (ce dernier est un alias de track).
identify(user)→POST /api/v1/identify— résultat{ endUser: { id, externalId } }.event({ endUserId, name, payload?, occurredAt? })→POST /api/v1/events— résultat{ accepted: number }.