edgespark umbrella client: auth UI/APIs plus HTTP utilities.
Browser SDK for EdgeSpark BaaS - authentication + API client in one package.
``bash`
npm i @edgespark/client
> Note: This SDK is browser-only. It does not support Node.js or SSR environments.
`ts
import { createEdgeSpark } from "@edgespark/client";
import "@edgespark/client/styles.css";
const client = createEdgeSpark({ baseUrl: "https://api.example.com" });
// Option 1: Use managed login UI (recommended)
await client.auth.renderAuthUI(document.getElementById("auth")!, {
redirectTo: "/dashboard",
onLogin: (user) => console.log("Logged in!", user.email),
});
// Option 2: Build custom UI with direct API calls
await client.auth.signIn.email({ email, password });
const session = await client.auth.getSession();
// API requests (auth token auto-injected)
const res = await client.api.fetch("/api/users");
`
---
renderAuthUI provides a complete out-of-the-box authentication flow:
| Flow | Description |
|------|-------------|
| Sign In | Email/password login, OAuth (Google, etc.), anonymous temporary account |
| Sign Up | Email/password registration (handles email verification automatically) |
| Forgot Password | Send reset code → Enter code → Set new password |
| Email Verification | Send verification email after signup, supports resend |
The managed login UI is optimized for these container dimensions:
| Dimension | Value | Notes |
|-----------|-------|-------|
| Optimal width | 420px | Matches --edgespark-auth-card-width |320px
| Minimum width | | Mobile devices |width: 100%; max-width: 420px
| Responsive | | Recommended |
`html`
`ts
import { createEdgeSpark } from "@edgespark/client";
import "@edgespark/client/styles.css"; // Required
const client = createEdgeSpark({ baseUrl: "https://api.example.com" });
// Check if already logged in
const session = await client.auth.getSession();
if (session.data?.user) {
window.location.href = "/dashboard";
} else {
// Render login UI
await client.auth.renderAuthUI(document.getElementById("auth")!, {
redirectTo: "/dashboard",
onError: (error) => console.error("Auth error:", error),
});
}
`
`tsx
import { useRef, useEffect } from "react";
import { createEdgeSpark } from "@edgespark/client";
import "@edgespark/client/styles.css";
// Create client outside component (singleton)
const client = createEdgeSpark({ baseUrl: "https://api.example.com" });
export function AuthPage() {
const ref = useRef
useEffect(() => {
if (!ref.current) return;
// Check login status first
client.auth.getSession().then((session) => {
if (session.data?.user) {
window.location.href = "/dashboard";
return;
}
client.auth.renderAuthUI(ref.current!, {
redirectTo: "/dashboard",
});
});
}, []);
return
;// Dashboard page - get user info here
export function DashboardPage() {
const [user, setUser] = useState(null);
useEffect(() => {
client.auth.getSession().then((session) => {
if (!session.data?.user) {
window.location.href = "/login";
return;
}
setUser(session.data.user);
});
}, []);
if (!user) return
$3
Override default labels via the
parameter (partial override supported):`ts
await client.auth.renderAuthUI(container, {
labels: {
// Common labels
common: {
continueButton: "Continue",
backButton: "Back",
unknownError: "Something went wrong, please try again",
},
// Sign in page
signIn: {
title: "Welcome Back",
subtitle: "Sign in to continue",
emailPlaceholder: "Enter your email",
passwordPlaceholder: "Enter your password",
loginButton: "Sign In",
forgotPassword: "Forgot password?",
signUpPrompt: "Don't have an account?",
toggleToSignUp: "Sign up now",
guestPrompt: "Not ready to sign up?",
guestLinkText: "Continue with temporary account",
},
// Sign up page
signUp: {
title: "Create Account",
subtitle: "Sign up to get started",
emailPlaceholder: "Enter your email",
passwordPlaceholder: "Enter your password",
confirmPasswordPlaceholder: "Confirm your password",
signUpButton: "Sign Up",
toggleToSignIn: "Already have an account?",
toggleToSignInLink: "Sign in now",
},
// Verification code page
verifyCode: {
title: "Enter Verification Code",
sentTo: "Code sent to",
resendCode: "Resend",
resendCountdown: "Resend in {seconds}s", // {seconds} is a placeholder
},
// Reset password
resetPassword: {
title: "Reset Password",
subtitle: "Enter your email to receive a reset code",
sendResetButton: "Send Reset Code",
backToSignIn: "Back to sign in",
},
// Set new password
setNewPassword: {
title: "Set New Password",
subtitle: "Code sent to",
newPasswordLabel: "New password",
confirmPasswordLabel: "Confirm password",
setPasswordButton: "Set Password",
},
// OAuth buttons
oauth: {
googleBtnName: "Continue with Google",
githubBtnName: "Continue with GitHub",
},
// Error messages (override backend error codes)
errors: {
INVALID_EMAIL_OR_PASSWORD: "Invalid email or password",
INVALID_EMAIL: "Invalid email format",
PASSWORD_MISMATCH: "Passwords do not match",
PASSWORD_TOO_SHORT: "Password is too short",
USER_ALREADY_EXISTS: "This email is already registered",
EMAIL_NOT_VERIFIED: "Email not verified, please check your inbox",
INVALID_OTP: "Invalid verification code",
OTP_EXPIRED: "Verification code has expired",
TOO_MANY_ATTEMPTS: "Too many attempts, please try again later",
},
// Success page
success: {
title: "Success!",
continueButton: "Continue",
},
// iframe OAuth modal (for preview page limitations)
iframeModal: {
titleTemplate: "Sign in with {provider}", // {provider} is a placeholder
messageTemplate: "Due to preview limitations, {provider} sign-in must be completed in a new tab.",
actionButton: "Open in New Tab",
},
},
});
`$3
All styles are scoped under
. Import the CSS and override via CSS variables:`css
/ In your CSS file /
[data-edgespark-auth] {
/ Colors /
--edgespark-auth-color-primary: rgba(0, 0, 0, 0.95);
--edgespark-auth-color-secondary: rgba(0, 0, 0, 0.65);
--edgespark-auth-color-tertiary: rgba(0, 0, 0, 0.45);
--edgespark-auth-color-text: rgba(0, 0, 0, 0.95);
--edgespark-auth-color-text-inverse: #ffffff;
--edgespark-auth-color-error: #dc2626;
--edgespark-auth-color-border: rgba(0, 0, 0, 0.12);
--edgespark-auth-color-bg: #ffffff;
--edgespark-auth-color-bg-secondary: rgba(0, 0, 0, 0.05);
--edgespark-auth-color-bg-link: #0077ff; / Typography /
--edgespark-auth-font-family: 'Roboto Flex', -apple-system, sans-serif;
--edgespark-auth-font-size-title: 32px;
--edgespark-auth-font-size-body: 14px;
--edgespark-auth-font-size-small: 12px;
/ Sizing & Border Radius /
--edgespark-auth-radius-card: 30px;
--edgespark-auth-radius-input: 12px;
--edgespark-auth-radius-button: 999px;
--edgespark-auth-spacing: 16px;
--edgespark-auth-input-height: 48px;
--edgespark-auth-button-height: 48px;
--edgespark-auth-card-width: 420px;
}
`---
Custom UI
If the managed UI doesn't meet your needs, call
APIs directly to build your own UI.client.auth is based on better-auth client and supports all better-auth methods.$3
`ts
// Email/password sign in
const result = await client.auth.signIn.email({
email: "user@example.com",
password: "password",
});if (result.error) {
console.error("Sign in failed:", result.error.message);
} else {
console.log("Sign in successful:", result.data);
}
// OAuth sign in (redirects to third-party page)
await client.auth.signIn.social({
provider: "google",
callbackURL: "/dashboard", // Redirect after success
});
// Anonymous temporary account (requires backend support)
await client.auth.signIn.anonymous();
`$3
ts
const result = await client.auth.signUp.email({
name: "John Doe",
email: "john@example.com",
password: "password",
callbackURL: "/verify-email", // Link destination in verification email
});if (result.error) {
console.error("Sign up failed:", result.error.message);
}
`$3
ts
// Get current logged-in user's session
const session = await client.auth.getSession();if (session.data) {
console.log("User info:", session.data.user);
console.log("Session:", session.data.session);
} else {
console.log("Not logged in");
}
`$3
ts
await client.auth.signOut();
`$3
ts
// 1. Send reset code to email
await client.auth.forgetPassword.emailOtp({
email: "user@example.com",
});// 2. Set new password with verification code
const result = await client.auth.emailOtp.resetPassword({
email: "user@example.com",
otp: "123456",
password: "newpassword",
});
if (result.error) {
console.error("Reset failed:", result.error.message);
}
`$3
ts
// Listen to auth state changes (login/logout/token refresh)
const unsubscribe = client.auth.onAuthStateChange(() => {
// Get latest session when state changes
client.auth.getSession().then((session) => {
if (session?.data?.user) {
console.log("Logged in", session.data.user);
} else {
console.log("Logged out");
}
});
});// Unsubscribe
unsubscribe();
`---
API Module
is fetch with auto-injected auth token:`ts
// GET
const res = await client.api.fetch("/api/users");
const users = await res.json();// POST
const res = await client.api.fetch("/api/posts", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title: "Hello" }),
});
`> Security Note: Token is only injected for same-origin requests (same domain as
). Cross-origin requests will not include the token automatically.---
Lifecycle & Best Practices
$3
Always check if user is already logged in before rendering the login UI:
`ts
const session = await client.auth.getSession();
if (session.data?.user) {
// Already logged in, redirect to dashboard
window.location.href = "/dashboard";
return;
}// Not logged in, render login UI
await client.auth.renderAuthUI(container, {
redirectTo: "/dashboard",
});
`$3
After redirect, use
on the target page - this is the recommended way to get user info:`ts
// /dashboard page
const session = await client.auth.getSession();
if (!session.data?.user) {
window.location.href = "/login";
return;
}
console.log("Welcome", session.data.user.name);
`$3
| API | Use Case | Notes |
|-----|----------|-------|
|
| Recommended: Get current user info | Works everywhere, async |
| onLogin | Quick sync ops (analytics, logging) | Not called for OAuth; fires before redirect |
| onAuthStateChange | Advanced: real-time auth monitoring | Need manual unsubscribe; fires on any token change |$3
`tsx
// ✅ Create client outside component (singleton)
const client = createEdgeSpark({ baseUrl: "..." });function AuthPage() {
const ref = useRef(null);
useEffect(() => {
if (!ref.current) return;
// Check if already logged in
client.auth.getSession().then((session) => {
if (session.data?.user) {
window.location.href = "/dashboard";
return;
}
// Render login UI
client.auth.renderAuthUI(ref.current!, {
redirectTo: "/dashboard",
});
});
// No need to destroy - renderAuthUI auto-cleans previous UI
}, []);
return
;
}
`$3
ts
// Destroy client (cleanup UI, event listeners, etc.)
client.destroy();// Also clear locally stored token
client.destroy({ clearToken: true });
`> Note: Only call
when the entire app unmounts, not on component unmount.---
API Reference
$3
Creates an EdgeSpark client. Initialization is synchronous.
| Option | Type | Description |
|--------|------|-------------|
|
baseUrl | string | Backend URL (required) |
| fetchCredentials | RequestCredentials | Fetch credentials mode, default "include" |$3
Authentication client based on better-auth. Main methods:
| Method | Description |
|--------|-------------|
|
signIn.email({ email, password }) | Email/password sign in |
| signIn.social({ provider, callbackURL }) | OAuth sign in |
| signIn.anonymous() | Anonymous sign in |
| signUp.email({ name, email, password }) | Email sign up |
| signOut() | Sign out |
| getSession() | Get current session/user info |
| forgetPassword.emailOtp({ email }) | Send password reset code |
| emailOtp.resetPassword({ email, otp, password }) | Reset password with code |
| renderAuthUI(container, options) | Render managed login UI |
| onAuthStateChange(listener) | Listen to token changes |$3
| Method | Description |
|--------|-------------|
|
fetch(path, options?) | Fetch with auth token |$3
Options for
renderAuthUI:| Option | Type | Description |
|--------|------|-------------|
|
redirectTo | string | Redirect URL after login (simple mode) |
| redirects | RedirectOptions | Fine-grained redirect config (overrides redirectTo) |
| labels | Partial | Custom labels |
| onLogin | (user) => void | Optional: for quick sync ops like analytics (not called for OAuth) |
| onError | (error) => void | Error callback |$3
`ts
interface RedirectOptions {
oauth?: {
success?: string; // OAuth login success
newUser?: string; // OAuth first-time signup
error?: string; // OAuth error
};
emailPassword?: string; // Email/password login success
emailVerification?: string; // Email verification link destination
anonymous?: string; // Anonymous login success
}
`---
Build
bash
npm run build # Build
npm run dev # Run example (examples/dev)
``