Build auth UI with @edgespark/web

The current EdgeSpark scaffold uses @edgespark/web for frontend auth and API calls. It is a browser-only, same-origin SDK with cookie-based sessions, a managed auth UI, and a typed fetch wrapper for your app routes.

Create the browser client

The scaffold already creates a singleton in web/src/lib/edgespark.ts:

web/src/lib/edgespark.ts

import { createEdgeSpark } from "@edgespark/web";
import "@edgespark/web/styles.css";

export const client = createEdgeSpark();

createEdgeSpark() takes no options. It always uses the current page origin and always sends cookie credentials.

Mount the managed auth UI

Use client.authUI.mount(...) when you want EdgeSpark to handle sign-in, sign-up, email verification, OAuth entry points, and password reset UI for you.

Redirect mode

Use redirect mode for a dedicated /login page:

web/src/pages/LoginPage.tsx

import { useEffect, useRef } from "react";
import { client } from "@/lib/edgespark";

export function LoginPage() {
  const containerRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const mounted = client.authUI.mount(containerRef.current, {
      redirectTo: "/dashboard",
    });

    return () => {
      mounted.destroy();
    };
  }, []);

  return <div ref={containerRef} />;
}

After a successful sign-in or sign-up, the SDK redirects to /dashboard.

Controlled mode

Use controlled mode when the app owns the next step, such as closing a modal or navigating with a client router:

web/src/components/AuthModal.tsx

import { useEffect, useRef } from "react";
import { client } from "@/lib/edgespark";

interface AuthModalProps {
  onClose(): void;
}

export function AuthModal({ onClose }: AuthModalProps) {
  const containerRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const mounted = client.authUI.mount(containerRef.current, {
      onSuccess(event) {
        if (event.action !== "password-reset") {
          onClose();
        }
      },
      onError(error) {
        console.error(error.code, error.message);
      },
    });

    return () => {
      mounted.destroy();
    };
  }, [onClose]);

  return <div ref={containerRef} />;
}

In controlled mode, the SDK does not redirect for you.

Use headless auth methods

You can also call auth methods directly when you want custom forms:

web/src/lib/auth.ts

import { client } from "@/lib/edgespark";

export async function signIn(email: string, password: string) {
  const result = await client.auth.signIn.email({ email, password });

  if (result.error) {
    throw new Error(result.error.message ?? "Sign-in failed");
  }

  return result.data;
}

export async function signUp(name: string, email: string, password: string) {
  const result = await client.auth.signUp.email({ name, email, password });

  if (result.error) {
    throw new Error(result.error.message ?? "Sign-up failed");
  }

  return result.data;
}

The same client also exposes:

client.auth.getSession() for nullable session reads
client.auth.requireSession() for route guards that should throw when logged out
client.auth.onSessionChange(...) for hydration-safe session subscriptions
client.auth.signOut() for logout

Call your protected APIs

Use client.api.fetch(...) for same-origin app requests:

web/src/lib/load-posts.ts

import { client } from "@/lib/edgespark";

export async function loadPosts() {
  const response = await client.api.fetch("/api/posts");

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return response.json();
}

The wrapper always sends cookie credentials and rejects cross-origin URLs.

Let auth config drive the UI

The managed auth UI reads your project’s current auth configuration automatically. That means:

enabled OAuth providers appear automatically
sign-up availability follows disableSignUp
email verification and password reset behavior follow configs/auth-config.yaml

When you change auth config, use:

edgespark auth apply
edgespark deploy

See manage auth configuration for the config file format and provider key conventions, or add social OAuth login for per-provider setup walkthroughs.

web reference

The browser SDK reference for @edgespark/web, including auth, authUI, and api.fetch.

Manage auth configuration

Configure providers, sign-up policy, session settings, vars, and secret refs in configs/auth-config.yaml.

Getting started

Concepts

Build

Deploy

Create the browser client

Mount the managed auth UI

Redirect mode

Controlled mode

Use headless auth methods

Call your protected APIs

Let auth config drive the UI

See also

web reference

Manage auth configuration

​Create the browser client

​Mount the managed auth UI

​Redirect mode

​Controlled mode

​Use headless auth methods

​Call your protected APIs

​Let auth config drive the UI

​See also

web reference

Manage auth configuration

Create the browser client

Mount the managed auth UI

Redirect mode

Controlled mode

Use headless auth methods

Call your protected APIs

Let auth config drive the UI

See also