Announcing React-Netlify-Identity-Gotrue!

It’s Done!

After an extensive amount of research and effort, I’m very excited to release a comprehensive Netlify Identity integration for React apps (aimed squarely at Gatsby and Next.js but any React app will work). Written purely in React and following React Hooks methodologies without any dependencies, this thing kicks butt! I’m a bit biased.

This article intends to give a bit of background as to the ‘why’ this package was created, but for starters, here’s a bit of an overview of what’s just been released:

• https://gatsby-identity-demo.jonsully.net (The demo site!)
• gatsby-plugin-netlify-identity-gotrue-demo (Demo Site source code)
• gatsby-plugin-netlify-identity-gotrue (simple Gatsby Context bindings)
• react-netlify-identity-gotrue (the core of it all)

Starting from the bottom, react-netlify-identity-gotrue is the core of it all - it’s what provides the interface between a React app and Netlify’s Identity service with easy-to-use, well-documented bindings. It handles end-to-end auth workflows from invites, sign-ups, email confirmations, forgotten passwords, Authenticated Functions (e.g. Auth + Netlify Functions), flexible user metadata, and plenty more. It does all of that purely leveraging React Hooks and fetch - zero dependencies and powered by direct HTTP calls to your site’s Netlify Identity service.

Sitting above that, gatsby-plugin-netlify-identity-gotrue is a Gatsby plugin that automatically configures the NetlifyIdentityContext to wrap the Gatsby React tree root (so that identity is available everywhere in the site).

And consuming that plugin is the demo site - https://gatsby-identity-demo.jonsully.net / gatsby-plugin-netlify-identity-gotrue-demo.

Together, this stack provides both flexible layering and self-evident documentation into how to use the core react-netlify-identity-gotrue library. In addition, each of these repositories is well-documented and the react-netlify-identity-gotrue library contains an exhaustive description of each of the methods and values it exports. Give it a spin!

Alright but why?

So from a historical standpoint, there were two primarily available ‘stacks’ for consuming Netlify Identity prior to this package-set being released. The first was authored by Netlify themselves and consists of the following layers:

• netlify-identity-widget (display / UI layer and event binding glue)
• gotrue-js (core functionality and HTTP API interface)

And the second was authored by @sw-yx back when he worked with Netlify and involves a couple extra layers, but this stack is the current major means of integrating Netlify Identity into React. The layers are as follows:

• gatsby-plugin-netlify-identity (below + Gatsby bindings for easy setup)
• react-netlify-identity-widget (below + UI / display layer)
• react-netlify-identity (React interops and bindings)
• gotrue-js (core functionality and HTTP API interface)

So if two perfectly-fine integrations exist to implement Netlify Identity, why bother making a third? The answer lies in gotrue-js. The short story is that gotrue-js is a ‘vanilla-js’ library - it’s not connected to or aware of the React runtime at all. This can present issues when attempting to interface or interop with React. State can fall out of sync slightly, certain processes can’t get run exactly correctly, and generally things tend to be a little dirty. In the case of the former stack above, there are no React bindings at all. In order to interface with React you’d need to interact with events passed directly from window.

Additionally, the latter stack above doesn’t fully implement the needs of an Identity-enabled site. Password resets, email address changes, invitation tokens, etc. All of these things are critical for a production-ready app but aren’t supported by the latter stack above.

Putting these issues together, it felt like there was an opportunity to create a fully-featured pure-React integration for Netlify Identity that takes away the pain of cross-library interops and gives Application devs the ability to use the full Netlify Identity pipeline. react-netlify-identity-gotrue was built out of countless hours of digesting gotrue-js and gotrue code to re-engineer GoTrue’s HTTP API in React with a number of asynchronous hooks and state controls. It also takes into account so many hours spent with various members of The Community (feel free to find me there!) determining what feels hard, what feels broken, and what feels.. ergonomically bad. This library attempts to fix a number of those things and provide React developers with a single, unified interface for fully integrating Netlify Identity into their projects.

How do I get started?

Well for starters, go play around with the demo site! See if you can break it or if you can hack it. Then read the code underneath it and get an understanding of how the identity API works. You can follow that up by giving the react-netlify-identity-gotrue README a solid read-through to get a more fine-grain sense for what-goes-where, then finally you can build your own Gatsby, Next.js, or Create-React-App site that integrates react-netlify-identity-gotrue (or gatsby-plugin-netlify-identity-gotrue for Gatsby)!

Hope you enjoy!

-

Jon

Comments? Thoughts?

Reply

Replying to ...
Cancel

Full Name

Email

Comment

Please note: spam comments happen a lot. All submitted comments are run through OpenAI to detect and block spam.