@lovable.dev/cloud-auth-js

@lovable.dev/cloud-auth-js

OAuth authentication library for Lovable projects.

Installation

npm install @lovable.dev/cloud-auth-js

Usage

Better Auth

Client setup:

import { newAuthClient } from "@lovable.dev/cloud-auth-js";

export const authClient = newAuthClient();
export const { signIn, signOut } = authClient;

TanStack Start route setup:

import { createFileRoute } from "@tanstack/react-router";
import { registerAuthRoutes } from "@lovable.dev/cloud-auth-js/server";

export const Route = createFileRoute("/api/auth/$")(registerAuthRoutes());

Sign in with the Lovable OAuth provider:

await authClient.signInWithLovable({
  // Redirects here after successful authentication.
  callbackURL: "/account",
});

signInWithLovable uses redirect mode outside an iframe and popup mode in live preview. Pass mode: "redirect" or mode: "popup" to force a flow.

Server env vars:

Name	Description
LOVABLE_TENANT_ID	Lovable tenant ID.
LOVABLE_OAUTH_CLIENT_ID	Lovable OAuth client ID.
LOVABLE_OAUTH_CLIENT_SECRET	Lovable OAuth client secret.
LOVABLE_AUTH_SECRET	Secret used to sign auth cookies and tokens.
LOVABLE_AUTH_TRUSTED_ORIGINS	Comma-separated trusted origins.

Legacy OAuth broker

import { createLovableAuth } from "@lovable.dev/cloud-auth-js";
import { supabase } from "./supabase/client";

const lovableAuth = createLovableAuth();

// Sign in with OAuth
const result = await lovableAuth.signInWithOAuth("google");

if (result.redirected) {
  // Page is redirecting to OAuth provider
  return;
}

if (result.error) {
  console.error("Sign in failed:", result.error.message);
  return;
}

await supabase.auth.setSession(result.tokens);

Legacy API

createLovableAuth(config?)

Creates a Lovable auth instance.

Config options:

Option	Type	Default	Description
oauthBrokerUrl	string	"/~oauth/initiate"	OAuth broker initiate URL
supportedOAuthOrigins	string[]	["https://oauth.lovable.app"]	Allowed origins for OAuth postMessage

signInWithOAuth(provider, options?)

Initiates OAuth sign-in flow.

Parameters:

Parameter	Type	Description
provider	"google" | "apple"	OAuth provider
options.redirect_uri	string	Custom redirect URI (defaults to window.location.origin)
options.extraParams	Record<string, string>	Additional params to send to the OAuth broker

Returns: Promise<SignInWithOAuthResult>

Types

interface OAuthTokens {
  access_token: string;
  refresh_token: string;
}

interface LovableAuthConfig {
  oauthBrokerUrl?: string;
  supportedOAuthOrigins?: string[];
}

interface SignInWithOAuthOptions {
  redirect_uri?: string;
  extraParams?: Record<string, string>;
}

type SignInWithOAuthResult =
  | { tokens: OAuthTokens; error: null; redirected?: false }
  | { tokens?: undefined; error: Error; redirected?: false }
  | { tokens?: undefined; error: null; redirected: true };

License

MIT