Introduction

Fanvue OAuth Quick Start (Next.js App Router)

In a few minutes you’ll have a working Next.js app where users can “Login with Fanvue” using OAuth. We’ll start from the official Fanvue App Starter and run locally with pnpm.

What you’ll build

  • Secure OAuth login with Fanvue
  • Session-backed current-user page after sign-in
  • Production-ready settings you can deploy anywhere
Prerequisites
  • Node.js 18 or later
  • pnpm installed
  • Access to the Fanvue Developer area to create an app (Client ID/Secret)

1) Bootstrap from the Fanvue App Starter

Use the template repository: Fanvue App Starter

Pick one of these ways to start from the template:

  1. Use this template on GitHub

    • Open: Fanvue App Starter
    • Click “Use this template” → “Create a new repository”
    • Clone your new repository locally

  2. Scaffold via degit

    $pnpm dlx degit fanvue/fanvue-app-starter my-fanvue-app
    >cd my-fanvue-app

  3. Clone and re-init

    $git clone https://github.com/fanvue/fanvue-app-starter.git my-fanvue-app
    >cd my-fanvue-app
    >rm -rf .git && git init
Always use pnpm for install, dev, and build commands.

2) Set up local HTTPS proxy

OAuth requires HTTPS redirect URIs, even in local development. We’ll use mkcert and local-ssl-proxy to enable HTTPS locally.

Install mkcert

$brew install mkcert

Generate SSL certificates

Replace my-fanvue-app with your app name:

$mkcert -install
>mkcert my-fanvue-app.dev

This creates two files: my-fanvue-app.dev.pem and my-fanvue-app.dev-key.pem

Update hosts file

$echo "127.0.0.1 my-fanvue-app.dev" | sudo tee -a /etc/hosts

You’ll run the proxy later after configuring environment variables. The proxy will forward HTTPS traffic from port 3001 to your Next.js dev server on port 3000.

3) Create your Fanvue OAuth app

In the Fanvue Developer area, create a new App to obtain credentials:

  • Client ID and Client Secret
  • Redirect URI
    • Development: https://my-fanvue-app.dev:3001/api/oauth/callback (replace my-fanvue-app with your app name)
    • Production: https://YOUR_DOMAIN/api/oauth/callback
  • Scopes
    • For the starter, use: read:self
    • The starter automatically includes required system scopes (openid, offline_access, offline) in addition to what you set in OAUTH_SCOPES

4) Configure environment variables

Create .env.local in the project root and set the following (replace my-fanvue-app with your app name):

$OAUTH_CLIENT_ID=YOUR_CLIENT_ID
>OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
>OAUTH_SCOPES=read:self
>OAUTH_REDIRECT_URI=https://my-fanvue-app.dev:3001/api/oauth/callback
>SESSION_SECRET=use-a-random-16-char-secret
>SESSION_COOKIE_NAME=fanvue_oauth
>
># Normally you do not need to change these:
>OAUTH_ISSUER_BASE_URL=https://auth.fanvue.com
>API_BASE_URL=https://api.fanvue.com
  • Never commit .env.local to version control - Ensure OAUTH_SCOPES exactly matches what you configured in the Fanvue developer UI

5) Install and run locally

First, install dependencies and start the Next.js dev server:

$pnpm install
>pnpm dev

In a separate terminal, start the local SSL proxy (replace my-fanvue-app with your app name):

$npx local-ssl-proxy --source 3001 --target 3000 --cert ./my-fanvue-app.dev.pem --key ./my-fanvue-app.dev-key.pem

Visit https://my-fanvue-app.dev:3001 (replace with your app name) and click “Login with Fanvue”. After authorizing, you’ll be redirected back and see your current user JSON rendered by the app.

6) How it works (at a glance)

  • Next.js App Router with an OAuth callback at /api/oauth/callback
  • Session cookie (SESSION_COOKIE_NAME) signed with SESSION_SECRET
  • Server-side calls to API_BASE_URL using the authenticated session
  • Local SSL proxy forwards HTTPS requests to the Next.js dev server

7) Production deployment

  • Set the same environment variables in your hosting provider
  • In the Fanvue developer UI, add the production Redirect URI: https://YOUR_DOMAIN/api/oauth/callback
  • Build and run
$pnpm install
>pnpm build
>pnpm start
  • Vercel for hosting
  • Supabase if you also need a database

Troubleshooting

  • Invalid redirect URI: The value in the Fanvue developer UI must exactly match OAUTH_REDIRECT_URI (including the HTTPS protocol and port 3001)
  • Scope mismatch: OAUTH_SCOPES must exactly match the scopes selected in the Fanvue developer UI (starter uses read:self)
  • Missing session secret: Set SESSION_SECRET to a random string with at least 16 characters
  • Certificate errors in browser: Run mkcert -install to install the local CA certificate
  • Cannot reach app at .dev domain: Verify the hosts file entry with cat /etc/hosts | grep my-fanvue-app.dev
  • Proxy connection refused: Ensure the Next.js dev server is running on port 3000 before starting the proxy
  • Port already in use: If port 3000 or 3001 is in use, stop other services or use different ports (update proxy and redirect URI accordingly)
  • Blank page after login: Open browser DevTools and your terminal; ensure all env vars are set, the proxy is running, and the callback route is reachable

Where to customize in the starter

  • UI and login experience: src/app/page.tsx
  • OAuth callback and session handling: src/app/api/oauth/callback/route.ts
  • API calls after login: server routes under src/app/api/** using the session’s access token

Next steps

  • Add additional scopes in both the Fanvue developer UI and OAUTH_SCOPES
  • Call other endpoints (e.g., chats, followers) from your server routes
  • Protect pages with middleware that checks the session

Resources: