This is a detailed reference for the StackApp object. For setup instructions, see Setup.

Overview

HexclaveClientApp - Client-level permissions for frontend code
HexclaveServerApp - Server-level permissions with full access

HexclaveClientApp

A StackApp with client-level permissions. It contains most of the useful methods and hooks for your client-side code. Most commonly you get an instance of HexclaveClientApp by calling useHexclaveApp() in a Client Component.

type HexclaveClientApp = {
  new(options): HexclaveClientApp;

  getUser([options]): Promise<User>;
  useUser([options]): User;
  getProject(): Promise<Project>;
  useProject(): Project;

  signInWithOAuth(provider): void;
  signInWithCredential([options]): Promise<...>;
  signUpWithCredential([options]): Promise<...>;
  sendForgotPasswordEmail(email): Promise<...>;
  sendMagicLinkEmail(email): Promise<...>;

  initAnalytics(): void;
};

Constructor

Creates a new HexclaveClientApp instance. Because each app creates a new connection to Hexclave’s backend, you should re-use existing instances wherever possible.

This object is not usually constructed directly. More commonly, you would construct a HexclaveServerApp instead, pass it into your app setup (see the setup guide), and then use the useHexclaveApp() hook to obtain a HexclaveClientApp.The setup wizard does these steps for you, so you don’t need to worry about it unless you are manually setting up Hexclave.If you’re building a client-only app and don’t have a HEXCLAVE_SECRET_SERVER_KEY, you can construct a HexclaveClientApp directly.

User Management

`hexclaveClientApp.getUser([options])`

Gets the current user.

`hexclaveClientApp.useUser([options])`

React hook version of getUser(). Equivalent to the useUser() standalone hook, which is an alias for useHexclaveApp().useUser().

`hexclaveClientApp.getProject()`

Gets the current project.

`hexclaveClientApp.useProject()`

React hook version of getProject().

Authentication

`hexclaveClientApp.signInWithOAuth(provider)`

Initiates the OAuth sign-in process with the specified provider.

`hexclaveClientApp.signInWithCredential([options])`

`hexclaveClientApp.signUpWithCredential([options])`

`hexclaveClientApp.sendForgotPasswordEmail(email)`

Send a forgot-password email to an email address.

`hexclaveClientApp.sendMagicLinkEmail(email)`

Send a magic-link or OTP sign-in email to an email address.

Analytics

`hexclaveClientApp.initAnalytics()`

Marks the current page as one that should record analytics, including page views, clicks, session replays, and clickmaps.Call this at the top level of a client-side module that every page you want to track loads, such as your root layout or entry file. Analytics capture starts as soon as the client app is created in the browser, so the function doesn’t start anything itself. The call makes sure that the module creating the client app is loaded on every page, not just on pages that use authentication. See Tracking every page.Throws if the app is configured so that it never records analytics (analytics: { enabled: false }, automaticSideEffects: false, or a null token store). If the Analytics app is not enabled on the project, an error is logged as soon as the first upload is rejected.

HexclaveServerApp

Like HexclaveClientApp, but with server permissions. Has full read and write access to all users.

Since this functionality should only be available in environments you trust (ie. your own server), it requires a HEXCLAVE_SECRET_SERVER_KEY. In some cases, you may want to use a HexclaveServerApp on the client; an example for this is an internal dashboard that only your own employees have access to. We generally recommend against doing this unless you are aware of and protected against the (potentially severe) security implications of exposing HEXCLAVE_SECRET_SERVER_KEY on the client.

type HexclaveServerApp =
  // Inherits all functionality from HexclaveClientApp
  & HexclaveClientApp
  & {
    new(options): HexclaveServerApp;

    getUser([id][, options]): Promise<ServerUser | null>;
    useUser([id][, options]): ServerUser;
    listUsers([options]): Promise<ServerUser[] & { nextCursor: string | null }>;
    useUsers([options]): ServerUser[] & { nextCursor: string | null };
    createUser([options]): Promise<ServerUser>;
    sendEmail(options): Promise<Result<void, KnownErrors>>;

    getTeam(id): Promise<ServerTeam | null>;
    useTeam(id): ServerTeam;
    listTeams([options]): Promise<ServerTeam[] & { nextCursor: string | null }>;
    useTeams([options]): ServerTeam[] & { nextCursor: string | null };
    createTeam([options]): Promise<ServerTeam>;
  }

Constructor

Creates a new HexclaveServerApp instance.

User Operations

`hexclaveServerApp.getUser([id], [options])`

Enhanced version of HexclaveClientApp.getUser() with server permissions.Overloads:

getUser(id: string): Promise<ServerUser | null> to get a user by ID.
getUser(options?: { or?: "return-null" | "redirect" | "throw" }): Promise<CurrentServerUser | null> to get the current user.

The or: "redirect" overload is deprecated on both client and server app objects. The app type controls permissions, not whether the call runs in a browser. Use getUser() or { or: "throw" } for server-side authorization, and useUser({ or: "redirect" }) in a Client Component for navigation.

`hexclaveServerApp.useUser([id], [options])`

Functionally equivalent to getUser(), but as a React hook.

This should be used on the server-side only.

`hexclaveServerApp.listUsers([options])`

Lists all users on the project.

`hexclaveServerApp.useUsers([options])`

Functionally equivalent to listUsers(), but as a React hook.

This should be used on the server-side only.

`hexclaveServerApp.createUser([options])`

Creates a new user from the server.

`hexclaveServerApp.sendEmail(options)`

Send custom emails to users. You can send either custom HTML emails or use predefined templates with variables.

Team Management

`hexclaveServerApp.getTeam(id)`

Get a team by its ID.

`hexclaveServerApp.useTeam(id)`

Functionally equivalent to getTeam(id), but as a React hook.

This should be used on the server-side only.

`hexclaveServerApp.listTeams([options])`

Lists the teams on the current project.

`hexclaveServerApp.useTeams([options])`

Functionally equivalent to listTeams(), but as a React hook.

This should be used on the server-side only.

`hexclaveServerApp.createTeam([options])`

Creates a team without adding a user to it.

Objects

Types

Hooks

StackApp

Overview

HexclaveClientApp

Table of Contents

Constructor

User Management

`hexclaveClientApp.getUser([options])`

`hexclaveClientApp.useUser([options])`

`hexclaveClientApp.getProject()`

`hexclaveClientApp.useProject()`

Authentication

`hexclaveClientApp.signInWithOAuth(provider)`

`hexclaveClientApp.signInWithCredential([options])`

`hexclaveClientApp.signUpWithCredential([options])`

`hexclaveClientApp.sendForgotPasswordEmail(email)`

`hexclaveClientApp.sendMagicLinkEmail(email)`

Analytics

`hexclaveClientApp.initAnalytics()`

HexclaveServerApp

Table of Contents

Constructor

User Operations

`hexclaveServerApp.getUser([id], [options])`

`hexclaveServerApp.useUser([id], [options])`

`hexclaveServerApp.listUsers([options])`

`hexclaveServerApp.useUsers([options])`

`hexclaveServerApp.createUser([options])`

`hexclaveServerApp.sendEmail(options)`

Team Management

`hexclaveServerApp.getTeam(id)`

`hexclaveServerApp.useTeam(id)`

`hexclaveServerApp.listTeams([options])`

`hexclaveServerApp.useTeams([options])`

`hexclaveServerApp.createTeam([options])`

​Overview

​HexclaveClientApp

​Table of Contents

​Constructor

​User Management

​hexclaveClientApp.getUser([options])

​hexclaveClientApp.useUser([options])

​hexclaveClientApp.getProject()

​hexclaveClientApp.useProject()

​Authentication

​hexclaveClientApp.signInWithOAuth(provider)

​hexclaveClientApp.signInWithCredential([options])

​hexclaveClientApp.signUpWithCredential([options])

​hexclaveClientApp.sendForgotPasswordEmail(email)

​hexclaveClientApp.sendMagicLinkEmail(email)

​Analytics

​hexclaveClientApp.initAnalytics()

​HexclaveServerApp

​Table of Contents

​Constructor

​User Operations

​hexclaveServerApp.getUser([id], [options])

​hexclaveServerApp.useUser([id], [options])

​hexclaveServerApp.listUsers([options])

​hexclaveServerApp.useUsers([options])

​hexclaveServerApp.createUser([options])

​hexclaveServerApp.sendEmail(options)

​Team Management

​hexclaveServerApp.getTeam(id)

​hexclaveServerApp.useTeam(id)

​hexclaveServerApp.listTeams([options])

​hexclaveServerApp.useTeams([options])

​hexclaveServerApp.createTeam([options])

Overview

HexclaveClientApp

Table of Contents

Constructor

User Management

`hexclaveClientApp.getUser([options])`

`hexclaveClientApp.useUser([options])`

`hexclaveClientApp.getProject()`

`hexclaveClientApp.useProject()`

Authentication

`hexclaveClientApp.signInWithOAuth(provider)`

`hexclaveClientApp.signInWithCredential([options])`

`hexclaveClientApp.signUpWithCredential([options])`

`hexclaveClientApp.sendForgotPasswordEmail(email)`

`hexclaveClientApp.sendMagicLinkEmail(email)`

Analytics

`hexclaveClientApp.initAnalytics()`

HexclaveServerApp

Table of Contents

Constructor

User Operations

`hexclaveServerApp.getUser([id], [options])`

`hexclaveServerApp.useUser([id], [options])`

`hexclaveServerApp.listUsers([options])`

`hexclaveServerApp.useUsers([options])`

`hexclaveServerApp.createUser([options])`

`hexclaveServerApp.sendEmail(options)`

Team Management

`hexclaveServerApp.getTeam(id)`

`hexclaveServerApp.useTeam(id)`

`hexclaveServerApp.listTeams([options])`

`hexclaveServerApp.useTeams([options])`

`hexclaveServerApp.createTeam([options])`