Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.edgespark.dev/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
See also

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.
Last modified on April 16, 2026