web — EdgeSpark browser SDK - EdgeSpark Documentation

@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.

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/*.

CLI

SDK

Platform

web — EdgeSpark browser SDK

Create the client

`client.auth`

`client.api.fetch`

`client.authUI`

Redirect mode

Controlled mode

Error classes

Redirect targets

Locale presets

See also

Build auth UI

Authenticate users

​Create the client

​client.auth

​client.api.fetch

​client.authUI

​Redirect mode

​Controlled mode

​Error classes

​Redirect targets

​Locale presets

​See also

Build auth UI

Authenticate users

Create the client

`client.auth`

`client.api.fetch`

`client.authUI`

Redirect mode

Controlled mode

Error classes

Redirect targets

Locale presets

See also