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.

@edgespark/web is the browser SDK used by the current EdgeSpark scaffold. It is:
  • browser-only
  • same-origin only
  • cookie-session only
  • zero-config
It is meant for browser apps only. Do not use it in server code.

​
Create the client

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

export const client = createEdgeSpark();
createEdgeSpark() takes no options.

​
client.auth

client.auth keeps the familiar Better Auth method shape and adds EdgeSpark session helpers.
web/src/lib/session.ts
import { client } from "@/lib/edgespark";

export async function requireUser() {
  const session = await client.auth.requireSession();
  return session.user;
}

export function watchSession() {
  return client.auth.onSessionChange((session) => {
    console.log(session?.user.email ?? "signed out");
  });
}
You can also call the standard auth methods directly:
web/src/lib/auth.ts
import { client } from "@/lib/edgespark";

await client.auth.signIn.email({ email, password });
await client.auth.signUp.email({ name, email, password });
await client.auth.signOut();
await client.auth.getSession();
Current platform note:
  • changeEmail()
  • deleteUser()
still exist on the familiar auth surface, but they are not currently enabled by the platform and fail fast with UNSUPPORTED_AUTH_METHOD.

​
client.api.fetch

Use client.api.fetch(...) for app requests from the browser:
web/src/lib/load-profile.ts
import { client } from "@/lib/edgespark";

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

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

  return response.json();
}
The wrapper always sends cookie credentials and rejects cross-origin URLs.

​
client.authUI

Use the managed auth UI when you want EdgeSpark to render login, sign-up, verification, OAuth, and password reset flows.

​
Redirect mode

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

​
Controlled mode

const mounted = client.authUI.mount(container, {
  onSuccess(event) {
    if (event.action !== "password-reset") {
      window.location.assign("/dashboard");
    }
  },
  onError(error) {
    console.error(error.code, error.message);
  },
});
Destroy the mounted UI when the container is going away: 
mounted.destroy();
Password reset is the one special completion case:
  • in controlled mode, onSuccess({ action: "password-reset" }) fires and your app decides what to do next
  • in redirect mode, the UI returns to sign-in with a success notice instead of redirecting to an authenticated page

​
Error classes

@edgespark/web exports normalized error classes you can catch explicitly: 
import { EdgeSparkAuthError, EdgeSparkConfigError } from "@edgespark/web";
  • EdgeSparkAuthError for auth failures such as rejected sign-in or missing session
  • EdgeSparkConfigError for bad inputs such as invalid redirect targets or cross-origin fetches
  • EdgeSparkRuntimeError when called outside a browser runtime

​
Redirect targets

redirectTo can be a relative path or absolute URL: 
client.authUI.mount(container, {
  redirectTo: "/dashboard",
});
It must resolve to a valid http: or https: URL.

​
Locale presets

The managed UI auto-detects labels from the browser by default. Import a preset only when you want to force a specific language: 
import { createEdgeSpark, fr } from "@edgespark/web";

const client = createEdgeSpark();

client.authUI.mount(container, {
  redirectTo: "/dashboard",
  labels: fr,
});
The package also exports detectLocale() if you want the same browser-language detection logic outside the managed UI.

​
See also

Build auth UI

Mount the managed UI in a real app and wire redirect or controlled flows.

Authenticate users

Server-side auth rules for /api/*, /api/public/*, and /api/webhooks/*.
Last modified on April 7, 2026