Philosophy

Clerk believes that truly optimal developer experience can only be achieved by building SDKs independently for each framework. Each framework has nuanced patterns that should be embraced to avoid mismatched implementations.

This is why Clerk offers SDKs not only for React, but also for Next.js, Remix, Astro, and many other frameworks. Each framework has unique APIs, capabilities, and conventions, and dedicated SDKs provide better integration than a general-purpose SDK.

Here’s a non-exhaustive list of things to take into consideration to deliver a great developer experience.

Performance

Developers and marketers alike care about their website's performance scoring. Ensure efficient loading of your SDK and reduce bundle size & dependencies. Less dependencies also mean less maintenance and security concerns.

Enable best practices

For your SDK, follow the framework's or language's best practices and consider using their specialized patterns over generalized ones (e.g. special script loading). For your users, provide APIs to leverage those best practices.

Documentation

Spend time writing an exhaustive, yet organized README that enables your users to get started with your SDK. If you want to go above and beyond, create your own documentation site (recommended: Starlight). Provide examples on how to use your SDK, e.g. with a separate example repository.

Convenience

Make using your SDK as convenient as possible for its users. For example, provide pre-built components that users can import into their project. If the SDK can handle something under the hood which otherwise would require an action by the user, do it. Mimic the ease of use of Clerk's own SDKs.

Compatibility

Ensure compatibility with the upstream framework or language. Have reasonable backward compatibility.

API surface

Keep the API surface small. Most often you’ll only need to expose the options for the underlying Clerk SDKs and pass those through.

Testing

Add End-to-End tests to regularly test hot paths of your SDK. Functionality like sign-in, sign-up, and other UI components have high priority. Checkout the testing guide to learn which testing utilities are available and how to use Clerk's Testing Tokens to bypass bot detection.