Users
Reading and writing user information, and protecting pages
You will inevitably build custom components that access the user in one way or another. In this section, we will take a closer look at the functions and hooks that let you do this.
Client Component basics
The useUser()
hook returns the current user in a Client Component. By default, it will return null
if the user is not signed in.
The useUser()
hook is simply a shorthand for useStackApp().useUser()
. useStackApp()
also contains other useful hooks and methods for clients, which will be described later.
Sometimes, you want to retrieve the user only if they’re signed in, and redirect to the sign-in page otherwise. In this case, simply pass { or: "redirect" }
, and the function will never return null
.
Server Component basics
Since useUser()
is a stateful hook, you can’t use it on server components. Instead, you can import stackServerApp
from stack.ts
and call getUser()
:
Since useUser()
is a hook, it will re-render the component on user changes (eg. signout), while getUser()
will only fetch the user once (on page load). You can also call useStackApp().getUser()
on the client side to get the user in a non-component context.
Protecting a page
There are three ways to protect a page: in Client Components with useUser({ or: "redirect" })
, in Server Components with await getUser({ or: "redirect" })
, or with middleware.
On Client Components, the useUser({ or: 'redirect' })
hook will redirect the user to the sign-in page if they are not logged in. Similarly, on Server Components, call await getUser({ or: "redirect" })
to protect a page (or component).
Middleware can be used whenever it is easy to tell whether a page should be protected given just the URL, for example, when you have a /private
section only accessible to logged-in users.
Middleware
Client Component
Server Component
If you have sensitive information hidden in the page HTML itself, be aware of Next.js differences when using Server vs. Client Components.
-
Client Components: Client components are always sent to the browser, regardless of page protection. This is standard Next.js behavior. For more information, please refer to the Next.js documentation.
-
Server Components: If a component is protected, it is guaranteed that its bundled HTML will not be sent to the browser if the user is not logged in. However, this is not necessarily true for its children and the rest of the page, as Next.js may split components on the same page and send them to the client separately for performance.
For example, if your page is
<Parent><Child /></Parent>
, whereParent
is protected andChild
is not, Next.js may still send<Child />
to the browser even if the user is not logged in. (Normal browsers will never display it, but attackers may be able to retrieve it.) Notably, this also applies to unprotected pages inside protected layouts.To remediate this, every component/page that contains sensitive information should protect itself, instead of relying on an outer layout. This is good practice anyways; it prevents you from accidentally exposing the data.
-
Middleware: Because middleware runs on the edge, it ensures that the protected URLs are not accessible to anyone who is not authorized, so you don’t have to worry about Next.js pre-sending unprotected components to the client.
Irregardless of which method you use, attackers will never be able to, say, impersonate a user.
User metadata
You can update attributes on a user object with the user.update()
function.
You can store custom data in the clientMetadata
field. It will be readable and writable by the user themselves and should not contain any sensitive information.
You can then read the clientMetadata
field from the User
object:
If you want to store sensitive information, you can use the serverMetadata
field. This data is only readable & writable from the server.
If you want to store some information that is writable by the server but only readable by the client, you can use the clientReadOnlyMetadata
field. This is useful for things like subscription status, where the client needs to know the status but shouldn’t be able to change it.
Signing out
You can sign out the user by redirecting them to /handler/sign-out
or simply by calling user.signOut()
. They will be redirected to the URL configured as afterSignOut
in the StackServerApp
.
user.signOut()
Redirect
Example: Custom profile page
Stack automatically creates a user profile on sign-up. Let’s build a page that displays this information. In app/profile/page.tsx
:
Client Component
Server Component
After saving your code, you can see the profile page on http://localhost:3000/profile.
For more examples on how to use the User
object, check the CurrentUser object in the SDK documentation.
Next steps
In the next guide, we will show you how to put your application into production.