┌────────────────────────────────────────────────────────────────────────────────────┐ │ 📄 shadcn/directory/clerk/clerk-docs/guides/development/sdk-development/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.
[!IMPORTANT] Optimize for the user’s developer experience. These principles, conventions, and instructions below are not strict rules. Use your best judgement to adjust as needed. Adhere to what makes most sense for the programming language or framework.
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.
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.
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.
Make using your SDK as convenient as possible for its users. For example, provide prebuilt 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.
Ensure compatibility with the upstream framework or language. Have reasonable backward compatibility.
Keep the API surface small. Most often you’ll only need to expose the options for the underlying Clerk SDKs and pass those through.
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.
║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║
╚══════════════════════════════════════════════════════════════════════════════════════════════╝