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

# web — EdgeSpark browser SDK

> Use the @edgespark/web browser SDK for same-origin auth, managed auth UI, session helpers, errors, locales, and API requests.

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

```typescript web/src/lib/edgespark.ts theme={null}
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.

```typescript web/src/lib/session.ts theme={null}
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:

```typescript web/src/lib/auth.ts theme={null}
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:

```typescript web/src/lib/load-profile.ts theme={null}
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

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

### Controlled mode

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

<Columns cols={2}>
  <Card title="Build auth UI" icon="lock" href="/guides/auth-ui">
    Mount the managed UI in a real app and wire redirect or controlled flows.
  </Card>

  <Card title="Authenticate users" icon="user" href="/guides/authentication">
    Server-side auth rules for `/api/*`, `/api/public/*`, and `/api/webhooks/*`.
  </Card>
</Columns>