user.metadata is missing

[stepanh]

Describe the bug
I have metadata key display_name set on a user - I can see it on the Dashboard under "Custom metadata" but the user returned by useAuth hook doesn't include it.
I tried logging out and using Safari instead of Chrome, yet metadata still shows up empty.

To Reproduce

const { user } = useAuth();
console.log("user", user);
// logs the user but metadata is empty object
// metadata: {}

Expected behavior
Custom metadata is included.

Desktop (please complete the following information):

• OS: [MacOS]
• Browser [chrome, safari]
• authkit-nextjs version [2.3.2]
• Next.js version [15.3.2]

Additional context
externalId is returned on the user

[nicknisi]

Hey @stepanh, metadata is not in the response body of the User Authentication operations, though it is a bit confusing that metadata exists as an empty object.

zIf you want to publicly expose metadata properties from users or organizations in your access tokens, you can use JWT templates to customize claims in your application’s access tokens.

However, I think we can make this easier to access from authkit-nextjs, as currently you need to manually decode the token and get the properties off of it.

I'd propose we add a client-side useCustomClaims hook and a server-side getCustomClaims function.

Client access:

function ClientComponent() {
  const claims = useCustomClaims<{ 'urn:myapp:favorite_song': string; }>();

  return (
    <div>{claims?.['urn:myapp:favorite_song']}</div>
  );
}

Server access:

function ServerComponent() {
  const claims = await getCustomClaims<{ 'urn:myapp:favorite_song': string; }>();

  return (
    <div>{claims?.['urn:myapp:favorite_song']}</div>
  );
}

I've created a PR to add this new function and hook in #254. Thanks!

[stepanh]

Thank you @nicknisi , I guess that will work well.

Out of curiosity - why not go for the intuitive solution and just expose user.metadata?
I understand now that it's a choice inherited from https://github.com/workos/workos-node - but why not change the behaviour there? Performance reasons?