Docs

Conventions

Ideally, when a user switches from one Clerk SDK to another, the general concepts, feature set, names, and exports should be consistent. By following certain conventions, you can develop an SDK that achieves this ideal state, making it easier for users to quickly start a new project.

SDK name

Note

If there are strong conventions for your specific framework/language, default to those. Otherwise, follow the guidance below.

Add “Clerk” as a prefix or postfix into the name as it’ll make the SDK easier to discover. Here are some real world examples:

  • vue-clerk (Vue)
  • clerk-rs (Rust)
  • @hono/clerk-auth (Hono)
  • Clerk.Net (C#)

Environment variables

Any environment variable used in the context of Clerk should be prefixed with CLERK_. Learn more about Clerk environment variables.

Note

Depending on your framework, you’ll need to add a prefix to environment variables that should be available on the frontend. For example, PUBLIC_, VITE_ or NEXT_PUBLIC. These alterations are fine.

Required

You should always support these environment variables:

  • CLERK_PUBLISHABLE_KEY (Frontend-only, fullstack)
  • CLERK_SECRET_KEY (Backend-only, fullstack)

Additionally, you need to make the environment variables for API and SDK configuration available to your users.

Warning

The CLERK_SECRET_KEY should never be exposed on the client-side (frontend). Always use a server-side environment variable.

Optional

Clerk recommends implementing the sign-in and sign-up redirect environment variables.

README

The README is most often the first thing a user sees of your SDK, so it's paramount to include all the crucial information.

Use the template below to setup your own README.

README.md
# clerk-sdk-name

<!-- Give an overview. Explain what the SDK does and what one can use it for. Link out to clerk.com when mentioning Clerk -->

## Getting started

### Prerequisites

- If you haven't already, [sign up for an account](https://dashboard.clerk.com/sign-up) and create a new application. Go to the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page to retrieve your Publishable Key and/or Secret Key.

<!-- Mention any other necessary steps a user has to perform before continuing. Mention any hard requirements e.g. like minimum supported Node.js version. -->

### Installation

```shell
# Install command for SDK
```

## Usage

<!-- Explain how to use the Publishable Key and/or Secret Key, e.g. by placing them into an .env file -->

<!-- Explain how to use your SDK! -->

## License

<!-- State which license your library falls under, Clerk recommends MIT -->

Publishing to npm

While this reference can't cover the whole surface area of publishing a package to npm, there are a couple of conventions Clerk uses for their own SDKs to deliver a great developer experience.

Tip

Clerk recommends reading The Modern Guide to Packaging your JavaScript library to get more familiar with common terms and problems. It's also recommended to use publint and arethetypeswrong to validate your package before publishing. You can use both tools as a CLI, too.

Provide TypeScript types for your SDK

This is the biggest benefit you can provide to your users, as they'll get IntelliSense autocompletion in their IDE.

You can achieve this by authoring your SDK in TypeScript or providing a hand-written file. Enable the declaration setting in your tsconfig.json.

When only defining a main entry point, use the types key. Otherwise, for conditional exports, use the types key inside the exports field.

Use subpath exports

Use subpath exports to provide API boundaries, enable more efficient code-splitting, and split code between client & server.

Here's how the @clerk/astro package is using subpath exports:

  • @clerk/astro/react - Import Clerk's prebuilt React components
  • @clerk/astro/client - Access to useful stores like $authStore
  • @clerk/astro/server - Import Clerk's middleware

This setup ensures that functions that only work on the server are not bundled into client-side code. It also makes it easier for the bundler to tree-shake any unused code.

CommonJS/ES Module

Authoring dual packages is challenging, but not impossible. Before deciding to publish in both CommonJS (CJS) and ES Module (ESM) formats, consider whether you can publish solely in the ESM format. Most modern frameworks support ESM-only packages.

Build tools that can help you build dual and ESM-only packages:

Define peerDependencies and engines

Your SDK will require your users to have Node.js installed and use the framework the SDK is built for. To ensure compatibility, define peerDependencies and engines in your package.json.

Generate provenance statements

Security is important at Clerk and thus all Clerk SDKs are published with provenance statements. This allows you to publicly establish where a package was built and who published a package, which can increase supply-chain security for your packages.

Read npm's guide on generating provenance statements.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on