Users

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.

1
"use client";
2
import { useUser } from "@stackframe/stack"
3
4
export function MyClientComponent() {
5
  const user = useUser();
6
  return <div>{user ? `Hello, ${user.displayName ?? "anon"}` : 'You are not logged in'}</div>;
7
}

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.

1
  const user = useUser({ or: "redirect" });
2
  return <div>{`Hello, ${user.displayName ?? "anon"}`}</div>;

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():

1
import { stackServerApp } from "@/stack";
2
3
export default async function MyServerComponent() {
4
  const user = await stackServerApp.getUser();  // or: stackServerApp.getUser({ or: "redirect" })
5
  return <div>{user ? `Hello, ${user.displayName ?? "anon"}` : 'You are not logged in'}</div>;
6
}

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.

1
export async function middleware(request: NextRequest) {
2
  const user = await stackServerApp.getUser();
3
  if (!user) {
4
    return NextResponse.redirect(new URL('/handler/sign-in', request.url));
5
  }
6
  return NextResponse.next();
7
}
8
9
export const config = {
10
  // You can add your own route protection logic here
11
  // Make sure not to protect the root URL, as it would prevent users from accessing static Next.js files or Stack's /handler path
12
  matcher: '/protected/:path*',
13
};

User metadata

You can update attributes on a user object with the user.update() function.

1
'use client';
2
import { useUser } from "@stackframe/stack";
3
4
export default function MyClientComponent() {
5
  const user = useUser();
6
  return <button onClick={async () => await user.update({ displayName: "New Name" })}>
7
    Change Name
8
  </button>;
9
}

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.

1
await user.update({
2
  clientMetadata: {
3
    mailingAddress: "123 Main St",
4
  },
5
});

You can then read the clientMetadata field from the User object:

1
const user = useUser();
2
console.log(user.clientMetadata);

If you want to store sensitive information, you can use the serverMetadata field. This data is only readable & writable from the server.

1
const user = await stackServerApp.getUser();
2
await user.update({
3
  serverMetadata: {
4
    secretInfo: "This is a secret",
5
  },
6
});
7
8
// later:
9
const user = await stackServerApp.getUser();
10
console.log(user.serverMetadata);

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.

1
// On the server:
2
const user = await stackServerApp.getUser();
3
await user.update({
4
  clientReadOnlyMetadata: {
5
    subscriptionPlan: "premium",
6
  },
7
});
8
9
// On the client:
10
const user = useUser();
11
console.log(user.clientReadOnlyMetadata);

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.

1
"use client";
2
import { useUser } from "@stackframe/stack";
3
4
export default function SignOutButton() {
5
  const user = useUser();
6
  return user ? <button onClick={() => user.signOut()}>Sign Out</button> : "Not signed in";
7
}

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:

1
'use client';
2
import { useUser, useStackApp, UserButton } from "@stackframe/stack";
3
4
export default function PageClient() {
5
  const user = useUser();
6
  const app = useStackApp();
7
  return (
8
    <div>
9
      {user ? (
10
        <div>
11
          <UserButton />
12
          <p>Welcome, {user.displayName ?? "anonymous user"}</p>
13
          <p>Your e-mail: {user.primaryEmail}</p>
14
          <button onClick={() => user.signOut()}>Sign Out</button>
15
        </div>
16
      ) : (
17
        <div>
18
          <p>You are not logged in</p>
19
          <button onClick={() => app.redirectToSignIn()}>Sign in</button>
20
          <button onClick={() => app.redirectToSignUp()}>Sign up</button>
21
        </div>
22
      )}
23
    </div>
24
  );
25
}

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.