Quick Start | Sylphx Documentation

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/sdk

2. 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 connection URL — never expose to the browser
SYLPHX_URL=sylphx://sk_dev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@bold-river-a1b2c3.api.sylphx.com

# Environment app ID — safe to expose in browser bundles
NEXT_PUBLIC_SYLPHX_APP_ID=app_dev_xxxxxxxxxxxx

Connection URL Format (ADR-055)

One env var per credential type, parsed as a standard URI: sylphx://{credential}@{tenant-slug}.api.sylphx.com. The credential (pk_* or sk_*) is pure entropy with no embedded routing — your tenant slug lives in the host portion of the URL. Copy the URL and app ID from Project → API Keys in the Console.

Keep Your Secret URL Safe

SYLPHX_URL contains an sk_* credential and 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 { createServerClient } from '@sylphx/sdk'
import { getAppConfig } from '@sylphx/sdk/server'
import { SylphxProvider } from '@sylphx/sdk/react'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const sylphx = createServerClient(process.env.SYLPHX_URL!)
  const apiUrl = sylphx.baseUrl.replace(/\/v[0-9]+$/, '')

  // 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: sylphx.secretKey!,
    appId: process.env.NEXT_PUBLIC_SYLPHX_APP_ID!,
    platformUrl: apiUrl,
  })

  return (
    <html lang="en">
      <body>
        <SylphxProvider
          config={config}
          appId={process.env.NEXT_PUBLIC_SYLPHX_APP_ID!}
          platformUrl={apiUrl}
        >
          {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 { createClient, track } from '@sylphx/sdk'
import { auth } from '@sylphx/sdk/nextjs'

// One env var, one parser call, zero ambiguity (ADR-055)
const sylphx = createClient(process.env.SYLPHX_URL!)

export async function POST(req: Request) {
  const { userId } = await auth()
  if (!userId) return new Response('Unauthorized', { status: 401 })

  // Track an event
  await track(sylphx, { event: 'data_created', userId })

  return Response.json({ ok: true })
}

Next Steps

Authentication

OAuth providers, 2FA, passkeys, magic links

Billing

Subscriptions, checkout, usage-based pricing

AI Gateway

200+ models through one unified API

Analytics

Event tracking, funnels, user insights