JavaScript Quickstart

You will learn how to:

Add the ClerkJS SDK to your JavaScript application
Use Clerk components to allow users to sign in or out

Before you start:

Set up a Clerk application

Example repository

JavaScript Quickstart Repo

You're reading the quickstart guide for the beta of the next major version of the Javascript SDK. For more information about the changes from the current version, check out the upgrade guide!

To add the ClerkJS SDK to your JavaScript application, you have two options:

Install the package using a package manager, like npm, yarn, or pnpm.
Use the <script> tag to load the ClerkJS package from our CDN.

Select your preferred method below to get started.

Set up a JavaScript application using Vite

To install the ClerkJS SDK, you will need to use a bundler like Vite(opens in a new tab) or Webpack(opens in a new tab) to use this method.

For the sake of this guide, scaffold your new JavaScript application using Vite(opens in a new tab). From the prompts, choose the Vanilla framework, and then choose the JavaScript variant.

terminal
npm create vite@latest clerk-javascript
cd clerk-javascript
npm install
npm run dev

terminal
yarn create vite clerk-javascript
cd clerk-javascript
yarn install
yarn dev

terminal
pnpm create vite clerk-javascript
cd clerk-javascript
pnpm install
pnpm dev

Install `@clerk/clerk-js`

At the root of your project, install the ClerkJS package using your package manager of choice:

terminal
npm install @clerk/clerk-js@beta

terminal
yarn add @clerk/clerk-js@beta

terminal
pnpm add @clerk/clerk-js@beta

Set environment variables

It's recommended to use environment variables to store your Clerk Publishable Key. A common way to use environment variables in a JavaScript project is by putting the values in an .env file and then loading them into your application using a package like dotenv(opens in a new tab). However, when using Vite, environment variables stored in an .env file at the project root are automatically exposed through the import.meta.env object(opens in a new tab).

Create an .env file at the root of your project, and add your Clerk Publishable Key. If you're signed into Clerk, the .env snippet below will contain your key. Otherwise, you can copy it from the Clerk Dashboard by navigating to the API Keys(opens in a new tab) page.

.env
VITE_CLERK_PUBLISHABLE_KEY={{pub_key}}

In your main.js file, import the publishable key using Vite's import.meta.env object.

main.js
const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

Initialize ClerkJS

To initialize the ClerkJS SDK, import the Clerk class and instantiate it with your Publishable Key. Then, call the load() method to initialize ClerkJS.

main.js
import Clerk from "@clerk/clerk-js";
 
const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
 
const clerk = new Clerk(clerkPubKey);
await clerk.load({
  // Set load options here
});

Calling the load() method initializes ClerkJS. For more information on the load() method and what options you can pass to it, check out the reference documentation.

Clerk's prebuilt components are the easiest way to add authentication and user management to your application. They come styled out of the box and are customizable to fit your application's design.

To get started, you will use:

<SignIn />: renders a user interface for signing in.
<UserButton />: shows the avatar from the account the user is signed in with. When clicked, it opens a dropdown menu with options to sign out.

Your main.js file should look something like this:

main.js
import Clerk from "@clerk/clerk-js";
 
const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
 
const clerk = new Clerk(clerkPubKey);
await clerk.load();
 
if (clerk.user) {
  document.getElementById("app").innerHTML = `
    <div id="user-button"></div>
  `;
 
  const userButtonDiv =
    document.getElementById("user-button");
 
  clerk.mountUserButton(userButtonDiv);
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;
 
  const signInDiv =
    document.getElementById("sign-in");
 
  clerk.mountSignIn(signInDiv);
}

And your index.html file should look something like this:

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>

Add the ClerkJS package using a `<script>` tag

This <script> tag will load the ClerkJS package from our CDN and initialize it with your Clerk Publishable Key and Frontend API URL. It should be placed before any other <script> tags that use ClerkJS.

Navigate to the Clerk Dashboard(opens in a new tab) and select your application.
In the navigation sidebar, select API Keys.
In the Quick Copy section, select JavaScript from the dropdown menu.
Copy the <script> tag and paste it into your HTML file.

It should look something like this:

index.html
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="{{pub_key}}"
  src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

In the <script> tag, the onload attribute is used to call the load() method when the ClerkJS package is loaded. This is necessary to initialize ClerkJS. For more information on the load() method and what options you can pass to it, check out the reference documentation.

Listen for the `load` event

After the ClerkJS package is loaded, you can listen for the load event to ensure that ClerkJS is ready to use.

Below the <script> tag that initializes ClerkJS, add another <script> tag to listen for the load event:

index.html
<script>
  window.addEventListener("load", async function () {
    await Clerk.load();
 
    console.log("ClerkJS is loaded");
  });
</script>

Clerk's prebuilt components are the easiest way to add authentication and user management to your application. They come styled out of the box and are customizable to fit your application's design.

To get started, you will use:

<SignIn />: renders a user interface for signing in.
<UserButton />: shows the avatar from the account the user is signed in with. When clicked, it opens a dropdown menu with options to sign out.

index.html
<div id="app"></div>
 
<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="{{pub_key}}"
  src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>
 
<script>
  window.addEventListener("load", async function () {
    await Clerk.load();
 
    if (Clerk.user) {
      document.getElementById("app").innerHTML = `
        <div id="user-button"></div>
      `;
 
      const userButtonDiv = document.getElementById("user-button");
 
      Clerk.mountUserButton(userButtonDiv);
    } else {
      document.getElementById("app").innerHTML = `
        <div id="sign-in"></div>
      `;
 
      const signInDiv = document.getElementById("sign-in");
 
      Clerk.mountSignIn(signInDiv);
    }
  });
</script>

More resouces

Clerk Class Reference

Learn more about the Clerk class and how to use it.

Learn More

Authentication Components

Learn more about all our authentication components.

Learn More

Customization & Localization

Learn how to customize and localize the Clerk components.

Learn More

Last updated on March 26, 2024

You will learn how to:

Before you start:

Set up a JavaScript application using Vite

Install @clerk/clerk-js

Set environment variables

Initialize ClerkJS

Allow users to sign in and out

Add the ClerkJS package using a <script> tag

Listen for the load event

Allow users to sign in or out

More resouces

Clerk Class Reference

Authentication Components

Customization & Localization

Install `@clerk/clerk-js`

Add the ClerkJS package using a `<script>` tag

Listen for the `load` event