What You Get
Auth, billing, analytics, AI, storage, KV, realtime, feature flags, and more — all through one type-safe SDK. No separate integrations, dashboards, or SDKs to learn.
1. Install the SDK
npm install @sylphx/sdk2. Get Your API Keys
Create a project in the Sylphx Console and copy your keys from Project → API Keys. Add them to your environment:
.env.local
# Server-only — never expose to the browser
SYLPHX_SECRET_KEY=sk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Client-safe publishable key
NEXT_PUBLIC_SYLPHX_KEY=pk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKey Format (ADR-021)
Keys are self-describing:
sk_{env}_{ref}_{secret} and pk_{env}_{ref}_{token}. The project ref is embedded — no separate App ID variable needed. Legacy app_* keys still work.Keep Your Secret Key Safe
SYLPHX_SECRET_KEY (sk_*) must stay server-side only — API routes, Server Components, and middleware. Never use it in client code.3. Root Layout
Fetch server-side config once and pass it down via SylphxProvider:
app/layout.tsx
import { getAppConfig } from '@sylphx/sdk/server'
import { SylphxProvider } from '@sylphx/sdk/react'
export default async function RootLayout({ children }: { children: React.ReactNode }) {
// Fetches plans, feature flags, consent types, OAuth providers in one call.
// Uses Next.js cache() — runs once per request, not per component.
const config = await getAppConfig({
secretKey: process.env.SYLPHX_SECRET_KEY!,
appId: process.env.NEXT_PUBLIC_SYLPHX_KEY!,
})
return (
<html lang="en">
<body>
<SylphxProvider
appId={process.env.NEXT_PUBLIC_SYLPHX_KEY!}
config={config}
>
{children}
</SylphxProvider>
</body>
</html>
)
}4. Add Middleware
One middleware handles auth routes, token refresh, and route protection automatically. No manual /api/auth/* routes needed:
middleware.ts
import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'
export default createSylphxMiddleware({
publicRoutes: ['/', '/about', '/pricing', '/login', '/signup'],
})
export const config = {
matcher: ['/((?!_next|.*\\..*).*)', '/'],
}5. Add a Login Page
Drop in the built-in SignIn component — supports email/password, OAuth, magic links, and passkeys out of the box:
app/login/page.tsx
import { SignIn } from '@sylphx/sdk/react'
export default function LoginPage() {
return (
<div className="flex min-h-screen items-center justify-center">
<SignIn
mode="embedded"
afterSignInUrl="/dashboard"
signUpUrl="/signup"
/>
</div>
)
}6. Use the SDK in Your App
React hooks for client components:
app/dashboard/page.tsx
'use client'
import { useUser, useBilling, SignedIn, SignedOut, UserButton } from '@sylphx/sdk/react'
export default function Dashboard() {
const { user, isLoading } = useUser()
const { isPremium } = useBilling()
if (isLoading) return <div>Loading...</div>
return (
<div>
<SignedIn>
<header className="flex justify-between items-center p-4">
<h1>Hello, {user?.name}</h1>
<UserButton />
</header>
{isPremium ? <PremiumFeatures /> : <UpgradePrompt />}
</SignedIn>
<SignedOut>
<p>Please sign in to continue.</p>
</SignedOut>
</div>
)
}Server Components and API routes:
app/profile/page.tsx (Server Component)
import { currentUser, auth } from '@sylphx/sdk/nextjs'
import { redirect } from 'next/navigation'
export default async function ProfilePage() {
const user = await currentUser()
if (!user) redirect('/login')
return (
<div>
<h1>Welcome back, {user.name}</h1>
<p>Email: {user.email}</p>
</div>
)
}app/api/data/route.ts (API Route)
import { createConfig, track } from '@sylphx/sdk'
import { auth } from '@sylphx/sdk/nextjs'
const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
export async function POST(req: Request) {
const { userId } = await auth()
if (!userId) return new Response('Unauthorized', { status: 401 })
// Track an event
await track(config, { event: 'data_created', userId })
return Response.json({ ok: true })
}