StackApp
This is a detailed reference for the StackApp
object. Here is a more high-level overview.
Different types of StackApp
objects
Stack offers two types of app objects: StackClientApp
and StackServerApp
.
-
StackClientApp
:- Designed for client-side applications
- Provides functionality like
signInWithOAuth
,useUser
,useProject
, etc. - Obtain it by calling
useStackApp()
in a Client Component
-
StackServerApp
:- extends
StackClientApp
- Has additional capabilities like being able to listing all the users in the project
- Access it by importing the object from the file where you created it (
import { stackServerApp } from '@/stack'
) - While
StackServerApp
includesuseXYZ
hooks, they are generally not usable in server-side code due to its non-reactive nature. These hooks are primarily designed for client-side use where reactivity is supported.
- extends
Choose the appropriate type based on your application’s needs and environment.
StackClientApp
You can get a StackClientApp
instance by calling useStackApp()
in a Client Component.
Initialization
In most cases, we don’t create a StackClientApp
directly. Instead, we typically:
- Create a
StackServerApp
instance, pass it into theStackProvider
component - Use the
useStackApp()
hook to obtain aStackClientApp
from it
Check out the manual setup guide for more details. For details on how to initialize a StackServerApp
, refer to the StackServerApp section below.
Properties
The ID of the project that the app is associated with.
The URLs that Stack uses to route and redirect.
The URL of the home page.
The URL of the sign-in page.
The URL that the user will be redirected to after successful signing in.
The URL of the sign-up page.
The URL that the user will be redirected to after successful signing up.
The URL that the user will be redirected to after successful signing out.
The URL of the email verification page.
The URL of the password reset page.
The URL of the forgot password page.
The URL of the account settings page.
The URL of the handler root.
getUser()
Get the current user.
Parameters:
What to do if the user is not signed in. Can be:
"redirect"
: Redirects the user to thesignIn
URL."throw"
: Throws an error.
Returns:
- If
or
is not provided, returnsPromise<CurrentUser | null>
. - If
or
is"redirect"
or"throw"
, always returnsPromise<CurrentUser>
.
Example:
useUser()
Get the current user.
This is the same as getUser()
but it is a React hook. The useUser
hook imported from the package is an alias for this function.
Parameters:
What to do if the user is not signed in. Can be:
"redirect"
: Redirects the user to thesignIn
URL."throw"
: Throws an error.
Returns:
- If
or
is not provided, returnsCurrentUser | null
. - If
or
is"redirect"
or"throw"
, always returnsCurrentUser
.
Example:
signInWithOAuth()
Initiates the OAuth sign-in process with the specified provider. This method:
- Redirects the user to the OAuth provider’s sign-in page.
- After successful authentication, redirects the user back to your application.
- The final redirect destination is determined as follows:
- If an
after_auth_return_to
query parameter was provided when calling this function, it uses that URL. - Otherwise, it uses the
afterSignIn
URL configured in the app settings.
- If an
Parameters:
The type of the OAuth provider to sign in with.
Returns:
Promise<void>
: A promise that resolves when the redirect is complete.
Example:
signInWithCredential()
Sign in using email and password credentials. The behavior is as follows:
-
If sign-in is successful:
- By default, redirects the user to the
afterSignIn
URL. - If
after_auth_return_to
is provided in the query parameters, redirects to that URL instead. - If
noRedirect
is set totrue
, it will not redirect and instead return a successResult
object.
- By default, redirects the user to the
-
If sign-in fails:
- No redirection occurs.
- Returns a
Result
object containing error information.
Parameters:
The email of the user to sign in with.
The password of the user to sign in with.
Whether to not redirect the user after sign-in. Defaults to false
.
Returns:
Promise<Result<undefined, KnownErrors["EmailPasswordMismatch"]>>
: A promise that resolves to a Result
object.
Example:
signUpWithCredential()
Sign up using email and password credentials. The behavior is as follows:
-
If sign-up is successful:
- By default, redirects the user to the
afterSignUp
URL. - If
after_auth_return_to
is provided in the query parameters, redirects to that URL instead. - If
noRedirect
is set totrue
, it will not redirect and instead return a successResult
object.
- By default, redirects the user to the
-
If sign-up fails:
- No redirection occurs.
- Returns a
Result
object containing error information.
Parameters:
The email of the user to sign up with.
The password of the user to sign up with.
Whether to not redirect the user after sign-up. Defaults to false
.
Returns:
Promise<Result<undefined, KnownErrors["UserEmailAlreadyExists"] | KnownErrors["PasswordRequirementsNotMet"]>>
: A promise that resolves to a Result
object.
Example:
sendForgotPasswordEmail()
Send a forgot password email to an email address.
Parameters:
The email of the user to send the forgot password email to.
Returns:
Promise<Result<undefined, KnownErrors["UserNotFound"]>>
: A promise that resolves to a Result
object.
Example:
sendMagicLinkEmail()
Send a magic link/OTP sign-in email to an email address.
Parameters:
The email of the user to send the magic link email to.
Returns:
Promise<Result<{ nonce: string }, KnownErrors["RedirectUrlNotWhitelisted"]>>
: A promise that resolves to a Result
object.
Example:
getProject()
Get the current project.
Parameters:
No parameters.
Returns:
Promise<Project>
: The current project.
Example:
useProject()
Get the current project.
This is the same as getProject()
but it is a React hook. The useProject
hook imported from the package is an alias for this function.
Parameters:
No parameters.
Returns:
Project
: The current project.
Example:
StackServerApp
StackServerApp
extends StackClientApp
, so it has all the same capabilities, plus some extra ones listed below.
Note that although the useXYZ
hooks are available on StackServerApp
, they are generally not usable in server-side code due to its non-reactive nature. These hooks are primarily designed for client-side use where reactivity is supported.
Initialization
Parameters:
Where to store the auth tokens. Currently only "nextjs-cookie"
is supported.
Extra OAuth scopes to request when signing in. It is an object of format { [provider: string]: string[] }
, where the key is the provider type (e.g. "google"
, "apple"
, etc.) and the value is an array of scopes to request. Checkout the OAuth page for more details.
The base URL of the Stack server. By default it is read from the NEXT_PUBLIC_STACK_URL
environment variable if it exists, or use https://api.stack-auth.com
if it doesn’t.
The ID of the project to use. By default it is read from the NEXT_PUBLIC_STACK_PROJECT_ID
environment variable.
The publishable client key to use. By default it is read from the NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY
environment variable.
The secret server key to use. By default it is read from the STACK_SECRET_SERVER_KEY
environment variable.
Modify the URLs that Stack uses to route and redirect.
The URL of the home page.
The URL of the sign-in page.
The URL that the user will be redirected to after successful signing in.
The URL of the sign-up page.
The URL that the user will be redirected to after successful signing up.
The URL that the user will be redirected to after successful signing out.
The URL of the email verification page.
The URL of the password reset page.
The URL of the forgot password page.
The URL of the account settings page.
The URL of the handler root. When changing this, you should also change the location of the StackHandler
component and the domain handler path on the dashboard. Currently putting the handler at the root /
is not supported.
Example:
Properties
Same as StackClientApp
.
getUser()
Get a user. There are two overloads:
Overload 1 (get current server user):
Parameters:
What to do if the user is not signed in. Can be:
"redirect"
: Redirects the user to thesignIn
URL."throw"
: Throws an error.
Returns:
- If
or
is not provided, returnsPromise<ServerUser | null>
. - If
or
is"redirect"
or"throw"
, always returnsPromise<ServerUser>
.
Example:
Overload 2 (get user by ID):
Parameters:
The ID of the user to get.
Returns:
Promise<ServerUser | null>
: The user, or null if not found.
Example:
listUsers()
List all users.
Returns:
Promise<ServerUser[]>
: The list of users.
Example:
createUser()
Create a new user.
Parameters:
The primary email of the user to create.
Whether the primary email is enabled. When using password or otp auth, this must be set to true
, otherwise the user will not be able to sign in.
The password for the new user. An error will be thrown if a password is provided but password authentication is not enabled for the project in the dashboard.
Enables OTP (One-Time Password) or magic link sign-in using the primary email.
Note: Only verified emails can be used for OTP sign-in. An error will be thrown
if set to true
when OTP authentication is not enabled in the dashboard.
The display name of the user to create.
Whether the primary email is verified.
Returns:
Promise<ServerUser>
: The created user.
Example:
getTeam()
Get a team by ID.
Parameters:
The ID of the team to get.
Returns:
Promise<ServerTeam | null>
: The team, or null if not found.
Example:
listTeams()
List all teams.
Returns:
Promise<ServerTeam[]>
: The list of teams.
Example:
createTeam()
create a team without a user.
This is similar to user.createTeam()
, except it does not add the user to the team.
Parameters:
The display name for the team.
The URL of the team’s profile image (base64 image allowed, crop and compress before passing it in), or null to remove.
Returns:
Promise<ServerTeam>
: The created team.
Example: