Installation

Learn how to make ClerkJS available in your project.

Overview

ClerkJS is our foundational JavaScript library for building user management and authentication. It enables you to register, sign in, verify and manage users for your application using highly customizable flows.

The primary integration path through ClerkJS is with Clerk Components, as ClerkJS provides the foundation upon which all Clerk's UI offerings are built. However, integrating with ClerkJS directly gives you full freedom to use Clerk any way you see fit, dropping down to a lower level of primitives and commands for sign-ins, sign-ups, and user profile management.

Looking for a quickstart? We created a demo app to show you how to add Clerk to your project.

Setting up ClerkJS

There are two ways you can include ClerkJS in your project. You can either import the ClerkJS npm module or load ClerkJS directly in your browser.

In either case, after the ClerkJS library is loaded, you need to call the Clerk.load() method to initialize ClerkJS, passing the desired options.

You need to create a Clerk Application in your Clerk Dashboard before you can set up ClerkJS. For more information, check out our Set up your application guide.

Using ClerkJS as a module

There's an ES module for ClerkJS, available under the @clerk/clerk-js npm package. Use npm or yarn to install the ClerkJS module.

# Install the package with npm.
npm install @clerk/clerk-js

# Alternative install method with yarn.
yarn add @clerk/clerk-js

Once you've installed the ClerkJS package, you first have to import it in your own code. The Clerk object constructor needs the publishable_key as a parameter. You can find the publishable_key on the API Keys page.

import Clerk from "@clerk/clerk-js";
const publishableKey = your_publishable_key

const clerk = new Clerk(publishableKey);
await clerk.load({
  // Set load options here...
});

Loading ClerkJS as a script

You can also load ClerkJS with a <script/> tag in your website, straight from your Frontend API URL. You can find the URL on the API Keys page.

For security reasons, the ClerkJS library can only be loaded from the same domain. Make sure your website runs on the same domain as your Frontend API.

Add the following script in your site's <body> element.

<script> 
    const frontend_api = "your-frontend-api-key;
  
  // Create a script that will be loaded asynchronously in 
  // your page. 
  const script = document.createElement('script');
  script.setAttribute('data-clerk-frontend-api', frontend_api);
  script.async = true;
  script.src = `https://cdn.jsdelivr.net/npm/@clerk/clerk-js@latest/dist/clerk.browser.js`;
  script.crossOrigin = "anonymous";
  // Add a listener so you can initialize ClerkJS
  // once it's loaded.
  script.addEventListener('load', async function(){
    await window.Clerk.load({
      // Set load options here...
    });
  });
  document.body.appendChild(script);
</script>

TypeScript support

The ClerkJS npm package includes TypeScript declarations for many of the objects returned from the Clerk Frontend API.

The type declarations in @clerk/clerk-js for these objects will always track the latest version of the Clerk Frontend API. If you would like to use these types but are using an older version of the Clerk Frontend API, we recommend updating to the latest version, or ignoring and overriding the type definitions as necessary.

Note that we may release new minor and patch versions of @clerk/clerk-js with small but backwards-incompatible fixes to the type declarations. These changes will not affect ClerkJS itself.