The StackApp Object

By now, you may have seen the useApp() hook and the stackServerApp variable. Both return a StackApp, of type StackClientApp and StackServerApp respectively.

Nearly all of Stack’s functionality is on your StackApp object. Think of this object as the “connection” from your code to Stack’s servers. Each app is always associated with one specific project ID (by default the one found in your environment variables).

There is also a page on StackApp in the SDK reference, which lists all available functions.

getXyz/listXyz vs. useXyz

You will see that most of the asynchronous functions on StackApp come in two flavors: getXyz/listXyz and useXyz. The former are asynchronous fetching functions which return a Promise, while the latter are React hooks that suspend the current component until the data is available.

Normally, you would choose between the two based on whether you are in a React Server Component or a React Client Component. However, there are some scenarios where you use getXyz on the client, for example as the callback of an onClick handler.

1
// server-component.tsx
2
async function ServerComponent() {
3
  const app = stackServerApp;
4
  // returns a Promise, must be awaited
5
  const user = await app.getUser();
6
7
  return <div>{user.displayName}</div>;
8
}
9
10
11
// client-component.tsx
12
"use client";
13
function ClientComponent() {
14
  const app = useApp();
15
  // returns the value directly
16
  const user = app.useUser();
17
18
  return <div>{user.displayName}</div>;
19
}

Client vs. server

StackClientApp is the app which contains everything needed to build a frontend application, for example the own user object. It requires a publishable client key in its initialization (usually set by the NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY environment variable).

StackServerApp has all the functionality of StackClientApp, but also some server-only functions, eg. listing or modifying ALL users. This requires a secret server key (usually set by the STACK_SECRET_SERVER_KEY environment variable), which must always be kept secret.

There is also a third type, StackAdminApp, but it is rarely used. It is meant for internal tools that have special requirements, and can edit the Stack project configuration. This is useful for configuring Stack programmatically, for example with Terraform.