AuthKit Next.js

There are two ways to evaluate feature flags:

1. feature_flags claim: Use withAuth() to retrieve flags directly from the user's session. This is best for small flag sets. Flags update on the next login or session refresh.
2. Runtime Client: Use getFeatureFlagsRuntimeClient() for large flag sets or when you need server-side evaluation that stays in sync independently of the user session. This client should be created once per server process.

Note: When using the runtime client, call await featureFlags.waitUntilReady() to ensure the client is initialized.

import { getFeatureFlagsRuntimeClient, withAuth } from '@workos-inc/authkit-nextjs';

const featureFlags = getFeatureFlagsRuntimeClient();

export default async function DashboardPage() {
  const { user, organizationId } = await withAuth({ ensureSignedIn: true });

  try {
    await featureFlags.waitUntilReady({ timeoutMs: 5000 });
  } catch (error) {
    console.error('Feature flags client failed to initialize:', error);
  }

  const enabled = featureFlags.isEnabled('advanced-analytics', {
    userId: user.id,
    organizationId,
  });

  return enabled ? <AdvancedAnalytics /> : <BasicAnalytics />;
}

WorkOS requires a callback URL to redirect users back after authentication. You must expose an API route (Route Handler) in your Next.js app that uses handleAuth().

This route's path must match your WORKOS_REDIRECT_URI environment variable and the redirect URI configured in your WorkOS dashboard (e.g., if your URI is /auth/callback, place the code in /app/auth/callback/route.ts).

Key Options for handleAuth:

• returnPathname: The path to redirect the user to after successful sign-in (defaults to /).
• baseURL: The base URL for the redirect URI. Required if running in environments like Docker where the hostname differs from the request.
• onSuccess: A callback function triggered after successful authentication to perform side-effects (e.g., saving tokens or updating a database).
• onError: A callback function to handle authentication errors.

import { handleAuth } from '@workos-inc/authkit-nextjs';

// Basic usage
export const GET = handleAuth();

// With options
export const GET = handleAuth({
  returnPathname: '/dashboard',
  baseURL: 'http://localhost:3000',
  onSuccess: async ({ user, oauthTokens, authenticationMethod, organizationId, state }) => {
    // Perform side-effects here
  },
});

The library uses Next.js middleware/proxy to manage sessions. The implementation depends on your Next.js version:

• Next.js 16+: Create a proxy.ts file in your project root using authkitProxy().
• Next.js ≤15: Create a middleware.ts file in your project root using authkitMiddleware().

Warning on Matchers: Avoid using catch-all patterns that intercept static assets (like _next/static), as this can break styles. Use an exclusion pattern if necessary.

Middleware Options:

• redirectUri: Set a dynamic redirect URI (useful for Vercel preview deployments).
• debug: Enables debug logs.
• signUpPaths: Array of paths that should trigger the 'sign-up' screen hint.
• eagerAuth: Enables synchronous access token availability.
• refreshBufferSeconds: Seconds before expiry to proactively refresh the session (default 60).

// Next.js 16+ (proxy.ts)
import { authkitProxy } from '@workos-inc/authkit-nextjs';
export default authkitProxy();
export const config = { matcher: ['/', '/admin'] };

// Next.js ≤15 (middleware.ts)
import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
export default authkitMiddleware();
export const config = { matcher: ['/', '/admin'] };

// Recommended matcher to avoid breaking static assets
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

To deploy your vinext application to Cloudflare Workers:

1. Set Secrets: Use the Wrangler CLI to upload your WorkOS credentials as Worker secrets. Ensure NEXT_PUBLIC_WORKOS_REDIRECT_URI matches your deployed Workers URL (e.g., https://<your-app>.<subdomain>.workers.dev/callback).
2. Update WorkOS Dashboard: Add the new production callback URL to your WorkOS redirect URIs.
3. Deploy: Run the deploy command to trigger the vinext deploy process, which handles Cloudflare-specific build configurations.

To test the Workers runtime locally (matching production behavior), use a .dev.vars file and run wrangler dev instead of the standard dev server.

# Set secrets
wrangler secret put WORKOS_CLIENT_ID
wrangler secret put WORKOS_API_KEY
wrangler secret put WORKOS_COOKIE_PASSWORD
wrangler secret put NEXT_PUBLIC_WORKOS_REDIRECT_URI

# Deploy
pnpm run deploy

# Local Workers testing
cp .dev.vars.example .dev.vars
wrangler dev