[@clerk/express] Bug Report: Error When Parsing UserJSON to User

[LuccaRebelloToledo]

Preliminary Checks

• I have reviewed the documentation: https://clerk.com/docs

• I have searched for existing issues: https://github.com/clerk/javascript/issues

• I have not already reached out to Clerk support via email or Discord (if you have, no need to open an issue here)

• This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.

Reproduction

Zip

Publishable key

pk_test_c2V0LXR1bmEtNzUuY2xlcmsuYWNjb3VudHMuZGV2JA

Description

Steps to reproduce:

1. Create a Webhook with Event Types (user.created or user.updated).
2. Receive the UserJSON from the webhook.
3. Attempt to parse UserJSON into User.

Expected behavior:

The UserJSON should successfully convert into a User object.

Actual behavior:

An error occurs:

'User' cannot be used as a value because it was exported using 'export type'.
index.d.ts(28, 283): 'User' was exported here.

clerk-use-case.zip

Environment

System:
    OS: Windows 11 10.0.26100
    CPU: (16) x64 AMD Ryzen 7 5700X3D 8-Core Processor
    Memory: 18.42 GB / 31.93 GB
  Binaries:
    Node: 22.13.0 - C:\nvm4w\nodejs\node.EXE
    npm: 11.0.0 - C:\nvm4w\nodejs\npm.CMD
    pnpm: 9.15.4 - C:\nvm4w\nodejs\pnpm.CMD
  Browsers:
    Edge: Chromium (131.0.2903.146)
  npmPackages:
    @clerk/express: ^1.3.31 => 1.3.31

[Nelwhix]

Hi @LuccaRebelloToledo, after reviewing the code I don't think the User type is meant to be used that way. It is probably provided for internal use. Is there a reason why you can't use the userEvent variable directly? but if you absolutely want to deal with user types what if you do it this way:

import { clerkClient } from "@clerk/express";

app.post("/webhook", async (req, res) => {
  try {
    const userEvent = req.body;
    console.log("User Event:", userEvent);

    const userId = userEvent.id;

    const user = await clerkClient.users.getUser(userId);
    console.log("Fetched User:", user);

    res.status(200).send("Webhook received");
  } catch (error) {
    console.error("Error processing webhook:", error);
    res.status(500).send("Internal server error");
  }
});

[LuccaRebelloToledo]

Hey @Nelwhix, how are you? In the project I'm working on, I use many methods that take the User type as a parameter. It would be unfeasible for me to convert all the methods to use UserJSON. Also, if there was an update, I would have to update twice :/

Therefore, converting JSON to the User class ends up being quite important to me and will minimize requests in Clerk, consequently reducing costs.

[wobsoriano]

Related to #5058

[wobsoriano]

Hello @LuccaRebelloToledo! Sorry for the delay in getting back to you. After reviewing your issue and the related PR (#5058), I'd like to suggest a different approach.

Instead of trying to convert the webhook payload into a User type (w/c we exported as a type on purpose), I recommend extracting only the specific properties you need for your use case, which makes your code more explicit about what data it needs and more maintainable.

For example, if your functions need specific user properties, you could do:

app.post('/webhook', async (req, res) => {
  const userData: UserJSON = req.body
  
  // Extract only the properties you need
  const { id, email_addresses, first_name, last_name } = userData

  type UserData = {...}

  // Pass this to your functions instead
  const userInfo: UserData = {
    userId: id,
    emails: email_addresses,
    firstName: first_name,
    lastName: last_name
  }

  await handleUserAction(userInfo)
})