More resouces

JavaScript Quickstart

You will learn the following:

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

Note

The next major version of the Clerk Javascript SDK is coming soon! If you're just starting a project, consider trying out the Core 2 beta instead.

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.

NPM module

Set up a JavaScript application using Vite

To install the ClerkJS SDK, you will need to use a bundler like Vite or Webpack to use this method.

For the sake of this guide, scaffold your new JavaScript application using Vite. From the prompts, choose the Vanilla framework, and then choose the JavaScript variant.

npm

yarn

pnpm

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:

npm

yarn

pnpm

terminal

npm install @clerk/clerk-js

terminal

yarn add @clerk/clerk-js

terminal

pnpm add @clerk/clerk-js

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. However, when using Vite, environment variables stored in an .env file at the project root are automatically exposed through the import.meta.env object.

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 page.

.env

VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_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
});

Note

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 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="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_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="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_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>

Last updated on Aug 20, 2024

JavaScript Quickstart

You will learn the following:

Before you start

Example repository

Set up a JavaScript application using Vite

Install `@clerk/clerk-js`

Set environment variables

Initialize ClerkJS

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

Listen for the `load` event

More resouces

Clerk Class Reference

Authentication Components

Customization & Localization

JavaScript Quickstart

You will learn the following:

Before you start

Example repository

Feedback