Feedback on new "SDK Development" spec?

[LekoArts]

Hello @Hawxy 👋

First and foremost, thanks for creating this SDK and maintaining it — it's much appreciated! I'm currently an employee at Clerk and most recently worked on a new set of guides: SDK development

They lay out fundamentals like terminology, philosophy, and conventions. Then go into more details on how to create frontend-only, backend-only, and fullstack SDKs. We want to make it easier for all contributors to create and maintain Clerk SDKs.

While I'd be eager to hear your feedback on these new set of guides (however detailed as you like), I recognise that you're doing this (most probably) in your free time so don't feel obliged to answer my ask here 😊 I didn't find any contact information so I've opted to create a discussion here, if you want to continue over email you can reach me at [email protected].

Questions:

1. Are you missing any crucial information on https://clerk.com/docs/references/sdk/terminology that would make understanding Clerk's flow and its source code easier?
2. Since this SDK is a wrapper around the Backend OpenAPI spec, are you missing any crucial information in https://clerk.com/docs/references/sdk/backend-only that would have helped in creating this SDK?
3. Any other feedback? Please let me know!

Thanks again and have a great day!

[Hawxy]

Hi @LekoArts,
Thanks for putting those pages together, that's a nice consolidation of info that I had to go hunting for in the past.

Are you missing any crucial information on https://clerk.com/docs/references/sdk/terminology that would make understanding Clerk's flow and its source code easier?

This page is good.

Since this SDK is a wrapper around the Backend OpenAPI spec, are you missing any crucial information in https://clerk.com/docs/references/sdk/backend-only that would have helped in creating this SDK?

Nothing specific to generating a client, but I do have other feedback:

• Verifying the __session cookie and dealing with a Handshake feels like it should be suggested for Backend SDKs and only be a requirement for a Fullstack SDK. Batteries-included backend frameworks such as ASP.NET Core have very robust JWT support (validating Clerk JWTs is a few lines of code), and it's a similar story in neighboring frameworks in Java. Even in same-origin scenarios I would typically expect users to use JWT Header auth as it's significantly simpler to deal with on the backend and avoids the need to install/configure another dependency. At the same time, I understand if your goals are to keep the behavior identical across all frameworks.

• The Handshake flow should really have some pseudocode provided of what it's supposed to do with the request if the intention is for other languages to implement it. The current example just goes into the black box of the JS SDK for most of the logic.

Any other feedback?

Guidelines for Clerk logo usage would be nice. If we're permitted to use the Clerk logo in the readme/package icons etc.

[LekoArts]

Ok, so I've corrected the https://clerk.com/docs/references/sdk/backend-only page, only the fullstack SDK asks for handshake support now (your feedback was correct and we actually want it that way).

And you're absolutely right, the handshake flow right now is a black box and we need to explain this (in addition to other things on how Clerk works). I'll see that we get a PR like clerk/clerk-docs#577 over the finish line and then we can link to that, too.

[Hawxy]

Great to hear. One last thing I noticed; Redwood has docs built into the Clerk documentation (probably because it was the first community SDK added), was providing first party docs for community SDKs something you were interested in continuing or would you rather keep it all contained to the third party?

[LekoArts]

I didn't find out exactly why the Redwood docs were added, but in a meeting yesterday the topic you're talking about (Docs for community SDKs) was brought up, too.

Would you be interested in having the docs for this SDK to be hosted on clerk.com in contrast to hosting it on your own?

[Hawxy]

It's easier as a maintainer to have control over my own docs, and it's less overhead for your team not having to review doc updates from a dozen or so packages. That being said, having a "quick start" on the clerk docs with a link to visit the package's docs/repo for more information isn't a terrible idea if you wanted something on your side.

[LekoArts]

Gotcha. We'll factor in your opinion on this but right now we're leaning towards not including (complete) docs (and giving maintainers control over that).