{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/supertokens-on-vercel", "result": {"data":{"markdownRemark":{"html":"

This comprehensive walkthrough covers integrating SuperTokens authentication into a Next.js project hosted on Vercel, including local\nsetup, API route configuration, serverless deployment considerations, and complete authentication flow implementation.

\n

Why Use SuperTokens on Vercel?

\n

\n \n \n \n \n

\n

SuperTokens paired with Vercel creates a powerful authentication solution that balances developer experience with production-grade\nsecurity.

\n\n

Prerequisites

\n

Before beginning implementation, ensure the following tools and accounts are available:

\n

Development environment requirements:

\n\n

Deployment requirements:

\n\n

Configuration preparation:

\n\n

Step 1 — Bootstrap a Next.js Project

\n

Create a new Next.js project or use an existing application as the foundation for SuperTokens integration:

\n\n \n \n \n \n
 npx create-next-app@latest supertokens-vercel-demo                                                                                      \n cd supertokens-vercel-demo
\n

The Next.js CLI prompts for configuration options. For SuperTokens\ncompatibility, select the following:

\n\n

Install SuperTokens SDKs for both backend and frontend integration:

\n\n \n \n \n \n
  npm install supertokens-node supertokens-auth-react
\n

These packages provide the core authentication functionality:

\n
    \n
  • supertokens-node: Backend SDK for API routes and session management
    • \n
  • supertokens-auth-react: Frontend components and React integration
    • \n
\n

Step 2 — Set Up SuperTokens Backend

\n

Create the authentication API route handler that processes all SuperTokens backend operations.

\n

For App Router (Next.js 13+), create src/app/api/auth/[[...path]]/route.ts:

\n\n \n \n \n \n
// src/app/api/auth/[[...path]]/route.ts\nimport { getAppDirRequestHandler } from \"supertokens-node/nextjs\";\nimport { NextRequest } from \"next/server\";\nimport { ensureSuperTokensInit } from \"@/app/config/backend\";\n\n\nensureSuperTokensInit();\n\n\nconst handleCall = getAppDirRequestHandler();\n\n\nexport async function GET(req: NextRequest) {\n  const res = await handleCall(req);\n  if (!res.headers.has(\"Cache-Control\")) {\n    res.headers.set(\n      \"Cache-Control\",\n      \"no-cache, no-store, max-age=0, must-revalidate\"\n    );\n  }\n  return res;\n}\nexport const POST = handleCall;\nexport const PUT = handleCall;\nexport const DELETE = handleCall;\nexport const PATCH = handleCall;\nexport const HEAD = handleCall;\n
\n

This file acts as a proxy route — it passes all authentication requests to the SuperTokens backend handler.

\n

By mapping all HTTP methods (GET, POST, etc.) to handleCall, we ensure every auth-related request is handled correctly.

\n

Create backend configuration at src/app/config/backend.ts:

\n {\n const apiDomain = process.env.VERCEL_URL\n ? \\`https://\\${process.env.VERCEL_URL}\\`\n : process.env.NEXT_PUBLIC_API_DOMAIN || "http://localhost:3000";\n\n\n const websiteDomain = process.env.VERCEL_URL\n ? \\`https://\\${process.env.VERCEL_URL}\\`\n : process.env.NEXT_PUBLIC_WEBSITE_DOMAIN || "http://localhost:3000";\n\n\n return {\n appInfo: {\n appName: "SuperTokens Vercel Demo",\n apiDomain,\n websiteDomain,\n apiBasePath: "/api/auth",\n websiteBasePath: "/auth",\n },\n supertokens: {\n connectionURI:\n process.env.SUPERTOKENS_CONNECTION_URI || "https://try.supertokens.io",\n apiKey: process.env.SUPERTOKENS_API_KEY,\n },\n recipeList: [\n EmailPassword.init(),\n Session.init({\n cookieSameSite: "lax",\n cookieSecure: process.env.NODE_ENV === "production",\n }),\n ],\n };\n};\n\n\nexport function ensureSuperTokensInit() {\n try {\n SuperTokens.init(backendConfig());\n } catch (err: unknown) {\n const msg = String((err as Error).message || "");\n if (!/already initiali/i.test(msg)) {\n throw err;\n }\n }\n}`, `80730374283274080000`)\"\n >\n \n \n \n \n
// src/app/config/backend.ts\n\n\nimport SuperTokens from \"supertokens-node\";\nimport EmailPassword from \"supertokens-node/recipe/emailpassword\";\nimport Session from \"supertokens-node/recipe/session\";\nimport { TypeInput } from \"supertokens-node/types\";\n\n\nexport const backendConfig = (): TypeInput => {\n  const apiDomain = process.env.VERCEL_URL\n    ? `https://${process.env.VERCEL_URL}`\n    : process.env.NEXT_PUBLIC_API_DOMAIN || \"http://localhost:3000\";\n\n\n  const websiteDomain = process.env.VERCEL_URL\n    ? `https://${process.env.VERCEL_URL}`\n    : process.env.NEXT_PUBLIC_WEBSITE_DOMAIN || \"http://localhost:3000\";\n\n\n  return {\n    appInfo: {\n      appName: \"SuperTokens Vercel Demo\",\n      apiDomain,\n      websiteDomain,\n      apiBasePath: \"/api/auth\",\n      websiteBasePath: \"/auth\",\n    },\n    supertokens: {\n      connectionURI:\n        process.env.SUPERTOKENS_CONNECTION_URI || \"https://try.supertokens.io\",\n      apiKey: process.env.SUPERTOKENS_API_KEY,\n    },\n    recipeList: [\n      EmailPassword.init(),\n      Session.init({\n        cookieSameSite: \"lax\",\n        cookieSecure: process.env.NODE_ENV === \"production\",\n      }),\n    ],\n  };\n};\n\n\nexport function ensureSuperTokensInit() {\n  try {\n    SuperTokens.init(backendConfig());\n  } catch (err: unknown) {\n    const msg = String((err as Error).message || \"\");\n    if (!/already initiali/i.test(msg)) {\n      throw err;\n    }\n  }\n}
\n

This configuration initializes SuperTokens with email/password authentication and session management. The appInfo object uses environment variables for dynamic URL configuration essential for Vercel deployments.

\n

Step 3 — Create SuperTokens Frontend Wrapper

\n

Frontend integration connects React components with SuperTokens authentication backend.

\n

Configure frontend at src/app/config/frontend.ts:

\n {\n return {\n appInfo: {\n appName: "SuperTokens Vercel Demo",\n apiDomain: process.env.NEXT_PUBLIC_API_DOMAIN || "http://localhost:3000",\n websiteDomain: process.env.NEXT_PUBLIC_WEBSITE_DOMAIN || "http://localhost:3000",\n apiBasePath: "/api/auth",\n websiteBasePath: "/auth",\n },\n recipeList: [\n EmailPasswordReact.init(),\n SessionReact.init(),\n ],\n };\n};`, `11448959390809477000`)\"\n >\n \n \n \n \n
// src/app/config/frontend.ts\nimport EmailPasswordReact from \"supertokens-auth-react/recipe/emailpassword\";\nimport SessionReact from \"supertokens-auth-react/recipe/session\";\n\n\nexport const frontendConfig = () => {\n  return {\n    appInfo: {\n      appName: \"SuperTokens Vercel Demo\",\n      apiDomain: process.env.NEXT_PUBLIC_API_DOMAIN || \"http://localhost:3000\",\n      websiteDomain: process.env.NEXT_PUBLIC_WEBSITE_DOMAIN || \"http://localhost:3000\",\n      apiBasePath: \"/api/auth\",\n      websiteBasePath: \"/auth\",\n    },\n    recipeList: [\n      EmailPasswordReact.init(),\n      SessionReact.init(),\n    ],\n  };\n};
\n

Wrap application in src/app/layout.tsx:

\n\n \n {children}\n \n \n );\n}`, `94149769976833620000`)\"\n >\n \n \n \n \n
// src/app/layout.tsx\n\"use client\";\nimport React from \"react\";\nimport SuperTokensReact from \"supertokens-auth-react\";\nimport { SuperTokensWrapper } from \"supertokens-auth-react\";\nimport { frontendConfig } from \"./config/frontend\";\n\n\nif (\n  typeof window !== \"undefined\" &&\n  !(globalThis as unknown as { __supertokens_initialized: boolean })\n    .__supertokens_initialized\n) {\n  SuperTokensReact.init(frontendConfig());\n  (\n    globalThis as unknown as { __supertokens_initialized: boolean }\n  ).__supertokens_initialized = true;\n}\n\n\nexport default function RootLayout({\n  children,\n}: {\n  children: React.ReactNode;\n}) {\n  return (\n    <html lang=\"en\">\n      <body>\n        <SuperTokensWrapper>{children}</SuperTokensWrapper>\n      </body>\n    </html>\n  );\n}
\n

Add authentication routing component at src/app/auth/page.tsx:

\n {\n setReady(true);\n }, []);\n\n\n if (!ready) return null;\n\n\n return ;\n}`, `17121586558361512000`)\"\n >\n \n \n \n \n
\"use client\";\n\n\nimport React, { useEffect, useState } from \"react\";\nimport \"@/app/config/supertokens-init\";\nimport { AuthPage } from \"supertokens-auth-react/ui\";\nimport { EmailPasswordPreBuiltUI } from \"supertokens-auth-react/recipe/emailpassword/prebuiltui\";\n\n\nexport const dynamic = \"force-dynamic\";\n\n\nexport default function AuthPageWrapper() {\n  const [ready, setReady] = useState(false);\n\n\n  useEffect(() => {\n    setReady(true);\n  }, []);\n\n\n  if (!ready) return null;\n\n\n  return <AuthPage preBuiltUIList={[EmailPasswordPreBuiltUI]} />;\n}
\n

This component renders SuperTokens pre-built authentication UI, including login, signup, password reset, and email verification flows.

\n

Protected Route Example

\n

File: src/app/protected/page.tsx

\n(null);\n\n\n useEffect(() => {\n const check = async () => {\n try {\n const s = await Session.getAccessTokenPayloadSecurely();\n // If session exists, getUserId from accessToken payload or call protected API.\n setUserId(s?.sub || "signed-in");\n } catch {\n setUserId(null);\n }\n };\n check();\n }, []);\n\n\n if (userId === null)\n return (\n
\n Not signed in. Go to /auth\n
\n );\n return
Signed in. userId: {String(userId)}
;\n}`, `81965315855192050000`)\"\n >\n \n \n \n \n
//src/app/protected/page.tsx\n\"use client\";\nimport { useEffect, useState } from \"react\";\nimport Session from \"supertokens-auth-react/recipe/session\";\n\n\nexport default function ProtectedPage() {\n  const [userId, setUserId] = useState<string | null>(null);\n\n\n  useEffect(() => {\n    const check = async () => {\n      try {\n        const s = await Session.getAccessTokenPayloadSecurely();\n        // If session exists, getUserId from accessToken payload or call protected API.\n        setUserId(s?.sub || \"signed-in\");\n      } catch {\n        setUserId(null);\n      }\n    };\n    check();\n  }, []);\n\n\n  if (userId === null)\n    return (\n      <div>\n        Not signed in. Go to <a href=\"/auth\">/auth</a>\n      </div>\n    );\n  return <div>Signed in. userId: {String(userId)}</div>;\n}
\n

This page checks if a valid session exists. If not signed in → redirects user to /auth.

\n

If signed in → displays their userId or token payload.

\n

Initialize SuperTokens (Client Side)

\n

File: src/app/config/supertokens-init.ts

\n\n \n \n \n \n
//src/app/config/supertokens-init.ts\n\"use client\";\n\n\nimport SuperTokensReact from \"supertokens-auth-react\";\nimport { frontendConfig } from \"./frontend\";\n\n\nif (typeof window !== \"undefined\") {\n  if (!SuperTokensReact.isRecipeInitialized(\"emailpassword\")) {\n    SuperTokensReact.init(frontendConfig());\n  }\n}
\n

This lightweight script ensures SuperTokens is properly initialized when the app runs in the browser.

\n

Home Page Links

\n

File: src/app/page.tsx

\n\n

SuperTokens Demo

\n
    \n
  • Auth UI
    • \n
  • Protected (client)
    • \n
\n \n );\n}`, `7335561762471143000`)\"\n >\n \n \n \n \n
// src/app/page.tsx\nimport Link from \"next/link\";\n\n\nexport default function Home() {\n  return (\n    <main style={{ padding: 24 }}>\n      <h1>SuperTokens Demo</h1>\n      <ul>\n        <li><Link href=\"/auth\">Auth UI</Link></li>\n        <li><Link href=\"/protected\">Protected (client)</Link></li>\n      </ul>\n    </main>\n  );\n}
\n

Step 4 — Configure Environment Variables

\n

Vercel provides the VERCEL_URL environment variable to the backend, which points to the current URL that the app is deployed on. This enables SuperTokens to work across development, preview, and production environments.

\n

Local development configuration in .env.local:

\n\n \n \n \n \n
SUPERTOKENS_CONNECTION_URI=https://try.supertokens.io\nSUPERTOKENS_API_KEY=\nNEXT_PUBLIC_API_DOMAIN=http://localhost:3000\nNEXT_PUBLIC_WEBSITE_DOMAIN=http://localhost:3000
\n

Production environment variables in the Vercel dashboard:

\n\n \n \n \n \n
SUPERTOKENS_CONNECTION_URI=PRODUCTION_CONNECTION_URI\nSUPERTOKENS_API_KEY=your_production_api_key\nNEXT_PUBLIC_API_DOMAIN=https://your-app.vercel.app\nNEXT_PUBLIC_WEBSITE_DOMAIN=https://your-app.vercel.app
\n

For managed SuperTokens hosting, replace the SUPERTOKENS_CONNECTION_URI with your dedicated instance URL. Self-hosted deployments require ensuring the SuperTokens Core service is publicly accessible via HTTPS.

\n

Dynamic URL configuration for Vercel preview deployments requires using process.env.VERCEL_URL in backend configuration:

\n\n \n \n \n \n
appInfo: {\n  apiDomain: process.env.VERCEL_URL\n    ? `https://${process.env.VERCEL_URL}`\n    : process.env.NEXT_PUBLIC_API_DOMAIN,\n  websiteDomain: process.env.VERCEL_URL\n    ? `https://${process.env.VERCEL_URL}`\n    : process.env.NEXT_PUBLIC_WEBSITE_DOMAIN,\n}
\n

Step 5 — Deploy to Vercel

\n

Vercel deployment follows a straightforward process for Next.js applications with SuperTokens.

\n

\n \n \n \n \n

\n

Prepare for deployment:

\n
    \n
  1. Commit all changes to your Git repository:
    2. \n
\n\n \n \n \n \n
git add .\ngit commit -m \"Add SuperTokens authentication\"\ngit push origin main
\n
    \n
  1. Navigate to the Vercel dashboard and import your repository
    2. \n
  2. Configure environment variables in Vercel project settings
    3. \n
  3. Deploy the application
    4. \n
\n

Vercel automatically:

\n
    \n
  • Detects the Next.js framework
    • \n
  • Installs dependencies
    • \n
  • Builds the application
    • \n
  • Deploys to serverless infrastructure
    • \n
  • Generates preview URLs for pull requests
    • \n
\n

Important deployment considerations:

\n
    \n
  • This only works if the frontend and backend of your application have the same domain. If your backend is hosted separately, configure apiDomain to point to your backend server.
    • \n
  • Ensure CORS configuration allows requests from Vercel preview URLs
    • \n
  • Verify environment variables are set correctly in the Vercel dashboard
    • \n
  • Test authentication flows on the preview deployment before promoting to production
    • \n
\n

Step 6 — Test Auth Flow

\n

Verify authentication implementation works correctly across all flows.

\n

Registration flow testing:

\n
    \n
  1. Navigate to the /auth route in your deployed application
    2. \n
  2. Click “Sign Up” and create a new account
    3. \n
  3. Verify email verification flow (if enabled)
    4. \n
  4. Confirm successful redirect after registration
    5. \n
\n

\n \n \n \n \n

\n

\n \n \n \n \n

\n

\n \n \n \n \n

\n

Session verification:

\n

Protect API routes by verifying session tokens:

\n {\n if (!session) {\n return NextResponse.json(\n { error: "Unauthorized" },\n { status: 401 }\n );\n }\n\n\n const userId = session.getUserId();\n \n return NextResponse.json({\n message: "Protected data",\n userId: userId,\n });\n }\n );\n}`, `47919955470354830000`)\"\n >\n \n \n \n \n
import { withSession } from \"supertokens-node/nextjs\";\nimport { SessionContainer } from \"supertokens-node/recipe/session\";\nimport { NextRequest, NextResponse } from \"next/server\";\n\n\nexport async function GET(request: NextRequest) {\n  return withSession(\n    request,\n    async (session: SessionContainer | undefined) => {\n      if (!session) {\n        return NextResponse.json(\n          { error: \"Unauthorized\" },\n          { status: 401 }\n        );\n      }\n\n\n      const userId = session.getUserId();\n     \n      return NextResponse.json({\n        message: \"Protected data\",\n        userId: userId,\n      });\n    }\n  );\n}
\n

Cookie and session persistence:

\n
    \n
  • Verify session cookies are set with the correct security flags
    • \n
  • Test session persistence across page navigation
    • \n
  • Confirm that the logout functionality clears the session properly
    • \n
  • Validate that session refresh works without user interaction
    • \n
\n

Optional: Enable Social or Passwordless Login

\n

SuperTokens supports multiple authentication methods that can be added or combined according to specific requirements.

\n

Social login integration with ThirdPartyEmailPassword:

\n\n \n \n \n \n
import ThirdPartyEmailPassword from \"supertokens-node/recipe/thirdpartyemailpassword\";\nimport Google from \"supertokens-node/recipe/thirdpartyemailpassword/providers/google\";\nimport Github from \"supertokens-node/recipe/thirdpartyemailpassword/providers/github\";\n\n\nThirdPartyEmailPassword.init({\n  providers: [\n    Google({\n      clientId: process.env.GOOGLE_CLIENT_ID!,\n      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,\n    }),\n    Github({\n      clientId: process.env.GITHUB_CLIENT_ID!,\n      clientSecret: process.env.GITHUB_CLIENT_SECRET!,\n    }),\n  ],\n});
\n

Passwordless authentication with magic links or OTP:

\n\n \n \n \n \n
import Passwordless from \"supertokens-node/recipe/passwordless\";\n\n\nPasswordless.init({\n  contactMethod: \"EMAIL_OR_PHONE\",\n  flowType: \"MAGIC_LINK\",\n});
\n

Frontend configuration requires updating recipe initialization to match backend configuration. SuperTokens automatically renders appropriate UI components based on enabled recipes.

\n

SuperTokens Features That Work Seamlessly on Vercel

\n

SuperTokens architecture aligns well with Vercel’s serverless platform, providing several advantages:

\n
    \n
  • Serverless session verification operates efficiently within Vercel’s serverless functions, with minimal cold start overhead. Session validation requires only JWT verification or database lookup, completing within milliseconds even on cold starts.
    • \n
  • Flexible session management supports both stateless JWT tokens and stateful database sessions. Stateless tokens eliminate database dependency for session verification, while stateful sessions provide immediate revocation capabilities essential for security-sensitive applications.
    • \n
  • Multi-tenant authentication enables serving multiple customers from a single deployment with tenant-specific authentication configurations, branding, and user bases. This architecture works particularly well with Vercel’s edge network for global distribution.
    • \n
  • Frontend UI theming provides complete customization of authentication interfaces without requiring custom component development. CSS variables and component overrides enable matching authentication UI to application design systems.
    • \n
  • Type-safe claims and user roles integrate with TypeScript for compile-time type checking of user permissions and session claims, reducing runtime errors and improving developer experience.
    • \n
\n

Limitations & Workarounds

\n

Understanding platform constraints helps avoid common implementation pitfalls.

\n
    \n
  • Cold start latency affects serverless functions on Vercel’s free and hobby tiers. SuperTokens API routes experience slight latency during cold starts as the Node.js runtime initializes. Vercel Pro plans reduce cold start frequency through reserved capacity. For critical authentication endpoints, consider keeping functions warm through periodic health check requests.
    • \n
  • Edge runtime compatibility remains limited. SuperTokens relies on Node.js APIs unsupported in Vercel’s edge runtime, requiring standard serverless API routes rather than edge functions. This limitation affects global latency for authentication operations but typically remains acceptable for most applications.
    • \n
  • Self-hosted SuperTokens Core requirements mandate public HTTPS accessibility. Organizations self-hosting SuperTokens Core must expose the service to the internet or configure VPN connectivity between Vercel deployments and private networks. Managed SuperTokens hosting eliminates these networking concerns.
    • \n
  • Preview deployment considerations require dynamic URL configuration to support Vercel’s unique preview URLs for each pull request. The VERCEL_URL environment variable enables this functionality but requires proper configuration in appInfo.
    • \n
\n

Frequently Asked Questions

\n
    \n
  • Can I use the SuperTokens managed service on Vercel?
    • \n
\n

Yes, managed SuperTokens hosting works seamlessly with Vercel deployments. Point SUPERTOKENS_CONNECTION_URI to your managed instance URL and configure the API key. Managed hosting eliminates operational overhead while providing production-grade reliability and security.

\n
    \n
  • Can I deploy to Vercel edge functions?
    • \n
\n

Not currently. SuperTokens requires Node.js APIs unavailable in Vercel’s edge runtime. Use standard serverless API routes, which provide sufficient performance for most authentication workloads while supporting SuperTokens functionality.

\n
    \n
  • How do I handle custom domains?
    • \n
\n

Configure custom domains through Vercel dashboard, then update environment variables to reflect custom domain URLs. Ensure apiDomain and websiteDomain match your custom domain configuration.

\n
    \n
  • What about database requirements?
    • \n
\n

SuperTokens Core handles user data storage internally. Applications using self-hosted Core need to configure database connectivity (PostgreSQL, MySQL, or MongoDB supported). Managed SuperTokens hosting includes database infrastructure.

\n

Conclusion

\n

SuperTokens integrates naturally with Vercel’s developer-friendly environment, providing production-ready authentication that scales from prototype to enterprise deployment. The combination delivers secure, customizable authentication in minutes rather than weeks of custom development.

\n

Whether prototyping new features, launching minimum viable products, or scaling to millions of users, SuperTokens on Vercel provides authentication infrastructure that grows with application requirements. The open-source foundation ensures transparency and flexibility, while managed hosting options eliminate operational complexity for teams preferring convenience over infrastructure control.

\n

Start by deploying the example application, test authentication flows thoroughly, and progressively add features as requirements evolve. The modular architecture enables incremental adoption without requiring comprehensive upfront planning or migration efforts.

","frontmatter":{"date":"November 18, 2025","title":"Deploying SuperTokens on Vercel with Next.js","cover":"supertokens-on-vercel.png","author":"Mostafa Ibrahim","description":"Step-by-step guide to deploying SuperTokens authentication on Vercel with Next.js. Learn setup, environment config, API routes, and deployment tips."},"fields":{"slug":"/supertokens-on-vercel/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"3653ded7-57bb-5c43-bb99-c4308c78c77e","fields__slug":"/supertokens-on-vercel/","__params":{"fields__slug":"supertokens-on-vercel"}}}, "staticQueryHashes": []}