May 20, 2022
May 20, 2022
For optimal developer experience, React SDKs require completely different patterns than Node
This may be obvious but it must be stated as #1. Since React hooks run in the browser, SDKs cannot use secret keys for API access.
Instead, the API should be designed to scope access based on the currently signed-in user. Then, a session token or a JWT can be used to authorize requests to the API.
This is the critical change that turns a Node SDK into a React SDK. In Node SDKs, GET methods usually return a Promise:
Unfortunately, using a Promise in a React Component is a big headache. The developer needs to add
useState hooks to render a loading state while the Promise is pending, then update when the resolves.
The end result is quite verbose and hard to decipher:
The solution is to provide developers with a hook instead of a Promise. Hooks are composable, so under the hood this is still built with
useState, it just doesn't burden the developer with setting them up manually:
That's much easier to use!
There is still a problem in the example above. What if the user wants to change their name and the developer triggers an update:
By default, the
useUser hook in our
<UserProfile/> component won't automatically refresh. But since it's a hook, developers will expect it to – that's the whole point of React!
There are two high-level strategies to refreshing the hook, eager refresh and sequential refresh.
Eager refresh is the most performant solution, but it can be hard to configure. The idea is that the API endpoint behind
user.update() should return the updated User object in its response body. When the response is received,
user.update() can propogate the new value to any components calling
This example isn't particularly hard to configure because the mutation is contained to the
User object. It can be achieved with a globally-scoped React context to store the value of the User object, instead of using
useState directly in the
Eager refresh is much harder to configure when there are side effects involved. For example, at Clerk we have a
SignIn object that is responsible for tracking the state of a sign-in flow while the user completes their first and second factor. Once the user successfully signs in, it has the side effect of generating a
Session object, which changes the application's state from signed-out to signed-in.
We achieve eager refresh when a sign in completes by returning both the
SignIn object and
Session object from the server, but establishing a clean pattern for this has proven easier-said-than-done.
The alternative to eager refresh is sequential refresh, which is less performant but can be easier to configure, especially when side effects are possible.
Using our example above, instead of trying to return both
SignIn and the new
Session at once, the final
SignIn endpoint can instead return only the
When the client sees that the
SignIn is complete, though, it knows that a new
Session must exist. So, it can trigger a second request to retrieve the new
Two round-trips to the server will inherently be slower than one, but the development burden of eager refresh may make sequential refresh a viable alternative – especially as edge compute has made round-trips less costly over time.
Start completely free for up to 5,000 monthly active users and up to 10 monthly active orgs. No credit card required.
Learn more about our transparent per-user costs to estimate how much your company could save by implementing Clerk.
The latest news and updates from Clerk, sent to your inbox.